]>
Commit | Line | Data |
---|---|---|
bace2124 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
7fcc8326 | 5 | BIO_s_connect - connect BIO |
bace2124 DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/bio.h> | |
10 | ||
11 | BIO_METHOD * BIO_s_connect(void); | |
12 | ||
13 | #define BIO_set_conn_hostname(b,name) BIO_ctrl(b,BIO_C_SET_CONNECT,0,(char *)name) | |
14 | #define BIO_set_conn_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,1,(char *)port) | |
15 | #define BIO_set_conn_ip(b,ip) BIO_ctrl(b,BIO_C_SET_CONNECT,2,(char *)ip) | |
16 | #define BIO_set_conn_int_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,3,(char *)port) | |
17 | #define BIO_get_conn_hostname(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,0) | |
18 | #define BIO_get_conn_port(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,1) | |
19 | #define BIO_get_conn_ip(b,ip) BIO_ptr_ctrl(b,BIO_C_SET_CONNECT,2) | |
20 | #define BIO_get_conn_int_port(b,port) BIO_int_ctrl(b,BIO_C_SET_CONNECT,3,port) | |
21 | ||
22 | #define BIO_set_nbio(b,n) BIO_ctrl(b,BIO_C_SET_NBIO,(n),NULL) | |
23 | ||
24 | #define BIO_do_connect(b) BIO_do_handshake(b) | |
25 | ||
26 | =head1 DESCRIPTION | |
27 | ||
28 | BIO_s_connect() returns the connect BIO method. This is a wrapper | |
29 | round the platform's TCP/IP socket connection routines. | |
30 | ||
31 | Using connect BIOs TCP/IP connections can be made and data | |
32 | transferred using only BIO routines. In this way any platform | |
33 | specific operations are hidden by the BIO abstraction. | |
34 | ||
35 | Read and write operations on a connect BIO will perform I/O | |
36 | on the underlying connection. If no connection is established | |
37 | and the port and hostname (see below) is set up properly then | |
38 | a connection is established first. | |
39 | ||
40 | Connect BIOs support BIO_puts() but not BIO_gets(). | |
41 | ||
42 | If the close flag is set on a connect BIO then any active | |
43 | connection is shutdown and the socket closed when the BIO | |
44 | is freed. | |
45 | ||
46 | Calling BIO_reset() on a connect BIO will close any active | |
47 | connection and reset the BIO into a state where it can connect | |
48 | to the same host again. | |
49 | ||
50 | BIO_get_fd() places the underlying socket in B<c> if it is not NULL, | |
51 | it also returns the socket . If B<c> is not NULL it should be of | |
52 | type (int *). | |
53 | ||
54 | BIO_set_conn_hostname() uses the string B<name> to set the hostname | |
55 | The hostname can be an IP address. The hostname can also include the | |
56 | port in the form hostname:port . It is also acceptable to use the | |
57 | form "hostname/any/other/path" or "hostname:port/any/other/path". | |
58 | ||
59 | BIO_set_conn_port() sets the port to B<port>. B<port> can be the | |
60 | numerical form or a string such as "http". A string will be looked | |
61 | up first using getservbyname() on the host platform but if that | |
62 | fails a standard table of port names will be used. Currently the | |
63 | list is http, telnet, socks, https, ssl, ftp, gopher and wais. | |
64 | ||
65 | BIO_set_conn_ip() sets the IP address to B<ip> using binary form, | |
66 | that is four bytes specifying the IP address in big endian form. | |
67 | ||
68 | BIO_set_conn_int_port() sets the port using B<port>. B<port> should | |
69 | be of type (int *). | |
70 | ||
71 | BIO_get_conn_hostname() returns the hostname of the connect BIO or | |
72 | NULL if the BIO is initialised but no hostname is set. | |
73 | This return value is an internal pointer which should not be modified. | |
74 | ||
75 | BIO_get_conn_port() returns the port as a string. | |
76 | ||
77 | BIO_get_conn_ip() returns the IP address in binary form. | |
78 | ||
79 | BIO_get_conn_int_port() returns the host name as an int. | |
80 | ||
81 | BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is | |
82 | zero then blocking I/O is set. If B<n> is 1 then non blocking I/O | |
83 | is set. | |
84 | ||
85 | BIO_do_connect() attempts to connect the supplied BIO. It returns 1 | |
86 | if the connection was established successfully. A zero or negative | |
87 | value is returned if the connection could not be established, the | |
88 | call BIO_should_retry() should be used for non blocking connect BIOs | |
89 | to determine if the call should be retried. | |
90 | ||
91 | ||
92 | =head1 NOTES | |
93 | ||
94 | If blocking I/O is set then a non positive return value from any | |
95 | I/O call is caused by an error condition, although a zero return | |
96 | will normally mean that the connection was closed. | |
97 | ||
98 | If the port name is supplied as part of the host name then this will | |
99 | override any value set with BIO_set_conn_port(). | |
100 | ||
101 | The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(), | |
102 | BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a | |
103 | connection attempt is made. Before any connection attempt the values | |
104 | returned are those set by the application itself. | |
105 | ||
106 | Applications do not have to call BIO_do_connect() but can do so to | |
107 | separate the connection process from other I/O processing. | |
108 | ||
109 | If non blocking I/O is set then retries will be requested as appropriate. | |
110 | ||
111 | It addition to BIO_should_read() and BIO_should_write() it is also | |
112 | possible for BIO_should_io_special() to be true during the initial | |
113 | connection process with the reason BIO_RR_CONNECT. If this is returned | |
114 | then this is an indication that a connection attempt would block, | |
115 | the application should then take appropiate action to wait until | |
116 | the underlying socket has connected and retry the call. | |
117 | ||
118 | =head1 RETURN VALUES | |
119 | ||
120 | BIO_s_connect() returns the connect BIO method. | |
121 | ||
122 | BIO_get_fd() returns the socket or -1 if the BIO has not | |
123 | been initialised. | |
124 | ||
125 | =head1 EXAMPLES | |
126 | ||
127 | TBA | |
128 | ||
129 | =head1 SEE ALSO | |
130 | ||
131 | TBA |