NAME
BBrriiddggeeSSuuppppoorrtt - Scripting bridges support file
DESCRIPTION
BridgeSupport files are XML files that describe the API symbols of frame-
works or libraries that cannot be introspected at runtime. These are gen-
erally ANSI C symbols that are non-object-oriented items such as con-
stants, enumerations, structures, and functions but can also include some additional information about classes, methods, and informal protocols.BridgeSupport files are a major component of the Objective-C bridges
(RubyCocoa and PyObjC) supported in Mac OS X for scripting languages such as Ruby and Python.genbridgemetadata(1) is the tool used to generate BridgeSupport files
for particular frameworks or libraries. To understand the following discussion you should know what ``element'' and ``attribute'' mean in XML markup. You should also be familiar withObjective-C and with concepts related to the Objective-C runtime, such as
the type-encoding constants.
SSTTRRUUCCTTUURREEThe structure of BridgeSupport XML consists of a hierarchy of elements
under the root element, ssiiggnnaattuurreess. The signatures elementssiiggnnaattuurreess is the top-level, or root, element of a BridgeSupport XML
file. Mandatory attributes:version The version number of the BridgeSupport format. The only possi-
ble value is ``1.0'' which means the format delivered with Mac OS X 10.5. Possible children elements: ddeeppeennddssoonn, ssttrruucctt, ccffttyyppee, ooppaaqquuee, ccoonnssttaanntt, ssttrriinnggccoonnssttaanntt, eennuumm, ffuunnccttiioonn, ffuunnccttiioonnaalliiaass, iinnffoorrmmaallpprroottooccooll, ccllaassss. The dependson element This element describes a dependency. Frameworks usually depend on other frameworks, and the bridges will use these elements to interpret theBridgeSupport files of the dependencies before interpreting the given
one. Mandatory attributes: path The path of the dependency. The struct element This element describes a C structure. Mandatory attributes: name The name of the C structure. type, type64 The complete type of the C structure, including the fieldnames, as a string of Objective-C runtime encoding types.
If the element has a different type on a 64-bit environ-
ment, the type64 attribute will contain it. If the elementdoes not exist on a 32-bit environment, only the type64
attribute will be used. Optional attributes: opaque Indicates whether the fields of the structure should be exposed. The default value is ``false''. The cftype elementThis element describes a Core Foundation-based type.
Mandatory attributes: name The name of the Core Foundation type.type, type64 The type of the Core Foundation type as a string of Objec-
tive-C runtime encoding types. If the element has a differ-
ent type on a 64-bit environment, the type64 attribute will
contain it. If the element does not exist on a 32-bit envi-
ronment, only the type64 attribute will be used. Optional attributes:tollfree The name of the tollfree-bridged Objective-C class, if
any. gettypeidfunc The name of the function that retrieves the TypeID valueof the given Core Foundation type, if any. This name usu-
ally ends with ``GetTypeID''. The opaque element This element describes an opaque type, most generally a C pointer to a C opaque structure. Mandatory attributes: name The name of the opaque type.type, type64 The type of the opaque type, as a string of Objective-C
runtime encoding types. If the element has a different typeon a 64-bit environment, the type64 attribute will contain
it. If the element does not exist on a 32-bit environment,
only the type64 attribute will be used. The constant element This element describes a C constant. Mandatory attributes: name The name of the C constant.type, type64 The type of the C constant, as a string of Objective-C run-
time encoding types. If the element has a different type ona 64-bit environment, the type64 attribute will contain it.
If the element does not exist on a 32-bit environment, only
the type64 attribute will be used. Optional attributes: magiccookie Indicates whether the C constant has a ``magic'' or fixed value and should not be converted at runtime to the given type. The default value is ``false''. The stringconstant element This element describes a string constant. The string can either be a Cstring or an Objective-C string (an NSString object). ssttrriinnggccoonnssttaanntt
elements are usually created from C preprocessor macros. Mandatory attributes: name The name of the string constant. value The value of the string constant. Optional attributes:nsstring Indicates whether the string constant has an Objective-C value,
and should be converted to an NSString object. The default value is ``false''. The enum element This element describes a C enumeration. Mandatory attributes: name The name of the C enumeration. value, value64, levalue, bevalue The value of the C enumeration, as an integer. The value can benegative. If the enumeration has a different value on a 64-bit
environment, the value64 attribute will contain it. If the enumera-
tion does not exist on a 32-bit environment, only the value64
attribute will be used. If the enumeration has a different value onlittle-endian (Intel) and big-endian (PPC) machines, the levalue
and bevalue will contain respectively the values for little and big endian platforms. Optional attributes: ignore Indicates whether the C enumeration should be ignored by the bridges. The default value is ``false''.suggestion If the ignore attribute is ``true'' , this attribute may con-
tain a textual message that the bridges can deliver as an exception or error message to be delivered to the user. By default there is no suggestion. The function element This element describes a C function. Mandatory attributes: name The name of the C function. Optional attributes: variadic Indicates whether the C function accepts a variable number of arguments. The default value is ``false''. inline Indicates whether the C function is inline. In that case, the symbol can be found in the respective .dylib file that comeswith the BridgeSupport file. Consult genbridgemetadata(1) to
know how the dylib files are generated. The default value is ``false''. Possible children: aarrgg (zero or more), rreettvvaall (zero or one). The functionalias element This element defines an alias or shortcut to a C function. Mandatory attributes: name The name of the C function alias. original The name of the original C function the alias points to. The class elementThis element defines an Objective-C class. Only classes where additional
metadata is needed are described. Mandatory attributes:name The name of the Objective-C class.
Possible children: mmeetthhoodd (zero or more). The informalprotocol elementThis element defines an Objective-C informal protocol.
Mandatory attributes:name The name of the Objective-C informal protocol.
Possible children: mmeetthhoodd (zero or more). The method elementThis element defines an Objective-C method. Only methods where additional
metadata is needed are described. Mandatory attributes:selector The selector of the Objective-C method.
Mandatory attributes (only when declared under iinnffoorrmmaallpprroottooccooll) :type, type64 The type of the Objective-C method, as a string of Objec-
tive-C runtime encoding types. If the element has a differ-
ent type on a 64-bit environment, the type64 attribute will
contain it. If the element does not exist on a 32-bit envi-
ronment, only the type64 attribute will be used. Optional attributes: classmethod Whether this is a class method or not. The default value is ``false''. Optional attributes (only when not declared under iinnffoorrmmaallpprroottooccooll) : variadic Indicates whether the method accepts a variable number of arguments. The default value is ``false''. ignore Indicates whether the method should be ignored by the bridges. The default value is ``false''.suggestion If the ignore attribute is ``true'' , this attribute may con-
tain a textual message that the bridges can deliver as an exception or error message to be delivered to the user. By default there is no suggestion. Possible children (only when not declared under iinnffoorrmmaallpprroottooccooll) : aarrgg (zero or more), rreettvvaall (zero or one). The arg and retval elements These elements describe respectively an argument and a return value. They should be defined within both ffuunnccttiioonn and mmeetthhoodd elements, and their attributes depend under which element they are defined under. Optional attributes: carraylengthinarg Defines the argument or return value as a C array whose length is defined by the value of the given argument. The value of thisattribute is the index position of the argu-
ment that should contain the array size. The value can also be two integers separated by a comma, which in that case means that the first value is used when converting to C /Objective-C, and the second when converting
back to the scripting language. This attribute cannot be used with another ``carray'' attribute. carrayoffixedlength Defines the argument or return value as a C array of a fixed length. The value of this attribute is the array size. This attribute cannot be used with another ``carray'' attribute. carraydelimitedbynull Defines the argument or return value as a C array that ends with a NULL value, if the value of this attribute is ``true''. The default value of this attribute is ``false''. This attribute cannot be used with another ``carray'' attribute. carrayofvariablelength Defines the argument or return value as a C array of a variable length, if the value of this attribute is ``true''. The default value of this attribute is ``false''. This attribute cannot be used with another ``carray'' attribute. functionpointer Indicates whether the argument or return value is a function pointer. If ``true'' ,the current element should have a set of com-
plete arg and retval child elements to define both the argument and the return value types of the function pointer. seloftype, seloftype64 This attribute, used for arguments or returnvalue of the type ``SEL'' (an Objective-C
selector), is used to provide the signature of the method the selector should point to,as a string of Objective-C runtime encoding
types. If the selector has a different typeon a 64-bit environment, the seloftype64
attribute will contain it. There is no default value. This attribute can be used to give a hint to the bridges when their default behavior isn't sufficient. Optional attributes (aarrgg only): carraylengthinretval Defines the argument as a C like array whose length is defined by the value of the return value, if ``true''. The default value of this attribute is ``false''. This attribute cannot be used with another ``carray'' attribute. typemodifier The type modifier of the argument. Possible values are ``n'' (in), ``o'' (out) and ``N'' (inout). There is no default value. nullaccepted Indicates whether a NULL value can be passed to this argument. The default value is ``true''. printfformat Indicates whether this argument accepts a printf(3) format string value. The default value is ``false''. Optional attributes (rreettvvaall only): alreadyretained A value of ``true'' indicates that the return value should not be retained by the bridges. The default value is ``false''. Mandatory attributes (when declared under ffuunnccttiioonn): type, type64 The type of the argument or return value, as a string ofObjective-C runtime encoding types. If the element has a
different type on a 64-bit environment, the type64
attribute will contain it. If the element does not exist ona 32-bit environment, only the type64 attribute will be
used. Mandatory attributes (when declared under mmeetthhoodd, aarrgg only): index The index position of the argument. Optional attributes (when declared under mmeetthhoodd): type, type64 The type of the argument or return value, as a string ofObjective-C runtime encoding types. If the element has a
different type on a 64-bit environment, the type64
attribute will contain it. If the element does not exist ona 32-bit environment, only the type64 attribute will be
used. This attribute is optional for methods as the bridgescan retrieve the type by asking the runtime, but it is pos-
sible to override the default type using this attribute. There is no default value.SEE ALSO
genbridgemetadata(1) /System/Library/DTDs/BridgeSupport.dtd
BSD March 13, 2007 BSD