1#ifndef PyObjC_STRUCT_WRAPPER
2#define PyObjC_STRUCT_WRAPPER
3/*!
4 * @header struct-wrapper.h
5 * @abstract Creation of mutable struct-like types
6 * @discussion
7 *      This module defines a function that can be used to create
8 *      types for mutable struct-like types.
9 *
10 *      The struct-like type has the following properties:
11 *
12 *      - Fields can be accessed by name or index (e.g. instances can be
13 *        used as mutable tuples)
14 *      - Instances are not hasable
15 *      - Instances can be pickled
16 *      - Instances can be compared with sequences, and will compare equal
17 *        to a tuple with equal values for the fields.
18 *
19 *      This module also defines a pair of functions to integrate this
20 *      functionality in PyObjC, that is to make it possible to translate
21 *      C structs to instances of these struct-like types.
22 */
23
24/*!
25 * @function PyObjC_MakeStructType
26 * @abstract Create a mutable struct-like type
27 * @param name       Name of the type, should include the module name
28 * @param doc        Docstring for the type
29 * @param tpinit     Optional __init__ method for the type
30 * @param numFields  Number of fields in the type
31 * @param fieldnames Field names, there should be exactly numFields names.
32 * @result Returns a newly allocated type or NULL
33 * @discussion
34 *    The name, doc and fieldnames should be pointers to static strings,
35 *    this function will not copy them.
36 *
37 *    If tpinit is NULL the type will have a default __init__ that initializes
38 *    the fields to None and uses its arguments to optionally initiaze the
39 *    fields.
40 *
41 */
42PyObject* PyObjC_MakeStructType(
43	const char* name,
44	const char* doc,
45	initproc tpinit,
46	Py_ssize_t numFields,
47	const char** fieldnames,
48	const char* typestr);
49
50
51/*!
52 * @function PyObjC_RegisterStructType
53 * @abstract Create a new struct-like type and register it with the bridge
54 * @param signature  Objective-C signature for the struct
55 * @param name       Name of the type, should include the module name
56 * @param doc        Docstring for the type
57 * @param tpinit     Optional __init__ method for the type
58 * @param numFields  Number of fields in the type
59 * @param fieldnames Field names, there should be exactly numFields names.
60 * @result Returns a newly allocated type or NULL
61 * @discussion
62 *    This function calls PyObjC_MakeStructType(name, doc, tpinit, numFields,
63 *    fieldnames) and then adds the created type to an internal lookup table.
64 *
65 *    PyObjC_CreateRegisteredStruct can then be used to create instances of
66 *    the type.
67 */
68PyObject* PyObjC_RegisterStructType(
69	const char* signature,
70	const char* name,
71	const char* doc,
72	initproc tpinit,
73	Py_ssize_t numFields,
74	const char** fieldnames);
75
76/*!
77 * @function PyObjC_CreateRegisteredStruct
78 * @param signature  An Objective-C signature for a struct type
79 * @param len        Length of the signature string
80 * @param objc_signature
81 *                If not null this will be set to the signature that
82 *                was used to register the struct type. This might include
83 *                type codes that are private to PyObjC (such as _C_NSBOOL)
84 *
85 * @result A new instance or NULL
86 * @discussion
87 *     This function will not set an error when it cannot find or create
88 *     a wrapper for the specified Objective-C type.
89 *
90 *     The returned instance is uninitialized, all fields are NULL. The
91 *     __init__ method has not been called.
92 */
93PyObject* PyObjC_CreateRegisteredStruct(const char* signature, Py_ssize_t len, const char** objc_signature);
94
95#endif /* PyObjC_STRUCT_MEMBER */
96