NAME
ber_sockbuf_alloc, ber_sockbuf_free, ber_sockbuf_ctrl, ber_sockbuf_add_io, ber_sockbuf_remove_io, Sockbuf_IO - OpenLDAP LBER I/O infrastructure
LIBRARY
OpenLDAP LBER (liblber, -llber)
SYNOPSIS
#include <lber.h>
Sockbuf *ber_sockbuf_alloc( void );
void ber_sockbuf_free(Sockbuf *sb);
int ber_sockbuf_ctrl(Sockbuf *sb, int opt, void *arg);
int ber_sockbuf_add_io(Sockbuf *sb, Sockbuf_IO *sbio, int layer, void *arg);
int ber_sockbuf_remove_io(Sockbuf *sb, Sockbuf_IO *sbio, int layer);
typedef struct sockbuf_io_desc { int sbiod_level; Sockbuf *sbiod_sb; Sockbuf_IO *sbiod_io; void *sbiod_pvt; struct sockbuf_io_desc *sbiod_next; } Sockbuf_IO_Desc;
typedef struct sockbuf_io { int (*sbi_setup)(Sockbuf_IO_Desc *sbiod, void *arg); int (*sbi_remove)(Sockbuf_IO_Desc *sbiod); int (*sbi_ctrl)(Sockbuf_IO_Desc *sbiod, int opt, void *arg); ber_slen_t (*sbi_read)(Sockbuf_IO_Desc *sbiod, void *buf, ber_len_t len); ber_slen_t (*sbi_write)(Sockbuf_IO_Desc *sbiod, void *buf, ber_len_t len); int (*sbi_close)(Sockbuf_IO_Desc *sbiod); } Sockbuf_IO;
DESCRIPTION
These routines are used to manage the low level I/O operations performed by the Lightweight BER library. They are called implicitly by the other libraries and usually do not need to be called directly from applications. The I/O framework is modularized and new transport layers can be supported by appropriately defining a Sockbuf_IO structure and installing it onto an existing Sockbuf. Sockbuf structures are allocated and freed by ber_sockbuf_alloc() and ber_sockbuf_free(), respectively. The ber_sockbuf_ctrl() function is used to get and set options related to a Sockbuf or to a specific I/O layer of the Sockbuf. The ber_sockbuf_add_io() and ber_sockbuf_remove_io() functions are used to add and remove specific I/O layers on a Sockbuf.
Options for ber_sockbuf_ctrl() include:
LBER_SB_OPT_HAS_IO | |
Takes a Sockbuf_IO * argument and returns 1 if the given handler is installed on the Sockbuf, otherwise returns 0. | |
LBER_SB_OPT_GET_FD | |
Retrieves the file descriptor associated to the Sockbuf; arg must be a ber_socket_t *. The return value will be 1 if a valid descriptor was present, -1 otherwise. | |
LBER_SB_OPT_SET_FD | |
Sets the file descriptor of the Sockbuf to the descriptor pointed to by arg; arg must be a ber_socket_t *. The return value will always be 1. | |
LBER_SB_OPT_SET_NONBLOCK | |
Toggles the non-blocking state of the file descriptor associated to the Sockbuf. arg should be NULL to disable and non-NULL to enable the non-blocking state. The return value will be 1 for success, -1 otherwise. | |
LBER_SB_OPT_DRAIN | |
Flush (read and discard) all available input on the Sockbuf. The return value will be 1. | |
LBER_SB_OPT_NEEDS_READ | |
Returns non-zero if input is waiting to be read. | |
LBER_SB_OPT_NEEDS_WRITE | |
Returns non-zero if the Sockbuf is ready to be written. | |
LBER_SB_OPT_GET_MAX_INCOMING | |
Returns the maximum allowed size of an incoming message; arg must be a ber_len_t *. The return value will be 1. | |
LBER_SB_OPT_SET_MAX_INCOMING | |
Sets the maximum allowed size of an incoming message;
arg must be a
ber_len_t *. The return value will be 1.
| |
Options not in this list will be passed down to each
Sockbuf_IO handler in turn until one of them processes it. If the option is not handled
ber_sockbuf_ctrl() will return 0.
| |
Multiple Sockbuf_IO handlers can be stacked in multiple layers to provide various functionality. Currently defined layers include | |
LBER_SBIOD_LEVEL_PROVIDER | |
the lowest layer, talking directly to a network | |
LBER_SBIOD_LEVEL_TRANSPORT | |
an intermediate layer | |
LBER_SBIOD_LEVEL_APPLICATION | |
a higher layer | |
Currently defined Sockbuf_IO handlers in liblber include | |
ber_sockbuf_io_tcp | |
The default stream-oriented provider | |
ber_sockbuf_io_fd | |
A stream-oriented provider for local IPC sockets | |
ber_sockbuf_io_dgram | |
A datagram-oriented provider. This handler is only present if the liblber library was built with LDAP_CONNECTIONLESS defined. | |
ber_sockbuf_io_readahead | |
A buffering layer, usually used with a datagram provider to hide the datagram semantics from upper layers. | |
ber_sockbuf_io_debug | |
A generic handler that outputs hex dumps of all traffic. This handler may be inserted multiple times at arbitrary layers to show the flow of data between other handlers. | |
Additional handlers may be present in libldap if support for them was enabled: | |
ldap_pvt_sockbuf_io_sasl | |
An application layer handler for SASL encoding/decoding. | |
sb_tls_sbio | |
A transport layer handler for SSL/TLS encoding/decoding. Note that this handler is private to the library and is not exposed in the API. | |
SEE ALSO
lber-decode(3), lber-encode(3), lber-types(3), ldap_get_option(3)
ACKNOWLEDGEMENTS
OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from University of Michigan LDAP 3.3 Release.