include/io/channel.h

71  *  - Use QOM to properly support arbitrary subclassing
100  * must follow to provide specific channel implementations.
101  * The first five callbacks are mandatory to support, others
174  * @feature: the feature to check support of
187  * @feature: the feature to set support for
200  * to debugging. The name is used when creating GSource
209  * @iov: the array of memory regions to read data into
211  * @fds: pointer to an array that will received file handles
214  * @errp: pointer to a NULL-initialized error object
222  * It is not required for all @iov to be filled with
232  * to indicate the size of the @fds array that
234  * to call close() on each file descriptor and to
237  * It is an error to pass a non-NULL @fds parameter
257  * @iov: the array of memory regions to write data from
259  * @fds: an array of file handles to send
262  * @errp: pointer to a NULL-initialized error object
264  * Write data to the IO channel, reading it from the
270  * It is not required for all @iov data to be fully
276  * If there are file descriptors to send, the @fds
281  * It is an error to pass a non-NULL @fds parameter
300  * @iov: the array of memory regions to read data into
302  * @errp: pointer to a NULL-initialized error object
311  * to be read, yielding from the current coroutine
330  * @iov: the array of memory regions to read data into
332  * @errp: pointer to a NULL-initialized error object
341  * to be read, yielding from the current coroutine
358  * @iov: the array of memory regions to write data from
360  * @errp: pointer to a NULL-initialized error object
362  * Write data to the IO channel, reading it from the
369  * to be written, yielding from the current coroutine
382  * @iov: the array of memory regions to read data into
384  * @errp: pointer to a NULL-initialized error object
397  * @iov: the array of memory regions to write data from
399  * @errp: pointer to a NULL-initialized error object
412  * @buf: the memory region to read data into
414  * @errp: pointer to a NULL-initialized error object
428  * @buf: the memory regions to send data from
430  * @errp: pointer to a NULL-initialized error object
444  * @buf: the memory region to read data into
445  * @buflen: the number of bytes to @buf
446  * @errp: pointer to a NULL-initialized error object
466  * @buf: the memory region to read data into
467  * @buflen: the number of bytes to @buf
468  * @errp: pointer to a NULL-initialized error object
486  * @buf: the memory region to write data into
487  * @buflen: the number of bytes to @buf
488  * @errp: pointer to a NULL-initialized error object
506  * @errp: pointer to a NULL-initialized error object
522  * @enabled: whether or not to follow the coroutine's AioContext
524  * If @enabled is true, calls to qio_channel_yield() use the current
527  * If @enabled is false, calls to qio_channel_yield() use the global iohandler
529  * do not wish to respond to I/O during nested event loops. This is the
537  * @errp: pointer to a NULL-initialized error object
549  * @iov: the array of memory regions to write data from
552  * @errp: pointer to a NULL-initialized error object
555  * an error. To avoid errors, the caller may check for the feature
556  * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method.
569  * @buf: the memory region to write data into
570  * @buflen: the number of bytes to @buf
572  * @errp: pointer to a NULL-initialized error object
575  * an error. To avoid errors, the caller may check for the feature
576  * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method.
585  * @iov: the array of memory regions to read data into
588  * @errp: pointer to a NULL-initialized error object
591  * an error.  To avoid errors, the caller may check for the feature
592  * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method.
605  * @buf: the memory region to write data into
606  * @buflen: the number of bytes to @buf
608  * @errp: pointer to a NULL-initialized error object
611  * an error.  To avoid errors, the caller may check for the feature
612  * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method.
621  * @how: the direction to shutdown
622  * @errp: pointer to a NULL-initialized error object
628  * so may report an error. To avoid errors, the
630  * QIO_CHANNEL_FEATURE_SHUTDOWN prior to calling
647  * permitted to delay writes in order to merge
649  * writes may be delayed in order to opportunistically
654  * When @enabled is false, applications may wish to
655  * use the qio_channel_set_cork() method to explicitly
659  * API corresponds to the inverse of TCP_NODELAY flag,
663  * free to ignore this without it being considered an
675  * permitted to dispatch data that is written.
678  * set to false once again.
685  * API corresponds to the TCP_CORK flag.
688  * free to ignore this without it being considered an
698  * @offset: the position to seek to, relative to @whence
700  * @errp: pointer to a NULL-initialized error object
703  * @ioc, to be @offset. The value of @offset is
704  * interpreted relative to @whence:
706  * SEEK_SET - the position is set to @offset bytes
708  * SEEK_END - the position is set to end of the file plus @offset bytes
724  * @condition: the I/O condition to monitor
726  * Create a new main loop source that is used to watch
729  * of this, since it directly attaches a callback to
740  * @condition: the I/O condition to monitor
741  * @func: callback to invoke when the source becomes ready
742  * @user_data: opaque data to pass to @func
743  * @notify: callback to free @user_data
745  * Create a new main loop source that is used to watch
747  * will be registered against the source, to be invoked
749  * will be passed to @func when it is invoked. The @notify
750  * callback will be used to free @user_data when the
754  * to remove and free the source when no longer required.
769  * @condition: the I/O condition to monitor
770  * @func: callback to invoke when the source becomes ready
771  * @user_data: opaque data to pass to @func
772  * @notify: callback to free @user_data
773  * @context: the context to run the watch source
775  * Similar as qio_channel_add_watch(), but allows to specify context
776  * to run the watch source.
790  * @condition: the I/O condition to monitor
791  * @func: callback to invoke when the source becomes ready
792  * @user_data: opaque data to pass to @func
793  * @notify: callback to free @user_data
794  * @context: gcontext to bind the source to
796  * Similar as qio_channel_add_watch(), but allows to specify context
797  * to run the watch source, meanwhile return the GSource object
800  * Note: callers is responsible to unref the source when not needed.
814  * @condition: the I/O condition to wait for
822  * This must only be called from coroutine context. It is safe to
834  * If qio_channel_yield() is currently waiting for the channel to become
835  * readable, interrupt it and reenter immediately. This function is safe to call
843  * @condition: the I/O condition to wait for
849  * This will enter a nested event loop to perform
858  * @read_ctx: the AioContext to set the read handler on or NULL
860  * @write_ctx: the AioContext to set the write handler on or NULL
862  * @opaque: the opaque value passed to the handler
865  * be used by channel implementations to forward the handlers
866  * to another channel (e.g. from #QIOChannelTLS to the
885  * @iov: the array of memory regions to read data to
887  * @fds: an array of file handles to read
890  * @errp: pointer to a NULL-initialized error object
894  * Additionally, attempts to read file descriptors shared
896  * requested data to be read, yielding from the current
897  * coroutine if required. data refers to both file
914  * @iov: the array of memory regions to read data to
916  * @fds: an array of file handles to read
918  * @errp: pointer to a NULL-initialized error object
922  * Additionally, attempts to read file descriptors shared
924  * requested data to be read, yielding from the current
925  * coroutine if required. data refers to both file
940  * @iov: the array of memory regions to write data from
942  * @fds: an array of file handles to send
945  * @errp: pointer to a NULL-initialized error object
949  * to send all data passed (file handles and memory regions).
951  * to be written, yielding from the current coroutine
955  * instead of waiting for all requested data to be written,
959  * desired behavior, it's suggested to call qio_channel_flush()
974  * @errp: pointer to a NULL-initialized error object
983  *          1 if every send failed to use zero copy.
993  * @pid: pointer to pid
994  * @errp: pointer to a NULL-initialized error object
996  * Returns the pid of the peer process connected to this socket.