pyobjc / Doc / C-API.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
Documentation for the PyObjC C-API (Preliminary)</title>
</head>
<body>
<h2>Documentation for the PyObjC C-API (Preliminary)</h2>
<h2><a name="introduction">Introduction</a></h2>
<p><i>WARNING: This API is unstable and might change in the future. Please let
us know if you want to use the C-API in your own code</i></p>
<p>The PyObjC package can be extended in C (or more likely Objective-C) using
the C API described in this document. This API should be used to write
custom wrappers for &quot;hard&quot; methods and to create/access Objective-C proxy
objects from the wrappers for C functions.</p>
<p>IMHO this API shouldn't be used to write modules that &quot;just happen&quot; to
work with Objective-C objects, using (static) methods in a class is much
more convenient.</p>
<p>The C API is defined in <code><span>pyobjc-api.h</span></code>. This file is currently not installed
because the API is not entirely stable. This is the only file that can
be included from outside of the 'Modules/objc' directory; future versions of
the bridge may use additional linker flags to make sure that the module doesn't
export symbols other than the module init function.</p>
<p>The easiest way to wrap global functions and constants is by using the scripts
in Scripts/CodeGenerators. These scripts are unsupported and might not work on
anything but the Apple headers, but if they work it will save you a lot of work.</p>
<h2><a name="limitations">Limitations</a></h2>
<p>An important limitation of the current C API is that you can only use the API
from one C file in the implementation of an extension module. This limitation
will probably not be removed in future versions of the API.</p>
<h2><a name="initialization">Initialization</a></h2>
<p>The initialization function (below) should be called before using the
rest of the API:</p>
<pre>
static int PyObjC_ImportAPI(PyObject* calling_module)
</pre>
<p>This module will return 0 if loading the module was successful, and -1
otherwise. Reasons for failure include: not being able to locate the module
and API version conflicts.</p>
<p>Loading the API will make it impossible to unload the <code><span>calling_module</span></code>.</p>
<p>NOTE: Using the API other than by the mechanism described in this document 
is unsupported.</p>
<h2><a name="compatibility-macros">Compatibility Macros</a></h2>
<p>On Mac OS X, the version guard macro <code><span>MAC_OS_X_VERSION_MAX_ALLOWED</span></code> will 
always be available.</p>
<p>The macros <code><span>PyDoc_STR</span></code>, <code><span>PyDoc_VAR</span></code> and <code><span>PyDoc_STRVAR</span></code> are defined 
when they are not defined in <code><span>Python.h</span></code>.</p>
<h2><a name="types">Types</a></h2>
<pre>
PyObjCObject_Type

int PyObjCObject_Check(value);
</pre>
<p><code><span>PyObjCObject_Type</span></code> is the type of Objective-C objects, both pure Objective-C
objects and hybrid Python/Objective-C objects are instances of this type. Use
<code><span>PyObjCObject_Check</span></code> to check if a value is an instance of this type.</p>
<p>There is at most 1 proxy for an Objective-C instance. That is, you can use
the <code><span>is</span></code> operator in Python to check if two variables refer to the same
Objective-C object.</p>
<pre>
PyObjCClass_Type

int PyObjCClass_Check(value);
</pre>
<p><code><span>PyObjCClass_Type</span></code> is the type of Objective-C classes, both pure Objective-C
objects and hybrid Python/Objective-C classes are instances of this type. Use
<code><span>PyObjCClass_Check</span></code> to check if a value is an instance of this type.</p>
<p>There is at most 1 class proxy for an Objective-C class. That is, you can use
the <code><span>is</span></code> operator in Python to compare two classes for equality.</p>
<pre>
PyObjCSelector_Type

int PyObjCSelector_Check(value);
</pre>
<p><code><span>PyObjCSelector_Type</span></code> is the type of Objective-C methods (including the
methods defined in Python).  Use <code><span>PyObjCSelector_Check</span></code> to check if a value 
is an instance of this type.</p>
<h2><a name="api-functions">API functions</a></h2>
<pre>
int PyObjC_RegisterMethodMapping(
                     Class cls, 
                     SEL sel, 
                     PyObject *(callObjC)(PyObject*, PyObject*, PyObject*),
                     IMP callPython);
</pre>
<p>Register a custom wrapper for a specific method. Returns -1 on failure.</p>
<pre>
int PyObjC_RegisterSignatureMapping(
                     char* typespec,
                     PyObject *(*callObjC)(PyObject*, PyObject*, PyObject*),
                     IMP callPython);
</pre>
<p>Register a custom wrapper for methods with a specific signature. Returns -1
on failure.</p>
<pre>
id PyObjCObject_GetObject(PyObject* obj);
</pre>
<p>Return the Objective-C object that is proxied by a <code><span>PyObjCObject_Type</span></code> 
instance.</p>
<pre>
void PyObjCObject_ClearObject(PyObject* obj);
</pre>
<p>Clear the proxied object. That is, the <code><span>PyObjCObject_Type</span></code> instance will
no longer be a proxy.</p>
<pre>
Class PyObjCClass_GetClass(PyObject* cls);
</pre>
<p>Extract the Class from a proxied Objective-C class.</p>
<pre>
PyObject* PyObjCClass_New(Class cls);
</pre>
<p>Create or find a proxy object for the class.</p>
<pre>
id PyObjC_PythonToId(PyObject* value);
</pre>
<p>Create a proxy for the Python object. This will unwrap proxied Objective-C 
objects, and will create the appropriate proxy for Python objects.</p>
<pre>
PyObject* IdToPython(id value);
</pre>
<p>Create a proxy for the Objective-C object. This will unwrap proxied Python
objects and will create a proxy object for Objective-C objects.</p>
<pre>
void PyObjCErr_FromObjC(NSException* localException);
</pre>
<p>Convert an Objective-C exception to Python. Use 
<code><span>PyObjCErr_FromObjC(localException)</span></code> to convert the exception in an 
<code><span>NS_HANDLER</span></code> block.</p>
<p>Note that PyObjC supports round-tripping for exceptions, if the current 
Objective-C exception is an converted Python exception, the original Python
exception will be rethrown.</p>
<pre>
void PyObjCErr_ToObjC(void);
</pre>
<p>Convert a Python exception to Objective-C. This function does not return.</p>
<p>Note that PyObjC supports round-tripping for exceptions, if the current Python
exception is an converted Objective-C exception, the original Objective-C
exception will be rethrown.</p>
<pre>
int PyObjC_PythonToObjC(const char* typespec, PyObject* value, void* buffer);
</pre>
<p>Convert the value to an Objective-C value of type <code><span>typespec</span></code>. The buffer must
be at least <code><span>PyObjCRT_SizeOfType(typespec)</span></code> bytes long.</p>
<p>NOTE: The <code><span>typespec</span></code> is a type specifier as described in the runtime 
reference of the Objective-C manual from Apple. Use <code><span>@encode(mytype)</span></code> if to
get code that is portable to a different Objective-C runtime.</p>
<pre>
PyObject* PyObjC_ObjCToPython(const char* typespec, void* value);
</pre>
<p>Convert an Objective-C value of type <code><span>typespec</span></code> to python.</p>
<pre>
PyObject* PyObjC_CallPython(id self, SEL sel, PyObject* arglist, int* isAlloc);
</pre>
<p>Call the Python implementation of method <code><span>sel</span></code> of <code><span>self</span></code>. The <code><span>arglist</span></code>
must contain the complete argument list, including self. If <code><span>isAlloc</span></code> is not
<code><span>NULL</span></code> it is used to output whether this method should return a new reference
(TRUE) or a borrowed reference (FALSE).</p>
<pre>
int PyObjCRT_SizeOfType(const char* typespec);
</pre>
<p>Return the size of variables of the specified type.</p>
<pre>
int PyObjCRT_AlignOfType(const char* typespec);
</pre>
<p>Return the alignment of variables of the specified type.</p>
<pre>
Class PyObjCSelector_GetClass(PyObject* sel);
</pre>
<p>Return the class containing the definition of <code><span>sel</span></code>.</p>
<pre>
SEL PyObjCSelector_GetSelector(PyObject* sel);
</pre>
<p>Return the Objective-C method name for <code><span>sel</span></code>.</p>
<pre>
void PyObjC_InitSuper(struct objc_super*, Class, id);
</pre>
<p>Initialize the <code><span>struct</span> <span>objc_super</span></code> for use with <code><span>objc_sendMsgSuper</span></code>. Use 
this if the <code><span>self</span></code> argument is a normal object.</p>
<pre>
void PyObjC_InitSuperCls(struct objc_super*, Class, Class);
</pre>
<p>Initialize the <code><span>struct</span> <span>objc_super</span></code> for use with <code><span>objc_sendMsgSuper</span></code>. Use 
this if the <code><span>self</span></code> argument is a Class.</p>
<pre>
int  PyObjCPointerWrapper_Register(
              const char* typespec, PyObject* (*pythonify)(void*),
              int (*depythonify)(PyObject*, void*)
      );
</pre>
<p>Use <code><span>pythonify</span></code> to convert pointers of type <code><span>typespec</span></code> to python and
<code><span>depythonify</span></code> to extract them from Python. Use this to register helper 
function for the conversion of opaque pointers.</p>
<pre>
id  PyObjCUnsupportedMethod_IMP(id, SEL);
</pre>
<p>Use this as an argument for <code><span>PyObjC_RegisterMethodMapping</span></code> or 
<code><span>PyObjC_RegisterSignatureMapping</span></code> if the method is not callable from 
Objective-C.</p>
<pre>
PyObject* PyObjCUnsupportedMethod_Caller(PyObject*, PyObject*, PyObject*);
</pre>
<p>Use this as an argument for <code><span>PyObjC_RegisterMethodMapping</span></code> or 
<code><span>PyObjC_RegisterSignatureMapping</span></code> if the method is not callable from Python.</p>
<pre>
int PyObjCObject_Convert(PyObject* object, void* pvar);
</pre>
<p>This is a variation on <code><span>PyObjC_PythonToId</span></code> than can be used with 
<code><span>PyArg_Parse</span></code>.</p>
<pre>
int PyObjCClass_Convert(PyObject* object, void* pvar);
</pre>
<p>This is a variation on <code><span>PyObjCClass_GetClass</span></code> than can be used with 
<code><span>PyArg_Parse</span></code>.</p>
<pre>
int PyObjCSelector_Convert(PyObject* object, void* pvar);
</pre>
<p>Write the <code><span>SEL</span></code> for a selector object into <code><span>*pvar</span></code>. 
For use with <code><span>PyArg_Parse</span></code>.</p>
<pre>
int PyObjC_ConvertBOOL(PyObject* object, void* pvar);
</pre>
<p>Write <code><span>YES</span></code> into <code><span>*pvar</span></code> if <code><span>object</span></code> is true, write <code><span>NO</span></code> otherwise.
<code><span>*pvar</span></code> should be of type BOOL.  For use with <code><span>PyArg_Parse</span></code>.</p>
<pre>
int PyObjC_ConvertChar(PyObject* object, void* pvar);
</pre>
<p>Write the value of a string of length 1 into the character (type char)
at <code><span>*pvar</span></code>. For use with <code><span>PyArg_Parse</span></code>.</p>
</body>
</html>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.