Merge pull request #278 from nmav/ocserv
[project/luci.git] / libs / nixio / docsrc / nixio.TLSSocket.lua
1 --- TLS Socket Object.
2 -- TLS Sockets contain the underlying socket and context in the fields
3 -- "socket" and "context".
4 -- @cstyle      instance
5 module "nixio.TLSSocket"
6
7 --- Initiate the TLS handshake as client with the server.
8 -- @class function
9 -- @name TLSSocket.connect
10 -- @usage This function calls SSL_connect().
11 -- @usage You have to call either connect or accept before transmitting data.
12 -- @see TLSSocket.accept
13 -- @return true
14
15 --- Wait for a TLS handshake from a client.
16 -- @class function
17 -- @name TLSSocket.accept
18 -- @usage This function calls SSL_accept().
19 -- @usage You have to call either connect or accept before transmitting data.
20 -- @see TLSSocket.connect
21 -- @return      true
22
23 --- Send a message to the socket.
24 -- @class function
25 -- @name TLSSocket.send
26 -- @usage This function calls SSL_write().
27 -- @usage <strong>Warning:</strong> It is not guaranteed that all data
28 -- in the buffer is written at once.
29 -- You have to check the return value - the number of bytes actually written -
30 -- or use the safe IO functions in the high-level IO utility module.
31 -- @usage Unlike standard Lua indexing the lowest offset and default is 0.
32 -- @param buffer        Buffer holding the data to be written.
33 -- @param offset        Offset to start reading the buffer from. (optional)
34 -- @param length        Length of chunk to read from the buffer. (optional)
35 -- @return number of bytes written
36
37 --- Send a message on the socket (This is an alias for send).
38 -- See the send description for a detailed description.
39 -- @class function
40 -- @name TLSSocket.write
41 -- @param buffer        Buffer holding the data to be written.
42 -- @param offset        Offset to start reading the buffer from. (optional)
43 -- @param length        Length of chunk to read from the buffer. (optional)
44 -- @see TLSSocket.send
45 -- @return number of bytes written
46
47 --- Receive a message on the socket.
48 -- @class function
49 -- @name TLSSocket.recv
50 -- @usage This function calls SSL_read().
51 -- @usage <strong>Warning:</strong> It is not guaranteed that all requested data
52 -- is read at once.
53 -- You have to check the return value - the length of the buffer actually read -
54 -- or use the safe IO functions in the high-level IO utility module.
55 -- @usage The length of the return buffer is limited by the (compile time) 
56 -- nixio buffersize which is <em>nixio.const.buffersize</em> (8192 by default).
57 -- Any read request greater than that will be safely truncated to this value.  
58 -- @param length        Amount of data to read (in Bytes).
59 -- @return buffer containing data successfully read
60
61 --- Receive a message on the socket (This is an alias for recv).
62 -- See the recv description for more details.
63 -- @class function
64 -- @name TLSSocket.read  
65 -- @param length        Amount of data to read (in Bytes).
66 -- @see TLSSocket.recv
67 -- @return buffer containing data successfully read
68
69 --- Shut down the TLS connection.
70 -- @class function
71 -- @name TLSSocket.shutdown
72 -- @usage This function calls SSL_shutdown().
73 -- @return      true