include/io/channel.h

7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16  * You should have received a copy of the GNU Lesser General Public
67  * The QIOChannel defines the core API for a generic I/O channel
68  * class hierarchy. It is inspired by GIOChannel, but has the
73  *  - None of the character set translation, binary data exclusively
99  * This class defines the contract that all subclasses
101  * The first five callbacks are mandatory to support, others
104  * Consult the corresponding public API docs for a description
105  * of the semantics of each callback. io_shutdown in particular
173  * @ioc: the channel object
174  * @feature: the feature to check support of
176  * Determine whether the channel implementation supports
177  * the optional feature named in @feature.
186  * @ioc: the channel object
187  * @feature: the feature to set support for
189  * Add channel support for the feature named in @feature.
196  * @ioc: the channel object
197  * @name: the name of the channel
199  * Sets the name of the channel, which serves as an aid
200  * to debugging. The name is used when creating GSource
208  * @ioc: the channel object
209  * @iov: the array of memory regions to read data into
210  * @niov: the length of the @iov array
216  * Read data from the IO channel, storing it in the
218  * in the @iov will be fully populated with data
219  * before the next one is used. The @niov parameter
220  * specifies the total number of elements in @iov.
223  * data. If the channel is in blocking mode, at least
225  * guaranteed. If the channel is non-blocking and no
228  * If the channel has passed any file descriptors,
229  * the @fds array pointer will be allocated and
230  * the elements filled with the received file
231  * descriptors. The @nfds pointer will be updated
232  * to indicate the size of the @fds array that
233  * was allocated. It is the callers responsibility
235  * call g_free() on the array pointer in @fds.
239  * value for the QIO_CHANNEL_FEATURE_FD_PASS constant.
241  * Returns: the number of bytes read, or -1 on error,
243  * and the channel is non-blocking
256  * @ioc: the channel object
257  * @iov: the array of memory regions to write data from
258  * @niov: the length of the @iov array
264  * Write data to the IO channel, reading it from the
266  * in the @iov will be fully sent, before the next
267  * one is used. The @niov parameter specifies the
271  * sent. If the channel is in blocking mode, at least
273  * guaranteed. If the channel is non-blocking and no
276  * If there are file descriptors to send, the @fds
277  * array should be non-NULL and provide the handles.
283  * value for the QIO_CHANNEL_FEATURE_FD_PASS constant.
285  * Returns: the number of bytes sent, or -1 on error,
287  * and the channel is non-blocking
299  * @ioc: the channel object
300  * @iov: the array of memory regions to read data into
301  * @niov: the length of the @iov array
304  * Read data from the IO channel, storing it in the
306  * in the @iov will be fully populated with data
307  * before the next one is used. The @niov parameter
308  * specifies the total number of elements in @iov.
310  * The function will wait for all requested data
311  * to be read, yielding from the current coroutine
329  * @ioc: the channel object
330  * @iov: the array of memory regions to read data into
331  * @niov: the length of the @iov array
334  * Read data from the IO channel, storing it in the
336  * in the @iov will be fully populated with data
337  * before the next one is used. The @niov parameter
338  * specifies the total number of elements in @iov.
340  * The function will wait for all requested data
341  * to be read, yielding from the current coroutine
357  * @ioc: the channel object
358  * @iov: the array of memory regions to write data from
359  * @niov: the length of the @iov array
362  * Write data to the IO channel, reading it from the
364  * in the @iov will be fully sent, before the next
365  * one is used. The @niov parameter specifies the
368  * The function will wait for all requested data
369  * to be written, yielding from the current coroutine
381  * @ioc: the channel object
382  * @iov: the array of memory regions to read data into
383  * @niov: the length of the @iov array
396  * @ioc: the channel object
397  * @iov: the array of memory regions to write data from
398  * @niov: the length of the @iov array
411  * @ioc: the channel object
412  * @buf: the memory region to read data into
413  * @buflen: the length of @buf
427  * @ioc: the channel object
428  * @buf: the memory regions to send data from
429  * @buflen: the length of @buf
443  * @ioc: the channel object
444  * @buf: the memory region to read data into
445  * @buflen: the number of bytes to @buf
448  * Reads @buflen bytes into @buf, possibly blocking or (if the
449  * channel is non-blocking) yielding from the current coroutine
450  * multiple times until the entire content is read. If end-of-file
465  * @ioc: the channel object
466  * @buf: the memory region to read data into
467  * @buflen: the number of bytes to @buf
470  * Reads @buflen bytes into @buf, possibly blocking or (if the
471  * channel is non-blocking) yielding from the current coroutine
472  * multiple times until the entire content is read. If end-of-file
485  * @ioc: the channel object
486  * @buf: the memory region to write data into
487  * @buflen: the number of bytes to @buf
490  * Writes @buflen bytes from @buf, possibly blocking or (if the
491  * channel is non-blocking) yielding from the current coroutine
492  * multiple times until the entire content is written.  Otherwise
504  * @ioc: the channel object
505  * @enabled: the blocking flag state
508  * If @enabled is true, then the channel is put into
521  * @ioc: the channel 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
528  * AioContext. This is may be used by coroutines that run in the main loop and
529  * do not wish to respond to I/O during nested event loops. This is the
536  * @ioc: the channel object
539  * Close the channel, flushing any pending I/O
548  * @ioc: the channel object
549  * @iov: the array of memory regions to write data from
550  * @niov: the length of the @iov array
551  * @offset: offset in the channel where writes should begin
555  * an error. To avoid errors, the caller may check for the feature
559  * sending of file handles as well as beginning the write at the
568  * @ioc: the channel object
569  * @buf: the memory region to write data into
570  * @buflen: the number of bytes to @buf
571  * @offset: offset in the channel where writes should begin
575  * an error. To avoid errors, the caller may check for the feature
584  * @ioc: the channel object
585  * @iov: the array of memory regions to read data into
586  * @niov: the length of the @iov array
587  * @offset: offset in the channel where writes should begin
591  * an error.  To avoid errors, the caller may check for the feature
595  * receiving of file handles as well as beginning the read at the
604  * @ioc: the channel object
605  * @buf: the memory region to write data into
606  * @buflen: the number of bytes to @buf
607  * @offset: offset in the channel where writes should begin
611  * an error.  To avoid errors, the caller may check for the feature
620  * @ioc: the channel object
621  * @how: the direction to shutdown
625  * without closing the underlying transport.
628  * so may report an error. To avoid errors, the
629  * caller may check for the feature flag
643  * @ioc: the channel object
644  * @enabled: the new flag state
646  * Controls whether the underlying transport is
648  * small packets. If @enabled is true, then the
655  * use the qio_channel_set_cork() method to explicitly
659  * API corresponds to the inverse of TCP_NODELAY flag,
660  * controlling whether the Nagle algorithm is active.
671  * @ioc: the channel object
672  * @enabled: the new flag state
674  * Controls whether the underlying transport is
680  * This feature is typically used when the automatic
681  * write coalescing facility is disabled via the
685  * API corresponds to the TCP_CORK flag.
697  * @ioc: the channel object
698  * @offset: the position to seek to, relative to @whence
699  * @whence: one of the (POSIX) SEEK_* constants listed below
702  * Moves the current I/O position within the channel
703  * @ioc, to be @offset. The value of @offset is
706  * SEEK_SET - the position is set to @offset bytes
707  * SEEK_CUR - the position is moved by @offset bytes
708  * SEEK_END - the position is set to end of the file plus @offset bytes
713  * Returns: the new position on success, (off_t)-1 on failure
723  * @ioc: the channel object
724  * @condition: the I/O condition to monitor
727  * for the I/O condition @condition. Typically the
730  * the source
732  * Returns: the new main loop source.
739  * @ioc: the channel object
740  * @condition: the I/O condition to monitor
741  * @func: callback to invoke when the source becomes ready
746  * for the I/O condition @condition. The callback @func
747  * will be registered against the source, to be invoked
748  * when the source becomes ready. The optional @user_data
749  * will be passed to @func when it is invoked. The @notify
750  * callback will be used to free @user_data when the
753  * The returned source ID can be used with g_source_remove()
754  * to remove and free the source when no longer required.
755  * Alternatively the @func callback can return a FALSE
758  * Returns: the source ID
768  * @ioc: the channel object
769  * @condition: the I/O condition to monitor
770  * @func: callback to invoke when the source becomes ready
773  * @context: the context to run the watch source
776  * to run the watch source.
778  * Returns: the source ID
789  * @ioc: the channel object
790  * @condition: the I/O condition to monitor
791  * @func: callback to invoke when the source becomes ready
794  * @context: gcontext to bind the source to
797  * to run the watch source, meanwhile return the GSource object
798  * instead of tag ID, with the GSource referenced already.
800  * Note: callers is responsible to unref the source when not needed.
802  * Returns: the source pointer
813  * @ioc: the channel object
814  * @condition: the I/O condition to wait for
816  * Yields execution from the current coroutine until the condition
819  * addition, no two coroutine can be waiting on the same condition
820  * and channel at the same time.
823  * reenter the coroutine externally while it is waiting; in this
824  * case the function will return even if @condition is not yet
832  * @ioc: the channel object
834  * If qio_channel_yield() is currently waiting for the channel to become
842  * @ioc: the channel object
843  * @condition: the I/O condition to wait for
845  * Block execution from the current thread until
846  * the condition indicated by @condition becomes
850  * the wait.
857  * @ioc: the channel object
858  * @read_ctx: the AioContext to set the read handler on or NULL
859  * @io_read: the read handler
860  * @write_ctx: the AioContext to set the write handler on or NULL
861  * @io_write: the write handler
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
869  * When @read_ctx is NULL, don't touch the read handler. When @write_ctx is
870  * NULL, don't touch the write handler. Note that setting the read handler
871  * clears the write handler, and vice versa, if they share the same AioContext.
872  * Therefore the caller must pass both handlers together when sharing the same
884  * @ioc: the channel object
885  * @iov: the array of memory regions to read data to
886  * @niov: the length of the @iov array
895  * over the channel. The function will wait for all
896  * requested data to be read, yielding from the current
898  * descriptors and the iovs.
913  * @ioc: the channel object
914  * @iov: the array of memory regions to read data to
915  * @niov: the length of the @iov array
923  * over the channel. The function will wait for all
924  * requested data to be read, yielding from the current
926  * descriptors and the iovs.
939  * @ioc: the channel object
940  * @iov: the array of memory regions to write data from
941  * @niov: the length of the @iov array
950  * The function will wait for all requested data
951  * to be written, yielding from the current coroutine
957  * In this case, if the buffer gets changed between queueing and
958  * sending, the updated buffer will be sent. If this is not a
960  * before reusing the buffer.
973  * @ioc: the channel object
992  * @ioc: the channel object
996  * Returns the pid of the peer process connected to this socket.
998  * The use of this function is possible only for connected
1001  * Return -1 on error with pid -1 for the non-Linux OS.