======================== BridgeSupport XML format ======================== ------------------- A short description ------------------- Introduction ============ This file describes the metadata files used by PyObjC. The metadata files started out as a shared project used by PyObjC and RubyCocoa, but the format used by PyObjC has diverged a little from that shared format. FIXME: verify if the description in this file still matches reality, and if the definition is clear enough. Changes from the shared format ------------------------------ * PyObjC uses a number of additional format characters in type descriptors: - 'T': a character of type ``UniChar`` - 't': a character of type ``char`` - 'z': a small integer of type ``char`` - 'Z': a value of type 'bool' * PyObjC adds the attribute "block" to the "arg" and "retval" elements. * PyObjC adds the attribute "c_array_delimited_by_null" to the "function" and "method" elements. FIXME: There are other little differences in the semantics of the metadata file (such as when to add in/out/inout annotations to "void*" arguments). These need to be described better (including the rationale for PyObjC's behaviour). Document structure ================== The document is an ``signatures`` element with an optional ``version`` attribute. This document describes version ``pyobjc-2.2``. The child elements of the ``signatures`` describe the various objects that can be wrapped. Classes are special: instead of describing all classes in the metadata we only describe classes and methods that require special treatment, that is those were the normal Objective-C runtime metadata doesn't contain enough information to wrap them correctly. The following section describe the various elements in the metadata format. 64-bit support -------------- The metadata file supports 32-bit and 64-bit builds in a single file. This is done by adding a 64-bit version of attributes when the attribute has different values on 64-bit and 32-bit builds. When the 64-bit version is not present the value is assumed to be the same as on 32-bit builds. BOOLEAN attributes ------------------ Attributes that are marked as ``BOOLEAN`` can have two values: ``true`` or ``false`` (with the obvious interpretation for those values). ``depends_on`` -------------- This elements is used to describe direct framework dependencies. Attributes: * ``path``: Absolute path to the framework ``constant`` ------------ This element is used to describe C-level variables that refer to constants ( such as "``NSString* NSWorkspaceCopyOperation``). Attributes: * ``name``: Name of the constant * ``type``, ``type64``: Encoded type of the constant. * ``magic_cookie`` (BOOLEAN): if true this is a magic value, not a real object. Note that the *value* of the constant is not described, this can be retrieved from the actual framework using the ``CFBundle`` API. ``enum`` -------- This element is used to describe ``enum`` labels and ``#define``-s that map onto numbers. Attributes: * ``name``: name of the constant * ``value``, ``value64``: the value of the constant. If the value contains a dot (``"."``) the value is a floating-point number, otherwise it is an integer (of arbitrary size). * ``be_value``, ``le_value``: when a constant has a different value on big- and little-endian systems the ``value`` attribute won't be present and these two will be. There will be very few values without a ``value`` attribute, basically only "four character codes". ``string_constant`` ------------------- This element is used to describe ``#define``-s that map onto string values (either C-style strings or literal NSString values). Attributes: * ``name``: name of the contant * ``value``, ``value64``: the value of the constant The value is the value of the literal. * ``nsstring`` (BOOLEAN): if true the value is an NSString, otherwise it is a plain C string (defaults to ``false``). ``null_const`` -------------- This is used to describe null-pointer aliases. Attributes: * ``name``: name of the value The C value of these values is always ``NULL`` and these should be mapped onto a "no-value" value by the brides (such as ``None`` in Python). ``cftype`` ----------- This element describes CoreFoundation based types. Attributes: * ``name``: name of the type (such as ``CFArrayRef``). * ``type``, ``type64``: Encoding string for this type * ``tollfree``: if available this type is toll-free bridged to the named Objective-C class * ``gettypeid_func``: if available this is the function that should be called to get the ``CFTypeID`` for this type. This attribute must be present if ``tollfree`` isn't present and is optional otherwise. ``opaque`` ----------- Used to describe opaque types, that is 'pointer to struct' types where the fields of the struct aren't public. Attributes: * ``name``: name of the type (such as ``NSZone``) * ``type``, ``type64``: Encoding string for this type ``struct`` ---------- Used to describe structs that are defined in the framework. Attributes: * ``name``: name of the struct * ``type``, ``type64``: Encoding string for the this type. This is a verbose encoding that includes the field names, which isn't the same as the result of ``@encode(name)``. ``informal_protocol`` --------------------- This element describes informal protocols (but not formal ones, those can be extracted from the Objective-C runtime). Attributes: * ``name``: name of the informal protocol This element has subelements that describe the methods that are part of the protocol. All subelements have ``method`` as their tag. ``method`` ........... The ``method`` subelement of ``informal_protocol`` has the following attributes: * ``selector``: name of the method * ``classmethod`` (BOOLEAN): is this a class method? Defaults to ``false``. * ``encoding``, ``encoding64``: encoding of the method signature, as it would exist in the Objective-C runtime * ``suggestion``: This method shouldn't be used. The attribute value contains a human-reable message. * ``variadic`` (BOOLEAN): If true this is a varargs method, defaults to ``false``. ``class`` --------- This attribute is used to describe classes in the framework that contain methods were the metadata in the Objective-C runtime isn't good enough to wrap them. Attributes: * ``name``: name of the class This element has subelements of type ``method`` for all methods that require further annotations. Furthermore subelements of type ``property`` are used to describe Objective-C 2.0 properties that aren't present in the header files. ``method`` .......... This is used to describe metadata for methods, and only those bits of metadata that cannot be derived from the information in the Objective-C runtime. Attributes: * ``selector``: The method name * ``classmethod`` (BOOLEAN): Is this a class method? Defaults to ``false`` * ``suggestion``: This method shouldn't be used. The attribute value contains a human-reable message. * ``variadic`` (BOOLEAN): If true this is a varargs function, defaults to false * ``c_array_delimited_by_null`` (BOOLEAN): Only valid when variadic is true, defaults to ``False``. The variadic arguments are a null-terminated array. This element has subelements ``retval`` (present at most once) and ``argument`` (can be present multiple times) to describe the return value and arguments. See the section `Method and function argument and return values`_ for more information on these elements. When the ``suggestion`` attribute is present the bridge should emit a warning containing the suggestion. It may not be possible to call the method at all. ``function`` ------------ This is used to describe functions in the framework. Attributes * ``name``: Function name * ``suggestion``: This method shouldn't be used. The attribute value contains a human-reable message. * ``variadic`` (BOOLEAN): If true this is a varargs function, defaults to false * ``c_array_delimited_by_null`` (BOOLEAN): Only valid when variadic is true, defaults to ``False``. The variadic arguments are a null-terminated array. * ``inline`` (BOOLEAN): If true the function is a static inline function NOTE: static inline functions cannot be loading from a bundle using the CFBundle APIs because they aren't included as public functions. A bridge will have to implement some other mechanism to make this functions available. This element has subelements ``retval`` (present at most once) and ``argument`` (can be present multiple times) to describe the return value and arguments. See the section `Method and function argument and return values`_ for more information on these elements. When the ``retval`` element is not present the function returns ``void``. All function arguments will be present in the right order and don't need an ``index`` attribute. When the ``suggestion`` attribute is present the bridge should emit a warning containing the suggestion. It may not be possible to call the function at all. Method and function argument and return values ----------------------------------------------- ``retval`` ........... Attributes * ``already_retained`` (BOOLEAN): If true the function returns an object that is already retained, that is the user is responsible for releasing the object when it is no longer needed. Only valid when the return type is an object (either a ``NSObject*`` or a ``CFTypeRef``). Defaults to ``false``. * ``type``, ``type64``: The return type. Only present when this is different from the information in the Objective-C runtime. * ``c_array_length_in_arg``: The return value is an array whose length is present in another argument. The value is the index of the argument that contains the array size. This argument must be an integer or NSRange value or an ``inout`` or ``out`` argument of type integer. If the value is a (pointer to a) value of type NSRange the ``length`` is used as the array size. The value can also be two integers seperated by a comma, in which cases the first integer is the index of the argument that contains the length of the array on input and the second is index of the argument that contains the size on output. * ``c_array_delimited_by_null`` (BOOLEAN): The return value is a NULL-terminated array. The basic type of the array must be a pointer-type (object, opaque) or an integer type (in which case it is a 0-terminated array). Defaults to ``false``. * ``c_array_of_fixed_length``: The return value is an array of a fixed size. The value of this attribute is said size. * ``c_array_of_variable_length`` (BOOLEAN): The return value is an array of unspecified size. Note that bridges cannot know or infer the size of the array and have to raise an error when a method/function with this attribute is called. Defaults to ``false``. ``arg`` ........... Attributes * ``index``: Index of the argument. The first argument has index 0, and for selectors the two implict arguments are not counted. This attribute is optional on function arguments, all function arguments are present in the right order. * ``type``, ``type64``: Encoded type of the argument. Only present when this is different from the type in the Objective-C runtime. * ``type_modifier``: One of ``_C_IN``, ``_C_OUT`` or ``_C_INOUT`` to describe if a pointer argument is an input, output or input/output argument. This attribute is optional, but should be present on all pointer arguments as there is no default value. * ``c_array_length_in_arg``: The return value is an array whose length is present in another argument. The value is the index of the argument that contains the array size. This argument must be an integer value or an ``inout`` or ``out`` argument of type integer. * ``c_array_delimited_by_null``: The value is a NULL-terminated array. The basic type of the array must be a pointer-type (object, opaque) or an integer type (in which case it is a 0-terminated array). Defaults to ``false``. * ``c_array_of_fixed_length``: The value is an array of a fixed size. The value of this attribute is said size. * ``c_array_of_variable_length`` (BOOLEAN): The return value is an array of unspecified size. Defaults to ``false``. Bridges should assume that the length of the array passed in by the caller is the size of the array expected by the function/method. Note that this could cause crashes when the actually expected size is different. * ``c_array_length_in_result`` (BOOLEAN): The value is an array whose size is is the return value. There MUST also be ``c_array_of_fixed_length`` or ``c_array_length_in_arg`` attribute that describes how large the buffer must be on input. This attribute cannot be present on a ``rettype`` element and defaults to ``false``. * ``null_accepted`` (BOOLEAN): if true the pointer argument is allowed to be ``NULL``, otherwise it is not. Defaults to ``true``. * ``printf_format`` (BOOLEAN): if true this argument is a printf-style format. Only one of the arguments may have this property set to true, and only on a variadic function or method. Defaults to ``false``. * ``already_retained`` (BOOLEAN): If true the function returns an object that is already retained, that is the user is responsible for releasing the object when it is no longer needed. Only valid when the return type is an object (either a ``NSObject*`` or a ``CFTypeRef``). Defaults to ``false``. * ``function_pointer`` (BOOLEAN): if true the argument is a callback function. The signature of the callback is described by subelements of this element. * ``function_pointer_lifetime``: the livetime of a callback argument. Defaults to ``undetermined``: Valid values are: * ``call``: The callback function is only used during the call to the function/method and won't be stored for later use. * ``undetermined``: The called function/method may store a reference to the callback function and may therefore call the function when the call to this method/function has ended. Other lifetime values may be added in the future. NOTE: currently not supported by PyObjC. * ``sel_of_type``: if the type of the argument is ``SEL`` this attribute can contain the encoded signature for the selector. This can be used by bridges for additional type-checking. * ``block`` (BOOLEAN): if true the argument is a block. The signature of the block is described by subelements of this element and does not include the implement first argument. Exceptions file =============== The exceptions file has the same format as the metadata file, but with same minor additions as described below. 1. All elements can have a BOOLEAN attribute ``ignore`` (defaulting to ``false``). If the ``ignore`` attribute is false the element won't be present in the actual metadata file 2. All elements can have an attribute ``comment`` that contains arbitrary text that is not further interpreted. This attribute is meant to be used as a place where metadata maintainers can leave documentation/notes when that's needed. Use this instead of XML comments to ensure that tools keep the comment when rescanning a framework. 3. Function arguments will have an ``index`` attribute and only the function arguments/return values that require manual markup will be present. 4. The ``type_modifier`` attribute may have an empty value, which means the metadata maintainer has looked at an argument/return-value node and indicates that it doesn't need further markup (needed because the both scanners are pessimistic by design as to what arguments require markup) 5. Structs may have ``type`` and ``type64`` attributes in the exeption file (as the always have in the normal metadat file). If such fields are present those encodings are used instead of the output of ``@encode`` for this type and metadata will be generated for all methods that have a return or argument value of this type.