Package com.sun.jna.platform.mac

Interface CoreFoundation

  • All Superinterfaces:
    Library
    public interface CoreFoundation
extends Library
    Core Foundation is a framework that provides fundamental software services useful to application services, application environments, and to applications themselves. Core Foundation also provides abstractions for common data types.

    Core Foundation functions have names that indicate when you own a returned object: Object-creation functions have “Create” embedded in the name, and Object-duplication functions that have “Copy” embedded in the name. If you own an object, it is your responsibility to relinquish ownership (using CFRelease(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef)) when you have finished with it.

    If you receive an object from any Core Foundation function other than a creation or copy function—such as a Get function—you do not own it and cannot be certain of the object’s life span. If you want to ensure that such an object is not disposed of while you are using it, you must claim ownership (with the CFRetain(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef) function).

    • Method Detail

      • CFStringCreateWithCharacters

        CoreFoundation.CFStringRef CFStringCreateWithCharacters​(CoreFoundation.CFAllocatorRef alloc,
                                                        char[] chars,
                                                        CoreFoundation.CFIndex length)
        Creates a string from a buffer of Unicode characters.

        This reference must be released with CFRelease(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef) to avoid leaking references.

        Parameters:
        alloc - The allocator to use to allocate memory for the new string. Pass null or kCFAllocatorDefault to use the current default allocator.
        chars - The buffer of Unicode characters to copy into the new string.
        length - The number of characters in the buffer pointed to by chars. Only this number of characters will be copied to internal storage.
        Returns:
        An immutable string containing chars, or null if there was a problem creating the object.

      • CFArrayCreate

        CoreFoundation.CFArrayRef CFArrayCreate​(CoreFoundation.CFAllocatorRef alloc,
                                        Pointer values,
                                        CoreFoundation.CFIndex numValues,
                                        Pointer callBacks)
        Creates a new immutable array with the given values.

        This reference must be released with CFRelease(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef) to avoid leaking references.

        Parameters:
        alloc - The allocator to use to allocate memory for the new array and its storage for values. Pass null or kCFAllocatorDefault to use the current default allocator.
        values - A C array of the pointer-sized values to be in the new array. The values in the new array are ordered in the same order in which they appear in this C array. This value may be null if numValues is 0. This C array is not changed or freed by this function. If values is not a valid pointer to a C array of at least numValues elements, the behavior is undefined.
        numValues - The number of values to copy from the values C array into the new array. This number will be the count of the new array—it must not be negative or greater than the number of elements in values.
        callBacks - A pointer to a CFArrayCallBacks structure initialized with the callbacks for the array to use on each value in the collection. The retain callback is used within this function, for example, to retain all of the new values from the values C array. A copy of the contents of the callbacks structure is made, so that a pointer to a structure on the stack can be passed in or can be reused for multiple collection creations.

        This value may be null, which is treated as if a valid structure of version 0 with all fields null had been passed in.

        Returns:
        A new immutable array containing numValues from values, or null if there was a problem creating the object.

      • CFDataCreate

        CoreFoundation.CFDataRef CFDataCreate​(CoreFoundation.CFAllocatorRef alloc,
                                      Pointer bytes,
                                      CoreFoundation.CFIndex length)
        Creates an immutable CFData object using data copied from a specified byte buffer.

        This reference must be released with CFRelease(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef) to avoid leaking references.

        Parameters:
        alloc - The allocator to use to allocate memory for the new object. Pass null or kCFAllocatorDefault to use the current default allocator.
        bytes - A pointer to the byte buffer that contains the raw data to be copied into the Data.
        length - The number of bytes in the buffer (bytes).
        Returns:
        A new CFData object, or null if there was a problem creating the object.

      • CFDictionaryCreateMutable

        CoreFoundation.CFMutableDictionaryRef CFDictionaryCreateMutable​(CoreFoundation.CFAllocatorRef alloc,
                                                                CoreFoundation.CFIndex capacity,
                                                                Pointer keyCallBacks,
                                                                Pointer valueCallBacks)
        Creates a new mutable dictionary.

        This reference must be released with CFRelease(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef) to avoid leaking references.

        Parameters:
        alloc - The allocator to use to allocate memory for the new string. Pass null or kCFAllocatorDefault to use the current default allocator.
        capacity - The maximum number of key-value pairs that can be contained by the new dictionary. The dictionary starts empty and can grow to this number of key-value pairs (and it can have less).

        Pass 0 to specify that the maximum capacity is not limited. The value must not be negative.

        keyCallBacks - A pointer to a CFDictionaryKeyCallBacks structure initialized with the callbacks to use to retain, release, describe, and compare keys in the dictionary. A copy of the contents of the callbacks structure is made, so that a pointer to a structure on the stack can be passed in or can be reused for multiple collection creations.

        This value may be null, which is treated as a valid structure of version 0 with all fields null.

        valueCallBacks - A pointer to a CFDictionaryValueCallBacks structure initialized with the callbacks to use to retain, release, describe, and compare values in the dictionary. A copy of the contents of the callbacks structure is made, so that a pointer to a structure on the stack can be passed in or can be reused for multiple collection creations.

        This value may be null, which is treated as a valid structure of version 0 with all fields null.

        Returns:
        A new dictionary, or null if there was a problem creating the object.

      • CFCopyDescription

        CoreFoundation.CFStringRef CFCopyDescription​(CoreFoundation.CFTypeRef cf)
        Returns a textual description of a Core Foundation object.

        The nature of the description differs by object. For example, a description of a CFArray object would include descriptions of each of the elements in the collection.

        You can use this function for debugging Core Foundation objects in your code. Note, however, that the description for a given object may be different in different releases of the operating system. Do not create dependencies in your code on the content or format of the information returned by this function.

        Parameters:
        cf - The CFType object (a generic reference of type CFTypeRef) from which to derive a description.
        Returns:
        A string that contains a description of cf.

      • CFRelease

        void CFRelease​(CoreFoundation.CFTypeRef cf)
        Releases a Core Foundation object.

        If the retain count of cf becomes zero the memory allocated to the object is deallocated and the object is destroyed. If you create, copy, or explicitly retain (see the CFRetain(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef) function) a Core Foundation object, you are responsible for releasing it when you no longer need it.

        Parameters:
        cf - A CFType object to release. This value must not be null.

      • CFGetRetainCount

        CoreFoundation.CFIndex CFGetRetainCount​(CoreFoundation.CFTypeRef cf)
        Returns the reference count of a Core Foundation object.
        Parameters:
        cf - The CFType object to examine.
        Returns:
        A number representing the reference count of {code cf}.

      • CFDictionaryGetValue

        Pointer CFDictionaryGetValue​(CoreFoundation.CFDictionaryRef theDict,
                             PointerType key)
        Returns the value associated with a given key.
        Parameters:
        theDict - The dictionary to examine.
        key - The key for which to find a match in theDict. The key hash and equal callbacks provided when the dictionary was created are used to compare. If the hash callback was null, the key is treated as a pointer and converted to an integer. If the equal callback was null, pointer equality (in C, ==) is used. If key, or any of the keys in theDict, is not understood by the equal callback, the behavior is undefined.
        Returns:
        The value associated with key in theDict, or null if no key-value pair matching key exists. Since null is also a valid value in some dictionaries, use CFDictionaryGetValueIfPresent(com.sun.jna.platform.mac.CoreFoundation.CFDictionaryRef, com.sun.jna.PointerType, com.sun.jna.ptr.PointerByReference) to distinguish between a value that is not found, and a null value.

      • CFDictionaryGetValueIfPresent

        byte CFDictionaryGetValueIfPresent​(CoreFoundation.CFDictionaryRef theDict,
                                   PointerType key,
                                   PointerByReference value)
        Returns a boolean value that indicates whether a given value for a given key is in a dictionary, and returns that value indirectly if it exists.
        Parameters:
        theDict - The dictionary to examine.
        key - The key for which to find a match in theDict. The key hash and equal callbacks provided when the dictionary was created are used to compare. If the hash callback was null, the key is treated as a pointer and converted to an integer. If the equal callback was null, pointer equality (in C, ==) is used. If key, or any of the keys in theDict, is not understood by the equal callback, the behavior is undefined.
        value - A pointer to memory which, on return, is filled with the pointer-sized value if a matching key is found. If no key match is found, the contents of the storage pointed to by this parameter are undefined. This value may be null, in which case the value from the dictionary is not returned (but the return value of this function still indicates whether or not the key-value pair was present).
        Returns:
        1 if a matching key was found, otherwise 0.

      • CFDictionarySetValue

        void CFDictionarySetValue​(CoreFoundation.CFMutableDictionaryRef theDict,
                          PointerType key,
                          PointerType value)
        Sets the value corresponding to a given key.
        Parameters:
        theDict - The dictionary to modify. If this parameter is a fixed-capacity dictionary and it is full before this operation, and the key does not exist in the dictionary, the behavior is undefined.
        key - The key of the value to set in theDict. If a key which matches key is already present in the dictionary, only the value for the key is changed ("add if absent, replace if present"). If no key matches key, the key-value pair is added to the dictionary.

        If a key-value pair is added, both key and value are retained by the dictionary, using the retain callback provided when theDict was created. key must be of the type expected by the key retain callback.

        value - The value to add to or replace in theDict. value is retained using the value retain callback provided when theDict was created, and the previous value if any is released. value must be of the type expected by the retain and release callbacks.

      • CFStringGetCString

        byte CFStringGetCString​(CoreFoundation.CFStringRef theString,
                        Pointer bufferToFill,
                        CoreFoundation.CFIndex bufferSize,
                        int encoding)
        Copies the character contents of a string to a local C string buffer after converting the characters to a given encoding.
        Parameters:
        theString - The string whose contents you wish to access.
        bufferToFill - The C string buffer into which to copy the string. On return, the buffer contains the converted characters. If there is an error in conversion, the buffer contains only partial results.

        The buffer must be large enough to contain the converted characters and a NUL terminator.

        bufferSize - The length of buffer in bytes.
        encoding - The string encoding to which the character contents of theString should be converted. The encoding must specify an 8-bit encoding.
        Returns:
        1 upon success or 0 if the conversion fails or the provided buffer is too small.

      • CFBooleanGetValue

        byte CFBooleanGetValue​(CoreFoundation.CFBooleanRef bool)
        Returns the value of a CFBoolean object.
        Parameters:
        bool - The boolean to examine.
        Returns:
        1 if the value of bool is true, 0 otherwise.

      • CFArrayGetValueAtIndex

        Pointer CFArrayGetValueAtIndex​(CoreFoundation.CFArrayRef theArray,
                               CoreFoundation.CFIndex idx)
        Retrieves a value at a given index.
        Parameters:
        theArray - The array to examine.
        idx - The index of the value to retrieve. If the index is outside the index space of theArray (0 to N-1 inclusive (where N is the count of theArray)), the behavior is undefined.
        Returns:
        The value at the idx index in theArray).

      • CFNumberGetValue

        byte CFNumberGetValue​(CoreFoundation.CFNumberRef number,
                      CoreFoundation.CFIndex theType,
                      ByReference valuePtr)
        Obtains the value of a CFNumber object cast to a specified type.
        Parameters:
        number - The CFNumber object to examine.
        theType - A constant that specifies the data type to return. See CoreFoundation.CFNumberType for a list of possible values.
        valuePtr - On return, contains the value of number.
        Returns:
        1 if the operation was successful, otherwise 0.

      • CFStringGetLength

        CoreFoundation.CFIndex CFStringGetLength​(CoreFoundation.CFStringRef theString)
        Returns the number (in terms of UTF-16 code pairs) of Unicode characters in a string.
        Parameters:
        theString - The string to examine.
        Returns:
        The number (in terms of UTF-16 code pairs) of characters stored in theString.

      • CFStringGetMaximumSizeForEncoding

        CoreFoundation.CFIndex CFStringGetMaximumSizeForEncoding​(CoreFoundation.CFIndex length,
                                                         int encoding)
        Returns the maximum number of bytes a string of a specified length (in Unicode characters) will take up if encoded in a specified encoding.
        Parameters:
        length - The number of Unicode characters to evaluate.
        encoding - The string encoding for the number of characters specified by length.
        Returns:
        The maximum number of bytes that could be needed to represent length number of Unicode characters with the string encoding encoding, or kCFNotFound if the number exceeds Long.MAX_VALUE.

      • CFDataGetLength

        CoreFoundation.CFIndex CFDataGetLength​(CoreFoundation.CFDataRef theData)
        Returns the number of bytes contained by a CFData object.
        Parameters:
        theData - The CFData object to examine.
        Returns:
        An index that specifies the number of bytes in theData.

      • CFDataGetBytePtr

        Pointer CFDataGetBytePtr​(CoreFoundation.CFDataRef theData)
        Returns a read-only pointer to the bytes of a CFData object.
        Parameters:
        theData - The CFData object to examine.
        Returns:
        A read-only pointer to the bytes associated with theData.

      • CFArrayGetTypeID

        CoreFoundation.CFTypeID CFArrayGetTypeID()
        Returns:
        The type identifier for the CFArray opaque type.

      • CFBooleanGetTypeID

        CoreFoundation.CFTypeID CFBooleanGetTypeID()
        Returns:
        The type identifier for the CFBoolean opaque type.

      • CFDateGetTypeID

        CoreFoundation.CFTypeID CFDateGetTypeID()
        Returns:
        The type identifier for the CFDate opaque type.

      • CFDataGetTypeID

        CoreFoundation.CFTypeID CFDataGetTypeID()
        Returns:
        The type identifier for the CFData opaque type.

        CFMutableData objects have the same type identifier as CFData objects.

      • CFDictionaryGetTypeID

        CoreFoundation.CFTypeID CFDictionaryGetTypeID()
        Returns:
        The type identifier for the CFDictionary opaque type.

        CFMutableDictionary objects have the same type identifier as CFDictionary objects.

      • CFNumberGetTypeID

        CoreFoundation.CFTypeID CFNumberGetTypeID()
        Returns:
        The type identifier for the CFNumber opaque type.

      • CFStringGetTypeID

        CoreFoundation.CFTypeID CFStringGetTypeID()
        Returns:
        The type identifier for the CFString opaque type.