Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kTcpServer.h
Go to the documentation of this file.
1 /**
2 * @file kTcpServer.h
3 * @brief Declares the kTcpServer class.
4 *
5 * @internal
6 * Copyright (C) 2008-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_TCP_SERVER_H
11 #define K_API_TCP_SERVER_H
12
13 #include <kApi/Io/kNetwork.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kTcpServer
19 * @extends kObject
20 * @ingroup kApi-Io
21 * @brief Represents a TCP server.
22 */
23 //typedef kObject kTcpServer; --forward-declared in kApiDef.x.h
24
25 /**
26 * Constructs a kTcpServer object.
27 *
28 * @public @memberof kTcpServer
29 * @param server Destination for the constructed object handle.
30 * @param ipVersion Internet Protocol version.
31 * @param allocator Memory allocator (or kNULL for default).
32 * @return Operation status.
33 */
34 kFx(kStatus) kTcpServer_Construct(kTcpServer* server, kIpVersion ipVersion, kAlloc allocator);
35
36 /**
37 * Sets the size of write buffers for accepted client sockets.
38 *
39 * Socket buffers decouple the sender and receiver, so that the sender does not need to block
40 * while waiting for the receiver to receive all bytes. Client buffers improve the efficiency
41 * of the client when performing several small write operations.
42 *
43 * By default, the client buffer size is zero and the socket buffer size is determined by the
44 * underlying operating system.
45 *
46 * @public @memberof kTcpServer
47 * @param server kTcpServer object.
48 * @param socketSize Size of the write buffer maintained by the underlying socket (-1 to leave unchanged).
49 * @param clientSize Size of the write buffer maintained by the client object (-1 to leave unchanged).
50 * @return Operation status.
51 */
52 kFx(kStatus) kTcpServer_SetWriteBuffers(kTcpServer server, kSSize socketSize, kSSize clientSize);
53
54 /**
55 * Sets the size of read buffers for accepted client sockets.
56 *
57 * Socket buffers decouple the sender and receiver, so that the sender does not need to block
58 * while waiting for the receiver to receive all bytes. Client buffers improve the efficiency
59 * of the client when performing several small read operations.
60 *
61 * @public @memberof kTcpServer
62 * @param server kTcpServer object.
63 * @param socketSize Size of the read buffer maintained by the underlying socket (-1 to leave unchanged).
64 * @param clientSize Size of the read buffer maintained by the client object (-1 to leave unchanged).
65 * @return Operation status.
66 */
67 kFx(kStatus) kTcpServer_SetReadBuffers(kTcpServer server, kSSize socketSize, kSSize clientSize);
68
69 /**
70 * Enables or disables reuse of a local end point within a short period of time.
71 *
72 * The option is typically used to allow a server to rebind to a local end point
73 * while a previous socket with the same local end point is in the TIME_WAIT state.
74 * This can be useful when a server must be stopped and started within a brief interval,
75 * but there is a small risk that packets with identical source/destination information
76 * could be misdirected to the new socket.
77 *
78 * @public @memberof kTcpServer
79 * @param server kTcpServer object.
80 * @param reuse kTRUE to enable reuse of IP addresses; kFALSE otherwise.
81 * @return Operation status.
82 */
83 kFx(kStatus) kTcpServer_EnableReuseAddress(kTcpServer server, kBool reuse);
84
85 /**
86 * Places the server into the listening state, to monitor for incoming connection requests.
87 *
88 * The server can be placed in the listening state only once per kTcpServer object. After
89 * the server is shut down, the kTcpServer object cannot be used to listen again on another port.
90 *
91 * @public @memberof kTcpServer
92 * @param server kTcpServer object.
93 * @param address A local IP address to which the server should bind, or kIpAddress_Any().
94 * @param port A local port number to which the server should bind, or kIP_PORT_ANY.
95 * @param backlog The maximum number of pending connection requests to enqueue.
96 * @return Operation status.
97 */
98 kFx(kStatus) kTcpServer_Listen(kTcpServer server, kIpAddress address, k32u port, kSize backlog);
99
100 /**
101 * Blocks until an incoming connection is established, or the specified timeout interval elapses.
102 *
103 * The returned connection object can be kNULL if the connection was closed by the remote client
104 * before being accepted.
105 *
106 * @public @memberof kTcpServer
107 * @param server A kTcpServer object in the listening state.
108 * @param timeout The timeout interval.
109 * @param client Returns a kTcpClient object representing the newly-established connection, or kNULL.
110 * @param allocator Memory allocator (or kNULL for default).
111 * @return Operation status.
112 */
113 kFx(kStatus) kTcpServer_Accept(kTcpServer server, k64u timeout, kTcpClient* client, kAlloc allocator);
114
115 /**
116 * Returns the underlying socket object.
117 *
118 * @public @memberof kTcpServer
119 * @param server kTcpServer object.
120 * @return Underlying socket object.
121 */
122 kFx(kSocket) kTcpServer_Socket(kTcpServer server);
123
124 /**
125 * Returns the local end point for a listening server.
126 *
127 * @public @memberof kTcpServer
128 * @param server kTcpServer object.
129 * @param endPoint Local end point.
130 * @return Operation status.
131 */
132 kFx(kStatus) kTcpServer_LocalEndPoint(kTcpServer server, kIpEndPoint* endPoint);
133
134 kEndHeader()
135
136 #include <kApi/Io/kTcpServer.x.h>
137
138 #endif
k32u
Represents a 32-bit unsigned integer.
kTcpServer::kTcpServer_Construct
kStatus kTcpServer_Construct(kTcpServer *server, kIpVersion ipVersion, kAlloc allocator)
Constructs a kTcpServer object.
kTcpServer::kTcpServer_Listen
kStatus kTcpServer_Listen(kTcpServer server, kIpAddress address, k32u port, kSize backlog)
Places the server into the listening state, to monitor for incoming connection requests.
k64u
Represents a 64-bit unsigned integer.
kIpVersion
Internet Protocol version enumeration.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kIpAddress
Represents an IP address.
Definition: kNetwork.h:36
kSSize
Represents a signed integer that can store a pointer address.
kTcpServer::kTcpServer_EnableReuseAddress
kStatus kTcpServer_EnableReuseAddress(kTcpServer server, kBool reuse)
Enables or disables reuse of a local end point within a short period of time.
kTcpServer::kTcpServer_SetReadBuffers
kStatus kTcpServer_SetReadBuffers(kTcpServer server, kSSize socketSize, kSSize clientSize)
Sets the size of read buffers for accepted client sockets.
kTcpServer::kTcpServer_LocalEndPoint
kStatus kTcpServer_LocalEndPoint(kTcpServer server, kIpEndPoint *endPoint)
Returns the local end point for a listening server.
kTcpServer
Represents a TCP server.
kTcpClient
Represents a TCP client.
kTcpServer::kTcpServer_SetWriteBuffers
kStatus kTcpServer_SetWriteBuffers(kTcpServer server, kSSize socketSize, kSSize clientSize)
Sets the size of write buffers for accepted client sockets.
kTcpServer::kTcpServer_Socket
kSocket kTcpServer_Socket(kTcpServer server)
Returns the underlying socket object.
kNetwork.h
IP networking definitions.
kTcpServer::kTcpServer_Accept
kStatus kTcpServer_Accept(kTcpServer server, k64u timeout, kTcpClient *client, kAlloc allocator)
Blocks until an incoming connection is established, or the specified timeout interval elapses...
kStatus
Represents an enumeration of error codes.
kIpEndPoint
Represents an IP end point (address, port).
Definition: kNetwork.h:171
kSocket
Represents a network socket.
kBool
Represents a boolean value.