From bace21247493eb38870d2585f0e643bdc550f60a Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Thu, 14 Sep 2000 12:44:34 +0000 Subject: [PATCH] Initial connect BIO docs. --- doc/crypto/BIO_s_connect.pod | 131 +++++++++++++++++++++++++++++++++++ doc/crypto/BIO_s_fd.pod | 2 +- doc/crypto/BIO_s_socket.pod | 6 +- 3 files changed, 135 insertions(+), 4 deletions(-) create mode 100644 doc/crypto/BIO_s_connect.pod diff --git a/doc/crypto/BIO_s_connect.pod b/doc/crypto/BIO_s_connect.pod new file mode 100644 index 0000000000..08a9e6473e --- /dev/null +++ b/doc/crypto/BIO_s_connect.pod @@ -0,0 +1,131 @@ +=pod + +=head1 NAME + + BIO_s_connect - connect BIO + +=head1 SYNOPSIS + + #include + + BIO_METHOD * BIO_s_connect(void); + + #define BIO_set_conn_hostname(b,name) BIO_ctrl(b,BIO_C_SET_CONNECT,0,(char *)name) + #define BIO_set_conn_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,1,(char *)port) + #define BIO_set_conn_ip(b,ip) BIO_ctrl(b,BIO_C_SET_CONNECT,2,(char *)ip) + #define BIO_set_conn_int_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,3,(char *)port) + #define BIO_get_conn_hostname(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,0) + #define BIO_get_conn_port(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,1) + #define BIO_get_conn_ip(b,ip) BIO_ptr_ctrl(b,BIO_C_SET_CONNECT,2) + #define BIO_get_conn_int_port(b,port) BIO_int_ctrl(b,BIO_C_SET_CONNECT,3,port) + + #define BIO_set_nbio(b,n) BIO_ctrl(b,BIO_C_SET_NBIO,(n),NULL) + + #define BIO_do_connect(b) BIO_do_handshake(b) + +=head1 DESCRIPTION + +BIO_s_connect() returns the connect BIO method. This is a wrapper +round the platform's TCP/IP socket connection routines. + +Using connect BIOs TCP/IP connections can be made and data +transferred using only BIO routines. In this way any platform +specific operations are hidden by the BIO abstraction. + +Read and write operations on a connect BIO will perform I/O +on the underlying connection. If no connection is established +and the port and hostname (see below) is set up properly then +a connection is established first. + +Connect BIOs support BIO_puts() but not BIO_gets(). + +If the close flag is set on a connect BIO then any active +connection is shutdown and the socket closed when the BIO +is freed. + +Calling BIO_reset() on a connect BIO will close any active +connection and reset the BIO into a state where it can connect +to the same host again. + +BIO_get_fd() places the underlying socket in B if it is not NULL, +it also returns the socket . If B is not NULL it should be of +type (int *). + +BIO_set_conn_hostname() uses the string B to set the hostname +The hostname can be an IP address. The hostname can also include the +port in the form hostname:port . It is also acceptable to use the +form "hostname/any/other/path" or "hostname:port/any/other/path". + +BIO_set_conn_port() sets the port to B. B can be the +numerical form or a string such as "http". A string will be looked +up first using getservbyname() on the host platform but if that +fails a standard table of port names will be used. Currently the +list is http, telnet, socks, https, ssl, ftp, gopher and wais. + +BIO_set_conn_ip() sets the IP address to B using binary form, +that is four bytes specifying the IP address in big endian form. + +BIO_set_conn_int_port() sets the port using B. B should +be of type (int *). + +BIO_get_conn_hostname() returns the hostname of the connect BIO or +NULL if the BIO is initialised but no hostname is set. +This return value is an internal pointer which should not be modified. + +BIO_get_conn_port() returns the port as a string. + +BIO_get_conn_ip() returns the IP address in binary form. + +BIO_get_conn_int_port() returns the host name as an int. + +BIO_set_nbio() sets the non blocking I/O flag to B. If B is +zero then blocking I/O is set. If B is 1 then non blocking I/O +is set. + +BIO_do_connect() attempts to connect the supplied BIO. It returns 1 +if the connection was established successfully. A zero or negative +value is returned if the connection could not be established, the +call BIO_should_retry() should be used for non blocking connect BIOs +to determine if the call should be retried. + + +=head1 NOTES + +If blocking I/O is set then a non positive return value from any +I/O call is caused by an error condition, although a zero return +will normally mean that the connection was closed. + +If the port name is supplied as part of the host name then this will +override any value set with BIO_set_conn_port(). + +The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(), +BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a +connection attempt is made. Before any connection attempt the values +returned are those set by the application itself. + +Applications do not have to call BIO_do_connect() but can do so to +separate the connection process from other I/O processing. + +If non blocking I/O is set then retries will be requested as appropriate. + +It addition to BIO_should_read() and BIO_should_write() it is also +possible for BIO_should_io_special() to be true during the initial +connection process with the reason BIO_RR_CONNECT. If this is returned +then this is an indication that a connection attempt would block, +the application should then take appropiate action to wait until +the underlying socket has connected and retry the call. + +=head1 RETURN VALUES + +BIO_s_connect() returns the connect BIO method. + +BIO_get_fd() returns the socket or -1 if the BIO has not +been initialised. + +=head1 EXAMPLES + +TBA + +=head1 SEE ALSO + +TBA diff --git a/doc/crypto/BIO_s_fd.pod b/doc/crypto/BIO_s_fd.pod index 6f0341e1ed..e5b9c811a6 100644 --- a/doc/crypto/BIO_s_fd.pod +++ b/doc/crypto/BIO_s_fd.pod @@ -20,7 +20,7 @@ BIO_s_fd - file descriptor BIO =head1 DESCRIPTION -BIO_f_fd() returns the file descriptor BIO method. This is a wrapper +BIO_s_fd() returns the file descriptor BIO method. This is a wrapper round the platforms file descriptor routines such as read() and write(). BIO_read() and BIO_write() read or write the underlying descriptor. diff --git a/doc/crypto/BIO_s_socket.pod b/doc/crypto/BIO_s_socket.pod index b8e25db22e..54f2b2343b 100644 --- a/doc/crypto/BIO_s_socket.pod +++ b/doc/crypto/BIO_s_socket.pod @@ -17,7 +17,7 @@ BIO_s_socket - socket BIO =head1 DESCRIPTION -BIO_f_socket() returns the socket BIO method. This is a wrapper +BIO_s_socket() returns the socket BIO method. This is a wrapper round the platform's socket routines. BIO_read() and BIO_write() read or write the underlying socket. @@ -50,8 +50,8 @@ BIO_s_socket() returns the socket BIO method. BIO_set_fd() always returns 1. -BIO_get_fd() returns the file descriptor or -1 if the BIO has not -been initialised. +BIO_get_fd() returns the socket or -1 if the BIO has not been +initialised. BIO_new_socket() returns the newly allocated BIO or NULL is an error occurred. -- 2.25.1