Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kTcpClient.h
Go to the documentation of this file.
1 /**
2 * @file kTcpClient.h
3 * @brief Declares the kTcpClient 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_CLIENT_H
11 #define K_API_TCP_CLIENT_H
12
13 #include <kApi/Io/kNetwork.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kTcpClient
19 * @extends kStream
20 * @ingroup kApi-Io
21 * @brief Represents a TCP client.
22 */
23 //typedef kStream kTcpClient; --forward-declared in kApiDef.x.h
24
25 /**
26 * Constructs a TCP client object.
27 *
28 * @public @memberof kTcpClient
29 * @param client 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) kTcpClient_Construct(kTcpClient* client, kIpVersion ipVersion, kAlloc allocator);
35
36 /**
37 * Sets the size of write buffers.
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 kTcpClient
47 * @param client TCP client 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) kTcpClient_SetWriteBuffers(kTcpClient client, kSSize socketSize, kSSize clientSize);
53
54 /**
55 * Sets the size of read buffers.
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 kTcpClient
62 * @param client TCP client 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) kTcpClient_SetReadBuffers(kTcpClient client, kSSize socketSize, kSSize clientSize);
68
69 /**
70 * Sets the timeout duration for blocking write operations.
71 *
72 * By default, kTcpClient objects do not use a timeout interval and can block indefinitely.
73 *
74 * @public @memberof kTcpClient
75 * @param client TCP client object.
76 * @param timeout Timeout value, in microseconds.
77 * @return Operation status.
78 */
79 kFx(kStatus) kTcpClient_SetWriteTimeout(kTcpClient client, k64u timeout);
80
81 /**
82 * Sets the timeout duration for blocking read operations.
83 *
84 * By default, kTcpClient objects do not use a timeout interval and can block indefinitely.
85 *
86 * @public @memberof kTcpClient
87 * @param client TCP client object.
88 * @param timeout Timeout value, in microseconds.
89 * @return Operation status.
90 */
91 kFx(kStatus) kTcpClient_SetReadTimeout(kTcpClient client, k64u timeout);
92
93 /**
94 * Sets a cancel query handler, which can be used to asynchronously terminate read/write operations.
95 *
96 * kTcpClient_SetCancelHandler and kTcpClient_Cancel represent alternative approaches to I/O cancellation;
97 * use one or the other approach, but not both.
98 *
99 * @public @memberof kTcpClient
100 * @param client TCP client object.
101 * @param function Callback function.
102 * @param receiver Callback context.
103 * @return Operation status.
104 */
105 kFx(kStatus) kTcpClient_SetCancelHandler(kTcpClient client, kCallbackFx function, kPointer receiver);
106
107 /**
108 * Cancels any pending I/O operations.
109 *
110 * kTcpClient_SetCancelHandler and kTcpClient_Cancel represent alternative approaches to I/O cancellation;
111 * use one or the other approach, but not both.
112 *
113 * This method is thread-safe.
114 *
115 * @public @memberof kTcpClient
116 * @return Operation status.
117 */
118 kFx(kStatus) kTcpClient_Cancel(kTcpClient client);
119
120 /**
121 * Connects to a remote end point.
122 *
123 * A connection can be established only once per kTcpClient object.
124 *
125 * @public @memberof kTcpClient
126 * @param client TCP client object.
127 * @param address The remote IP address.
128 * @param port The remote port number.
129 * @param timeout Timeout interval, in microseconds.
130 * @return Operation status.
131 */
132 kFx(kStatus) kTcpClient_Connect(kTcpClient client, kIpAddress address, k32u port, k64u timeout);
133
134 /**
135 * Waits until the client has bytes to read or until the specified timeout period elapses.
136 *
137 * This function will return kERROR_TIMEOUT in the event that the client is not ready for reading by
138 * the end of the timeout period.
139 *
140 * @public @memberof kTcpClient
141 * @param client TCP client object.
142 * @param timeout Timeout interval, in microseconds.
143 * @return Operation status.
144 */
145 kFx(kStatus) kTcpClient_Wait(kTcpClient client, k64u timeout);
146
147 /**
148 * Returns the underlying kSocket object.
149 *
150 * @public @memberof kTcpClient
151 * @param client TCP client object.
152 * @return Operation status.
153 */
154 kFx(kSocket) kTcpClient_Socket(kTcpClient client);
155
156 /**
157 * Returns the number of bytes currently enqueued and available for reading.
158 *
159 * This function returns the count of bytes enqueued in the client's internal read buffer. This does
160 * not include any data enqueued in the underlying socket's read buffer.
161 *
162 * @public @memberof kTcpClient
163 * @param client TCP client object.
164 * @return Operation status.
165 */
166 kFx(kSize) kTcpClient_Available(kTcpClient client);
167
168 /**
169 * Returns the local end point for a connected client.
170 *
171 * @public @memberof kTcpClient
172 * @param client TCP client object.
173 * @param endPoint Local end point.
174 * @return Operation status.
175 */
176 kFx(kStatus) kTcpClient_LocalEndPoint(kTcpClient client, kIpEndPoint* endPoint);
177
178 /**
179 * Returns the remote end point for a connected client.
180 *
181 * @public @memberof kTcpClient
182 * @param client TCP client object.
183 * @param endPoint Remote end point.
184 * @return Operation status.
185 */
186 kFx(kStatus) kTcpClient_RemoteEndPoint(kTcpClient client, kIpEndPoint* endPoint);
187
188 /**
189 * Reports any internal errors that will prevent success of future communication attempts.
190 *
191 * @public @memberof kTcpClient
192 * @param client TCP client object.
193 * @return Client status.
194 */
195 kFx(kStatus) kTcpClient_Status(kTcpClient client);
196
197 kEndHeader()
198
199 #include <kApi/Io/kTcpClient.x.h>
200
201 #endif
kTcpClient::kTcpClient_SetWriteBuffers
kStatus kTcpClient_SetWriteBuffers(kTcpClient client, kSSize socketSize, kSSize clientSize)
Sets the size of write buffers.
k32u
Represents a 32-bit unsigned integer.
kTcpClient::kTcpClient_SetWriteTimeout
kStatus kTcpClient_SetWriteTimeout(kTcpClient client, k64u timeout)
Sets the timeout duration for blocking write operations.
k64u
Represents a 64-bit unsigned integer.
kIpVersion
Internet Protocol version enumeration.
kTcpClient::kTcpClient_Connect
kStatus kTcpClient_Connect(kTcpClient client, kIpAddress address, k32u port, k64u timeout)
Connects to a remote end point.
kCallbackFx
kStatus(kCall * kCallbackFx)(kPointer receiver, kPointer sender, void *args)
Callback signature for a generic event handler.
Definition: kApiDef.h:1030
kPointer
Represents a void pointer.
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
kTcpClient::kTcpClient_RemoteEndPoint
kStatus kTcpClient_RemoteEndPoint(kTcpClient client, kIpEndPoint *endPoint)
Returns the remote end point for a connected client.
kTcpClient::kTcpClient_Cancel
kStatus kTcpClient_Cancel(kTcpClient client)
Cancels any pending I/O operations.
kSSize
Represents a signed integer that can store a pointer address.
kTcpClient::kTcpClient_SetReadTimeout
kStatus kTcpClient_SetReadTimeout(kTcpClient client, k64u timeout)
Sets the timeout duration for blocking read operations.
kTcpClient::kTcpClient_SetReadBuffers
kStatus kTcpClient_SetReadBuffers(kTcpClient client, kSSize socketSize, kSSize clientSize)
Sets the size of read buffers.
kTcpClient::kTcpClient_LocalEndPoint
kStatus kTcpClient_LocalEndPoint(kTcpClient client, kIpEndPoint *endPoint)
Returns the local end point for a connected client.
kTcpClient
Represents a TCP client.
kTcpClient::kTcpClient_Socket
kSocket kTcpClient_Socket(kTcpClient client)
Returns the underlying kSocket object.
kTcpClient::kTcpClient_Status
kStatus kTcpClient_Status(kTcpClient client)
Reports any internal errors that will prevent success of future communication attempts.
kNetwork.h
IP networking definitions.
kTcpClient::kTcpClient_SetCancelHandler
kStatus kTcpClient_SetCancelHandler(kTcpClient client, kCallbackFx function, kPointer receiver)
Sets a cancel query handler, which can be used to asynchronously terminate read/write operations...
kStatus
Represents an enumeration of error codes.
kIpEndPoint
Represents an IP end point (address, port).
Definition: kNetwork.h:171
kTcpClient::kTcpClient_Available
kSize kTcpClient_Available(kTcpClient client)
Returns the number of bytes currently enqueued and available for reading.
kTcpClient::kTcpClient_Construct
kStatus kTcpClient_Construct(kTcpClient *client, kIpVersion ipVersion, kAlloc allocator)
Constructs a TCP client object.
kSocket
Represents a network socket.
kTcpClient::kTcpClient_Wait
kStatus kTcpClient_Wait(kTcpClient client, k64u timeout)
Waits until the client has bytes to read or until the specified timeout period elapses.