Prepare writing data to the server (for playback streams). This
* function may be used to optimize the number of memory copies when
* doing playback ("zero-copy"). It is recommended to call this
* function before each call to pa_stream_write().
*
* Pass in the address to a pointer and an address of the number of
* bytes you want to write. On return the two values will contain a
* pointer where you can place the data to write and the maximum number
* of bytes you can write. \a *nbytes can be smaller or have the same
* value as you passed in. You need to be able to handle both cases.
* Accessing memory beyond the returned \a *nbytes value is invalid.
* Accessing the memory returned after the following pa_stream_write()
* or pa_stream_cancel_write() is invalid.
*
* On invocation only \a *nbytes needs to be initialized, on return both
* *data and *nbytes will be valid. If you place (size_t) -1 in *nbytes
* on invocation the memory size will be chosen automatically (which is
* recommended to do). After placing your data in the memory area
* returned, call pa_stream_write() with \a data set to an address
* within this memory area and an \a nbytes value that is smaller or
* equal to what was returned by this function to actually execute the
* write.
*
* An invocation of pa_stream_write() should follow "quickly" on
* pa_stream_begin_write(). It is not recommended letting an unbounded
* amount of time pass after calling pa_stream_begin_write() and
* before calling pa_stream_write(). If you want to cancel a
* previously called pa_stream_begin_write() without calling
* pa_stream_write() use pa_stream_cancel_write(). Calling
* pa_stream_begin_write() twice without calling pa_stream_write() or
* pa_stream_cancel_write() in between will return exactly the same
* \a data pointer and \a nbytes values.
*
* On success, will return zero and a valid (non-NULL) pointer. If the
* return value is non-zero, or the pointer is NULL, this indicates an
* error. Callers should also pay careful attention to the returned
* length, which may not be the same as that passed in, as mentioned above.
*
* \since 0.9.16
Prepare writing data to the server (for playback streams). This * function may be used to optimize the number of memory copies when * doing playback ("zero-copy"). It is recommended to call this * function before each call to pa_stream_write(). * * Pass in the address to a pointer and an address of the number of * bytes you want to write. On return the two values will contain a * pointer where you can place the data to write and the maximum number * of bytes you can write. \a *nbytes can be smaller or have the same * value as you passed in. You need to be able to handle both cases. * Accessing memory beyond the returned \a *nbytes value is invalid. * Accessing the memory returned after the following pa_stream_write() * or pa_stream_cancel_write() is invalid. * * On invocation only \a *nbytes needs to be initialized, on return both * *data and *nbytes will be valid. If you place (size_t) -1 in *nbytes * on invocation the memory size will be chosen automatically (which is * recommended to do). After placing your data in the memory area * returned, call pa_stream_write() with \a data set to an address * within this memory area and an \a nbytes value that is smaller or * equal to what was returned by this function to actually execute the * write. * * An invocation of pa_stream_write() should follow "quickly" on * pa_stream_begin_write(). It is not recommended letting an unbounded * amount of time pass after calling pa_stream_begin_write() and * before calling pa_stream_write(). If you want to cancel a * previously called pa_stream_begin_write() without calling * pa_stream_write() use pa_stream_cancel_write(). Calling * pa_stream_begin_write() twice without calling pa_stream_write() or * pa_stream_cancel_write() in between will return exactly the same * \a data pointer and \a nbytes values. * * On success, will return zero and a valid (non-NULL) pointer. If the * return value is non-zero, or the pointer is NULL, this indicates an * error. Callers should also pay careful attention to the returned * length, which may not be the same as that passed in, as mentioned above. * * \since 0.9.16