The buffer interface exports a model where an object can expose its internal data as a set of chunks of data, where each chunk is specified as a pointer/length pair. These chunks are called segments and are presumed to be non-contiguous in memory.
If an object does not export the buffer interface, then its tp_as_buffer member in the PyTypeObject structure should be NULL. Otherwise, the tp_as_buffer will point to a PyBufferProcs structure.
Note: It is very important that your
PyTypeObject structure uses
Py_TPFLAGS_DEFAULT for the
value of the tp_flags member rather than
tells the Python runtime that your PyBufferProcs structure
contains the bf_getcharbuffer slot. Older versions of Python
did not have this member, so a new Python interpreter using an old
extension needs to be able to test for its presence before using it.
The first slot is bf_getreadbuffer, of type getreadbufferproc. If this slot is NULL, then the object does not support reading from the internal data. This is non-sensical, so implementors should fill this in, but callers should test that the slot contains a non-NULL value.
The next slot is bf_getwritebuffer having type getwritebufferproc. This slot may be NULL if the object does not allow writing into its returned buffers.
The third slot is bf_getsegcount, with type getsegcountproc. This slot must not be NULL and is used to inform the caller how many segments the object contains. Simple objects such as PyString_Type and PyBuffer_Type objects contain a single segment.
The last slot is bf_getcharbuffer, of type
getcharbufferproc. This slot will only be present if the
Py_TPFLAGS_HAVE_GETCHARBUFFER flag is present in the
tp_flags field of the object's PyTypeObject. Before using
this slot, the caller should test whether it is present by using the
If present, it may be NULL, indicating that the object's contents
cannot be used as 8-bit characters.
The slot function may also raise an error if the object's contents
cannot be interpreted as 8-bit characters. For example, if the object
is an array which is configured to hold floating point values, an
exception may be raised if a caller attempts to use
bf_getcharbuffer to fetch a sequence of 8-bit characters.
This notion of exporting the internal buffers as ``text'' is used to
distinguish between objects that are binary in nature, and those which
have character-based content.
Note: The current policy seems to state that these characters may be multi-byte characters. This implies that a buffer size of N does not mean there are N characters present.
-1. The segment which is passed must be zero or positive, and strictly less than the number of segments returned by the bf_getsegcount slot function. On success, returns
*ptrptrto a pointer to the buffer memory.
*ptrptr; the memory buffer must correspond to buffer segment segment. Must return
-1and set an exception on error. TypeError should be raised if the object only supports read-only buffers, and SystemError should be raised when segment specifies a segment that doesn't exist.
*lenp. The function cannot fail.