1 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
2 | /* |
3 | * This file is part of the LibreOffice project. |
4 | * |
5 | * This Source Code Form is subject to the terms of the Mozilla Public |
6 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
7 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. |
8 | * |
9 | * This file incorporates work covered by the following license notice: |
10 | * |
11 | * Licensed to the Apache Software Foundation (ASF) under one or more |
12 | * contributor license agreements. See the NOTICE file distributed |
13 | * with this work for additional information regarding copyright |
14 | * ownership. The ASF licenses this file to you under the Apache |
15 | * License, Version 2.0 (the "License"); you may not use this file |
16 | * except in compliance with the License. You may obtain a copy of |
17 | * the License at http://www.apache.org/licenses/LICENSE-2.0 . |
18 | */ |
19 | |
20 | #ifndef INCLUDED_OSL_SOCKET_H |
21 | #define INCLUDED_OSL_SOCKET_H |
22 | |
23 | #include <rtl/ustring.h> |
24 | #include <rtl/byteseq.h> |
25 | |
26 | #include <osl/time.h> |
27 | #include <rtl/tencinfo.h> |
28 | |
29 | #ifdef __cplusplus |
30 | extern "C" { |
31 | #endif |
32 | |
33 | /* error returns */ |
34 | #define OSL_INADDR_NONE 0xffffffff |
35 | #define OSL_INVALID_PORT (-1) |
36 | #define OSL_INVALID_IPX_SOCKET_NO 0xffffffff |
37 | |
38 | /** |
39 | Opaque datatype SocketAddr. |
40 | */ |
41 | typedef struct oslSocketAddrImpl * oslSocketAddr; |
42 | |
43 | |
44 | /** |
45 | Represents the address-family of a socket |
46 | */ |
47 | typedef enum { |
48 | osl_Socket_FamilyInet, /* IP */ |
49 | osl_Socket_FamilyIpx, /* Novell IPX/SPX */ |
50 | osl_Socket_FamilyInvalid, /* always last entry in enum! */ |
51 | osl_Socket_Family_FORCE_EQUAL_SIZE = SAL_MAX_ENUM |
52 | } oslAddrFamily; |
53 | |
54 | /** |
55 | represent a specific protocol within a address-family |
56 | */ |
57 | typedef enum { |
58 | osl_Socket_ProtocolIp, /* for all af_inet */ |
59 | osl_Socket_ProtocolIpx, /* af_ipx datagram sockets (IPX) */ |
60 | osl_Socket_ProtocolSpx, /* af_ipx seqpacket or stream for SPX */ |
61 | osl_Socket_ProtocolSpxII, /* af_ipx seqpacket or stream for SPX II */ |
62 | osl_Socket_ProtocolInvalid, |
63 | osl_Socket_Protocol_FORCE_EQUAL_SIZE = SAL_MAX_ENUM |
64 | } oslProtocol; |
65 | |
66 | |
67 | /** |
68 | Represents the type of a socket |
69 | */ |
70 | typedef enum { |
71 | osl_Socket_TypeStream, |
72 | osl_Socket_TypeDgram, |
73 | osl_Socket_TypeRaw, |
74 | osl_Socket_TypeRdm, |
75 | osl_Socket_TypeSeqPacket, |
76 | osl_Socket_TypeInvalid, /* always last entry in enum! */ |
77 | osl_Socket_Type_FORCE_EQUAL_SIZE = SAL_MAX_ENUM |
78 | } oslSocketType; |
79 | |
80 | |
81 | /** |
82 | Represents socket-options |
83 | */ |
84 | typedef enum { |
85 | osl_Socket_OptionDebug, |
86 | osl_Socket_OptionAcceptConn, |
87 | osl_Socket_OptionReuseAddr, |
88 | osl_Socket_OptionKeepAlive, |
89 | osl_Socket_OptionDontRoute, |
90 | osl_Socket_OptionBroadcast, |
91 | osl_Socket_OptionUseLoopback, |
92 | osl_Socket_OptionLinger, |
93 | osl_Socket_OptionOOBinLine, |
94 | osl_Socket_OptionSndBuf, |
95 | osl_Socket_OptionRcvBuf, |
96 | osl_Socket_OptionSndLowat, |
97 | osl_Socket_OptionRcvLowat, |
98 | osl_Socket_OptionSndTimeo, |
99 | osl_Socket_OptionRcvTimeo, |
100 | osl_Socket_OptionError, |
101 | osl_Socket_OptionType, |
102 | osl_Socket_OptionTcpNoDelay, |
103 | osl_Socket_OptionInvalid, /* always last entry in enum! */ |
104 | osl_Socket_Option_FORCE_EQUAL_SIZE = SAL_MAX_ENUM |
105 | } oslSocketOption; |
106 | |
107 | /** |
108 | Represents the different socket-option levels |
109 | */ |
110 | typedef enum { |
111 | osl_Socket_LevelSocket, |
112 | osl_Socket_LevelTcp, |
113 | osl_Socket_LevelInvalid, /* always last entry in enum! */ |
114 | osl_Socket_Level_FORCE_EQUAL_SIZE = SAL_MAX_ENUM |
115 | } oslSocketOptionLevel; |
116 | |
117 | |
118 | /** |
119 | Represents flags to be used with send/recv-calls. |
120 | */ |
121 | typedef enum { |
122 | osl_Socket_MsgNormal, |
123 | osl_Socket_MsgOOB, |
124 | osl_Socket_MsgPeek, |
125 | osl_Socket_MsgDontRoute, |
126 | osl_Socket_MsgMaxIOVLen, |
127 | osl_Socket_MsgInvalid, /* always last entry in enum! */ |
128 | osl_Socket_Msg_FORCE_EQUAL_SIZE = SAL_MAX_ENUM |
129 | } oslSocketMsgFlag; |
130 | |
131 | /** |
132 | Used by shutdown to denote which end of the socket to "close". |
133 | */ |
134 | typedef enum { |
135 | osl_Socket_DirRead, |
136 | osl_Socket_DirWrite, |
137 | osl_Socket_DirReadWrite, |
138 | osl_Socket_DirInvalid, /* always last entry in enum! */ |
139 | osl_Socket_Dir_FORCE_EQUAL_SIZE = SAL_MAX_ENUM |
140 | } oslSocketDirection; |
141 | |
142 | /** Describes the various error socket error conditions, which may |
143 | occur */ |
144 | typedef enum { |
145 | osl_Socket_E_None, /* no error */ |
146 | osl_Socket_E_NotSocket, /* Socket operation on non-socket */ |
147 | osl_Socket_E_DestAddrReq, /* Destination address required */ |
148 | osl_Socket_E_MsgSize, /* Message too long */ |
149 | osl_Socket_E_Prototype, /* Protocol wrong type for socket */ |
150 | osl_Socket_E_NoProtocol, /* Protocol not available */ |
151 | osl_Socket_E_ProtocolNoSupport, /* Protocol not supported */ |
152 | osl_Socket_E_TypeNoSupport, /* Socket type not supported */ |
153 | osl_Socket_E_OpNotSupport, /* Operation not supported on socket */ |
154 | osl_Socket_E_PfNoSupport, /* Protocol family not supported */ |
155 | osl_Socket_E_AfNoSupport, /* Address family not supported by */ |
156 | /* protocol family */ |
157 | osl_Socket_E_AddrInUse, /* Address already in use */ |
158 | osl_Socket_E_AddrNotAvail, /* Can't assign requested address */ |
159 | osl_Socket_E_NetDown, /* Network is down */ |
160 | osl_Socket_E_NetUnreachable, /* Network is unreachable */ |
161 | osl_Socket_E_NetReset, /* Network dropped connection because */ |
162 | /* of reset */ |
163 | osl_Socket_E_ConnAborted, /* Software caused connection abort */ |
164 | osl_Socket_E_ConnReset, /* Connection reset by peer */ |
165 | osl_Socket_E_NoBufferSpace, /* No buffer space available */ |
166 | osl_Socket_E_IsConnected, /* Socket is already connected */ |
167 | osl_Socket_E_NotConnected, /* Socket is not connected */ |
168 | osl_Socket_E_Shutdown, /* Can't send after socket shutdown */ |
169 | osl_Socket_E_TooManyRefs, /* Too many references: can't splice */ |
170 | osl_Socket_E_TimedOut, /* Connection timed out */ |
171 | osl_Socket_E_ConnRefused, /* Connection refused */ |
172 | osl_Socket_E_HostDown, /* Host is down */ |
173 | osl_Socket_E_HostUnreachable, /* No route to host */ |
174 | osl_Socket_E_WouldBlock, /* call would block on non-blocking socket */ |
175 | osl_Socket_E_Already, /* operation already in progress */ |
176 | osl_Socket_E_InProgress, /* operation now in progress */ |
177 | osl_Socket_E_InvalidError, /* unmapped error: always last entry in enum! */ |
178 | osl_Socket_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM |
179 | } oslSocketError; |
180 | |
181 | /** Common return codes of socket related functions. |
182 | */ |
183 | typedef enum { |
184 | osl_Socket_Ok, /* successful completion */ |
185 | osl_Socket_Error, /* error occurred, check osl_getLastSocketError() for details */ |
186 | osl_Socket_TimedOut, /* blocking operation timed out */ |
187 | osl_Socket_Interrupted, /* blocking operation was interrupted */ |
188 | osl_Socket_InProgress, /* nonblocking operation is in progress */ |
189 | osl_Socket_FORCE_EQUAL_SIZE = SAL_MAX_ENUM |
190 | } oslSocketResult; |
191 | |
192 | typedef sal_uInt8 oslSocketIpxNetNumber[4]; |
193 | typedef sal_uInt8 oslSocketIpxNodeNumber[6]; |
194 | |
195 | /**@} end section types |
196 | */ |
197 | |
198 | /**@{ begin section oslSocketAddr |
199 | */ |
200 | |
201 | /** Creates a socket-address for the given family. |
202 | @param Family If family == osl_Socket_FamilyInet the address is |
203 | set to INADDR_ANY port 0. |
204 | @return 0 if address could not be created. |
205 | */ |
206 | SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createEmptySocketAddr( |
207 | oslAddrFamily Family); |
208 | |
209 | |
210 | /** Creates a new SocketAddress and fills it from Addr. |
211 | */ |
212 | SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_copySocketAddr( |
213 | oslSocketAddr Addr); |
214 | |
215 | /** Compares the values of two SocketAddresses. |
216 | @return <code>sal_True</code> if both addresses denote the same socket address, |
217 | <code>sal_False</code> otherwise. |
218 | */ |
219 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isEqualSocketAddr( |
220 | oslSocketAddr Addr1, oslSocketAddr Addr2); |
221 | |
222 | /** Uses the systems name-service interface to find an address for strHostname. |
223 | @param[in] strHostname The name for which you search for an address. |
224 | @return The desired address if one could be found, otherwise 0. |
225 | Don't forget to destroy the address if you don't need it any longer. |
226 | */ |
227 | SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_resolveHostname( |
228 | rtl_uString *strHostname); |
229 | |
230 | /** Create an internet address usable for sending broadcast datagrams. |
231 | To limit the broadcast to your subnet, pass your hosts IP address |
232 | in dotted decimal notation as first argument. |
233 | @see osl_sendToSocket() |
234 | @see oslSocketAddr |
235 | @param[in] strDottedAddr dotted decimal internet address, may be 0. |
236 | @param[in] Port port number in host byte order. |
237 | @return 0 if address could not be created. |
238 | */ |
239 | SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createInetBroadcastAddr ( |
240 | rtl_uString *strDottedAddr, sal_Int32 Port); |
241 | |
242 | |
243 | /** Create an internet-address, consisting of hostaddress and port. |
244 | We interpret strDottedAddr as a dotted-decimal inet-addr |
245 | (e.g. "141.99.128.50"). |
246 | @param strDottedAddr [in] String with dotted address. |
247 | @param Port [in] portnumber in host byte order. |
248 | @return 0 if address could not be created. |
249 | */ |
250 | SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createInetSocketAddr ( |
251 | rtl_uString *strDottedAddr, sal_Int32 Port); |
252 | |
253 | |
254 | /** Frees all resources allocated by Addr. The handle Addr must not |
255 | be used after the call anymore. |
256 | */ |
257 | SAL_DLLPUBLIC void SAL_CALL osl_destroySocketAddr( |
258 | oslSocketAddr Addr); |
259 | |
260 | /** Looks up the port-number designated to the specified service/protocol-pair. |
261 | (e.g. "ftp" "tcp"). |
262 | @return OSL_INVALID_PORT if no appropriate entry was found, otherwise the port-number. |
263 | */ |
264 | SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getServicePort( |
265 | rtl_uString *strServicename, rtl_uString *strProtocol); |
266 | |
267 | |
268 | |
269 | /** Retrieves the address-family from the Addr. |
270 | @return the family of the socket-address. |
271 | In case of an unknown family you get <code>osl_Socket_FamilyInvalid</code>. |
272 | */ |
273 | SAL_DLLPUBLIC oslAddrFamily SAL_CALL osl_getFamilyOfSocketAddr( |
274 | oslSocketAddr Addr); |
275 | |
276 | |
277 | /** Retrieves the internet port-number of Addr. |
278 | @return the port-number of the address in host-byte order. If Addr |
279 | is not an address of type <code>osl_Socket_FamilyInet</code>, it returns <code>OSL_INVALID_PORT</code> |
280 | */ |
281 | SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getInetPortOfSocketAddr( |
282 | oslSocketAddr Addr); |
283 | |
284 | |
285 | /** Sets the Port of Addr. |
286 | @param[in] Addr the SocketAddr to perfom the operation on. |
287 | @param[in] Port is expected in host byte-order. |
288 | @return <code>sal_False</code> if Addr is not an inet-addr. |
289 | */ |
290 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setInetPortOfSocketAddr( |
291 | oslSocketAddr Addr, sal_Int32 Port); |
292 | |
293 | |
294 | /** Returns the hostname represented by Addr. |
295 | @param[in] Addr The socket address from which to extract the hostname. |
296 | @param[out] strHostname The hostname represented by the address. If |
297 | there is no hostname to be found, it returns 0. |
298 | */ |
299 | SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getHostnameOfSocketAddr( |
300 | oslSocketAddr Addr, rtl_uString **strHostname); |
301 | |
302 | |
303 | /** Gets the address in dotted decimal format. |
304 | @param[in] Addr The socket address from which to extract the dotted decimal address. |
305 | @param[out] strDottedInetAddr Contains the dotted decimal address |
306 | (e.g. 141.99.20.34) represented by the address. |
307 | If the address is invalid or not of type <code>osl_Socket_FamilyInet</code>, |
308 | it returns 0. |
309 | @return <code>osl_Socket_Ok</code> or <code>osl_Socket_Error</code> |
310 | */ |
311 | SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getDottedInetAddrOfSocketAddr( |
312 | oslSocketAddr Addr, rtl_uString **strDottedInetAddr); |
313 | |
314 | /** Sets the addr field in the struct sockaddr with pByteSeq. pByteSeq must be in network byte order. |
315 | */ |
316 | SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_setAddrOfSocketAddr( |
317 | oslSocketAddr Addr, sal_Sequence *pByteSeq ); |
318 | |
319 | /** Returns the addr field in the struct sockaddr. |
320 | @param[in] Addr The socket address from which to extract the ipaddress. |
321 | @param[out] ppByteSeq After the call, *ppByteSeq contains the ipaddress |
322 | in network byteorder. *ppByteSeq may be 0 in case of an invalid socket handle. |
323 | @return <code>osl_Socket_Ok</code> or <code>osl_Socket_Error</code> |
324 | */ |
325 | SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getAddrOfSocketAddr( |
326 | oslSocketAddr Addr, sal_Sequence **ppByteSeq ); |
327 | |
328 | /* |
329 | Opaque datatype HostAddr. |
330 | */ |
331 | typedef struct oslHostAddrImpl * oslHostAddr; |
332 | |
333 | |
334 | /** Create an oslHostAddr from given hostname and socket address. |
335 | @param[in] strHostname The hostname to be stored. |
336 | @param[in] Addr The socket address to be stored. |
337 | @return The created address or 0 upon failure. |
338 | */ |
339 | SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddr( |
340 | rtl_uString *strHostname, const oslSocketAddr Addr); |
341 | |
342 | |
343 | /** Create an oslHostAddr by resolving the given strHostname. |
344 | Successful name resolution should result in the fully qualified |
345 | domain name (FQDN) and it's address as hostname and socket address |
346 | members of the resulting oslHostAddr. |
347 | @param[in] strHostname The hostname to be resolved. |
348 | @return The resulting address or 0 upon failure. |
349 | */ |
350 | SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddrByName(rtl_uString *strHostname); |
351 | |
352 | |
353 | /** Create an oslHostAddr by reverse resolution of the given Addr. |
354 | Successful name resolution should result in the fully qualified |
355 | domain name (FQDN) and it's address as hostname and socket address |
356 | members of the resulting oslHostAddr. |
357 | @param[in] Addr The socket address to be reverse resolved. |
358 | @return The resulting address or 0 upon failure. |
359 | */ |
360 | SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddrByAddr(const oslSocketAddr Addr); |
361 | |
362 | |
363 | /** Create a copy of the given Addr. |
364 | @return The copied address or 0 upon failure. |
365 | */ |
366 | SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_copyHostAddr(const oslHostAddr Addr); |
367 | |
368 | |
369 | /** Frees all resources allocated by Addr. The handle Addr must not |
370 | be used after the call anymore. |
371 | */ |
372 | SAL_DLLPUBLIC void SAL_CALL osl_destroyHostAddr(oslHostAddr Addr); |
373 | |
374 | |
375 | /** Get the hostname member of Addr. |
376 | @return The hostname or 0 upon failure. |
377 | */ |
378 | SAL_DLLPUBLIC void SAL_CALL osl_getHostnameOfHostAddr(const oslHostAddr Addr, rtl_uString **strHostname); |
379 | |
380 | |
381 | /** Get the socket address member of Addr. |
382 | @return The socket address or 0 upon failure. |
383 | */ |
384 | SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getSocketAddrOfHostAddr(const oslHostAddr Addr); |
385 | |
386 | /** Retrieve this machines hostname. |
387 | May not always be a fully qualified domain name (FQDN). |
388 | @param strLocalHostname out-parameter. The string that receives the local host name. |
389 | @return <code>sal_True</code> upon success, <code>sal_False</code> otherwise. |
390 | */ |
391 | SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getLocalHostname(rtl_uString **strLocalHostname); |
392 | |
393 | |
394 | /**@} end section oslHostAddr |
395 | */ |
396 | |
397 | /**@{ begin section oslSocket |
398 | */ |
399 | |
400 | |
401 | /*-***************************************************************************/ |
402 | /* oslSocket */ |
403 | /*-***************************************************************************/ |
404 | |
405 | typedef struct oslSocketImpl * oslSocket; |
406 | |
407 | /** increases the refcount of the socket handle by one |
408 | */ |
409 | SAL_DLLPUBLIC void SAL_CALL osl_acquireSocket( oslSocket Socket ); |
410 | |
411 | /** decreases the refcount of the socket handle by one. |
412 | |
413 | If the refcount drops to zero, the underlying socket handle |
414 | is destroyed and becomes invalid. |
415 | */ |
416 | SAL_DLLPUBLIC void SAL_CALL osl_releaseSocket( oslSocket Socket ); |
417 | |
418 | /** Create a socket of the specified Family and Type. The semantic of |
419 | the Protocol parameter depends on the given family and type. |
420 | @return 0 if socket could not be created, otherwise you get a handle |
421 | to the allocated socket-datastructure. |
422 | */ |
423 | SAL_DLLPUBLIC oslSocket SAL_CALL osl_createSocket( |
424 | oslAddrFamily Family, |
425 | oslSocketType Type, |
426 | oslProtocol Protocol); |
427 | |
428 | /** Retrieves the Address of the local end of the socket. |
429 | Note that a socket must be bound or connected before |
430 | a vaild address can be returned. |
431 | @return 0 if socket-address could not be created, otherwise you get |
432 | the created Socket-Address. |
433 | */ |
434 | SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getLocalAddrOfSocket(oslSocket Socket); |
435 | |
436 | /** Retrieves the Address of the remote end of the socket. |
437 | Note that a socket must be connected before |
438 | a vaild address can be returned. |
439 | @return 0 if socket-address could not be created, otherwise you get |
440 | the created Socket-Address. |
441 | */ |
442 | SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getPeerAddrOfSocket(oslSocket Socket); |
443 | |
444 | /** Binds the given address to the socket. |
445 | @param[in] Socket |
446 | @param[in] Addr |
447 | @return <code>sal_False</code> if the bind failed, <code> sal_True</code> if successful. |
448 | @see osl_getLastSocketError() |
449 | */ |
450 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_bindAddrToSocket( |
451 | oslSocket Socket, |
452 | oslSocketAddr Addr); |
453 | |
454 | /** Connects the socket to the given address. |
455 | |
456 | @param[in] Socket a bound socket. |
457 | @param[in] Addr the peer address. |
458 | @param pTimeout Timeout value or NULL for blocking. |
459 | |
460 | @return <code>osl_Socket_Ok</code> on successful connection, |
461 | <code>osl_Socket_TimedOut</code> if operation timed out, |
462 | <code>osl_Socket_Interrupted</code> if operation was interrupted |
463 | <code>osl_Socket_Error</code> if the connection failed. |
464 | */ |
465 | SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_connectSocketTo( |
466 | oslSocket Socket, |
467 | oslSocketAddr Addr, |
468 | const TimeValue* pTimeout); |
469 | |
470 | |
471 | /** Prepares the socket to act as an acceptor of incoming connections. |
472 | You should call "listen" before you use "accept". |
473 | @param[in] Socket The socket to listen on. |
474 | @param[in] MaxPendingConnections denotes the length of the queue of |
475 | pending connections for this socket. If MaxPendingConnections is |
476 | -1, the systems default value will be used (Usually 5). |
477 | @return <code>sal_False</code> if the listen failed. |
478 | */ |
479 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_listenOnSocket( |
480 | oslSocket Socket, |
481 | sal_Int32 MaxPendingConnections); |
482 | |
483 | |
484 | /** Waits for an ingoing connection on the socket. |
485 | This call blocks if there is no incoming connection present. |
486 | @param[in] Socket The socket to accept the connection on. |
487 | @param[in] pAddr if pAddr is != 0, the peers address is returned. |
488 | @return 0 if the accept-call failed, otherwise you get a socket |
489 | representing the new connection. |
490 | */ |
491 | SAL_DLLPUBLIC oslSocket SAL_CALL osl_acceptConnectionOnSocket |
492 | (oslSocket Socket, |
493 | oslSocketAddr* pAddr); |
494 | |
495 | /** Tries to receive BytesToRead data from the connected socket, |
496 | if no error occurs. Note that incomplete recvs due to |
497 | packet boundaries may occur. |
498 | |
499 | @param[in] Socket A connected socket to be used to listen on. |
500 | @param[out] pBuffer Points to a buffer that will be filled with the received |
501 | data. |
502 | @param[in] BytesToRead The number of bytes to read. pBuffer must have at least |
503 | this size. |
504 | @param[in] Flag Modifier for the call. Valid values are: |
505 | <ul> |
506 | <li><code>osl_Socket_MsgNormal</code> |
507 | <li><code>osl_Socket_MsgOOB</code> |
508 | <li><code>osl_Socket_MsgPeek</code> |
509 | <li><code>osl_Socket_MsgDontRoute</code> |
510 | <li><code>osl_Socket_MsgMaxIOVLen</code> |
511 | </ul> |
512 | |
513 | @return the number of received bytes. |
514 | */ |
515 | SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_receiveSocket( |
516 | oslSocket Socket, |
517 | void* pBuffer, |
518 | sal_uInt32 BytesToRead, |
519 | oslSocketMsgFlag Flag); |
520 | |
521 | /** Tries to receives BufferSize data from the (usually unconnected) |
522 | (datagram-)socket, if no error occurs. |
523 | |
524 | @param[in] Socket A bound socket to be used to listen for a datagram. |
525 | @param[out] SenderAddr A pointer to a created oslSocketAddr handle |
526 | or to a null handle. After the call, it will contain the constructed |
527 | oslSocketAddr of the datagrams sender. If pSenderAddr itself is 0, |
528 | it is ignored. |
529 | @param[out] pBuffer Points to a buffer that will be filled with the received |
530 | datagram. |
531 | @param[in] BufferSize The size of pBuffer. |
532 | @param[in] Flag Modifier for the call. Valid values are: |
533 | <ul> |
534 | <li><code>osl_Socket_MsgNormal</code> |
535 | <li><code>osl_Socket_MsgOOB</code> |
536 | <li><code>osl_Socket_MsgPeek</code> |
537 | <li><code>osl_Socket_MsgDontRoute</code> |
538 | <li><code>osl_Socket_MsgMaxIOVLen</code> |
539 | </ul> |
540 | |
541 | @return the number of received bytes. |
542 | */ |
543 | SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_receiveFromSocket( |
544 | oslSocket Socket, |
545 | oslSocketAddr SenderAddr, |
546 | void* pBuffer, |
547 | sal_uInt32 BufferSize, |
548 | oslSocketMsgFlag Flag); |
549 | |
550 | /** Tries to send BytesToSend data from the connected socket, |
551 | if no error occurs. |
552 | |
553 | @param[in] Socket A connected socket. |
554 | @param[in] pBuffer Points to a buffer that contains the send-data. |
555 | @param[in] BytesToSend The number of bytes to send. pBuffer must have at least |
556 | this size. |
557 | @param[in] Flag Modifier for the call. Valid values are: |
558 | <ul> |
559 | <li><code>osl_Socket_MsgNormal</code> |
560 | <li><code>osl_Socket_MsgOOB</code> |
561 | <li><code>osl_Socket_MsgPeek</code> |
562 | <li><code>osl_Socket_MsgDontRoute</code> |
563 | <li><code>osl_Socket_MsgMaxIOVLen</code> |
564 | </ul> |
565 | |
566 | @return the number of transfered bytes. |
567 | */ |
568 | SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendSocket( |
569 | oslSocket Socket, |
570 | const void* pBuffer, |
571 | sal_uInt32 BytesToSend, |
572 | oslSocketMsgFlag Flag); |
573 | |
574 | /** Tries to send one datagram with BytesToSend data to the given ReceiverAddr |
575 | via the (implicitly unconnected) datagram-socket. |
576 | Since there is only sent one packet, the function sends the data always complete |
577 | even with incomplete packet boundaries. |
578 | |
579 | @param[in] Socket A bound or unbound socket. Socket will be bound |
580 | after a successful call. |
581 | |
582 | @param[in] ReceiverAddr An initialized oslSocketAddress that contains |
583 | the destination address for this send. |
584 | |
585 | @param[in] pBuffer Points to a buffer that contains the send-data. |
586 | @param[in] BytesToSend The number of bytes to send. pBuffer must have at least |
587 | this size. |
588 | @param Flag [in] Modifier for the call. Valid values are: |
589 | <ul> |
590 | <li><code>osl_Socket_MsgNormal</code> |
591 | <li><code>osl_Socket_MsgOOB</code> |
592 | <li><code>osl_Socket_MsgPeek</code> |
593 | <li><code>osl_Socket_MsgDontRoute</code> |
594 | <li><code>osl_Socket_MsgMaxIOVLen</code> |
595 | </ul> |
596 | |
597 | @return the number of transfered bytes. |
598 | */ |
599 | SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendToSocket( |
600 | oslSocket Socket, |
601 | oslSocketAddr ReceiverAddr, |
602 | const void* pBuffer, |
603 | sal_uInt32 BytesToSend, |
604 | oslSocketMsgFlag Flag); |
605 | |
606 | /** Checks if read operations will block. |
607 | |
608 | You can specify a timeout-value in seconds/microseconds that denotes |
609 | how long the operation will block if the Socket is not ready. |
610 | |
611 | @return <code>sal_True</code> if read operations (recv, recvFrom, accept) on the Socket |
612 | will NOT block; <code>sal_False</code> if it would block or if an error occurred. |
613 | |
614 | @param Socket the Socket to perfom the operation on. |
615 | @param pTimeout if NULL, the operation will block without a timeout. |
616 | */ |
617 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isReceiveReady( |
618 | oslSocket Socket, const TimeValue* pTimeout); |
619 | |
620 | /** Checks if send operations will block. |
621 | You can specify a timeout-value in seconds/microseconds that denotes |
622 | how long the operation will block if the Socket is not ready. |
623 | @return <code>sal_True</code> if send operations (send, sendTo) on the Socket |
624 | will NOT block; <code>sal_False</code> if it would block or if an error occurred. |
625 | |
626 | @param Socket the Socket to perfom the operation on. |
627 | @param pTimeout if NULL, the operation will block without a timeout. Otherwise |
628 | the time define by timeout value. |
629 | */ |
630 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isSendReady( |
631 | oslSocket Socket, const TimeValue* pTimeout); |
632 | |
633 | /** Checks if a request for out-of-band data will block. |
634 | You can specify a timeout-value in seconds/microseconds that denotes |
635 | how long the operation will block if the Socket has no pending OOB data. |
636 | @return <code>sal_True</code> if OOB-request operations (recv with appropriate flags) |
637 | on the Socket will NOT block; <code>sal_False</code> if it would block or if an error occurred. |
638 | |
639 | @param Socket the Socket to perfom the operation on. |
640 | @param pTimeout if NULL, the operation will block without a timeout. |
641 | */ |
642 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isExceptionPending( |
643 | oslSocket Socket, const TimeValue* pTimeout); |
644 | |
645 | /** Shuts down communication on a connected socket. |
646 | @param[in] Socket the Socket to perfom the operation on. |
647 | @param[in] Direction denotes which end of the socket |
648 | should be closed: |
649 | <ul> |
650 | <li> <code>osl_Socket_DirRead</code> closes read operations. |
651 | <li> <code>osl_Socket_DirReadWrite</code> closes write operations. |
652 | <li> <code>osl_Socket_DirWrite</code> closes read and write operations. |
653 | </ul> |
654 | @return <code>sal_True</code> if the socket could be closed down. |
655 | */ |
656 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_shutdownSocket(oslSocket Socket, |
657 | oslSocketDirection Direction); |
658 | |
659 | /** Retrieves attributes associated with the socket. |
660 | @param Socket is the socket to query. |
661 | |
662 | @param Level selects the level for which an option should be queried. |
663 | Valid values are: |
664 | <ul> |
665 | <li> osl_sol_socket: Socket Level |
666 | <li> osl_sol_tcp: Level of Transmission Control Protocol |
667 | </ul> |
668 | |
669 | @param Option denotes the option to query. |
670 | Valid values (depending on the Level) are: |
671 | <ul> |
672 | <li> <code>osl_Socket_Option_Debug</code><br> |
673 | (sal_Bool) Socket debug flag 1 = enabled, 0 = disabled. |
674 | |
675 | <li> <code>osl_Socket_OptionAcceptConn</code><br> |
676 | <li> <code>osl_Socket_OptionReuseAddr</code><br> |
677 | (sal_Bool) Allows the socket to be bound to an address that is |
678 | already in use. |
679 | 1 = multiple bound allowed, 0 = no multiple bounds allowed |
680 | |
681 | <li><code>osl_Socket_OptionKeepAlive</code><br> |
682 | (sal_Bool) Keepalive packets are sent by the underlying socket. |
683 | 1 = enabled, 0 = disabled |
684 | |
685 | <li><code>osl_Socket_OptionDontRoute</code><br> |
686 | (sal_Bool) Do not route: send directly to interface. |
687 | 1 = do not route , 0 = routing possible |
688 | |
689 | <li><code>osl_Socket_OptionBroadcast</code><br> |
690 | (sal_Bool) Transmission of broadcast messages are allowed on the socket. |
691 | 1 = transmission allowed, 0 = transmission disallowed |
692 | |
693 | <li><code>osl_Socket_OptionUseLoopback</code><br> |
694 | |
695 | <li><code>osl_Socket_OptionLinger</code><br> |
696 | (sal_Int32) Linger on close if unsent data is present. |
697 | 0 = linger is off, > 0 = timeout in seconds. |
698 | |
699 | <li><code>osl_Socket_OptionOOBinLine</code><br> |
700 | |
701 | |
702 | <li><code>osl_Socket_OptionSndBuf</code><br> |
703 | (sal_Int32) Size of the send buffer in bytes. Data is sent after |
704 | SndTimeo or when the buffer is full. This allows faster writing |
705 | to the socket. |
706 | |
707 | <li><code>osl_Socket_OptionRcvBuf</code><br> |
708 | (sal_Int32) Size of the receive buffer in bytes. Data is sent after |
709 | SndTimeo or when the buffer is full. This allows faster writing |
710 | to the socket and larger packet sizes. |
711 | |
712 | <li><code>osl_Socket_OptionSndLowat</code><br> |
713 | |
714 | <li><code>osl_Socket_OptionRcvLowat</code><br> |
715 | |
716 | <li><code>osl_Socket_OptionSndTimeo</code><br> |
717 | (sal_Int32) Data is sent after this timeout. This allows gathering |
718 | of data to send larger packages but increases latency times. |
719 | |
720 | <li><code>osl_Socket_OptionRcvTimeo</code><br> |
721 | |
722 | <li><code>osl_Socket_OptionError</code><br> |
723 | <li><code>osl_Socket_OptionType</code><br> |
724 | |
725 | <li><code>osl_Socket_OptionTcpNoDelay</code><br> |
726 | Disables the Nagle algorithm for send coalescing. (Do not |
727 | collect data until a packet is full, instead send immediately. |
728 | This increases network traffic but might improve latency-times.) |
729 | 1 = disables the algorithm, 0 = keeps it enabled. |
730 | </ul> |
731 | If not above mentioned otherwise, the options are only valid for |
732 | level <code>osl_Socket_LevelSocket</code>. |
733 | |
734 | @param pBuffer Pointer to a buffer large enough to take the desired |
735 | attribute-value. |
736 | |
737 | @param BufferLen contains the length of the Buffer. |
738 | |
739 | @return -1 if an error occurred or else the size of the data copied into |
740 | pBuffer. |
741 | @see osl_setSocketOption() |
742 | */ |
743 | SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getSocketOption( oslSocket Socket, |
744 | oslSocketOptionLevel Level, |
745 | oslSocketOption Option, |
746 | void* pBuffer, |
747 | sal_uInt32 BufferLen); |
748 | |
749 | /** Sets the sockets attributes. |
750 | |
751 | @param Socket is the socket to modify. |
752 | |
753 | @param Level selects the level for which an option should be changed. |
754 | Valid values are: |
755 | <ul> |
756 | <li> osl_sol_socket: Socket Level |
757 | <li> osl_sol_tcp: Level of Transmission Control Protocol |
758 | </ul> |
759 | |
760 | @param Option denotes the option to modify. See osl_setSocketOption() for more |
761 | details. |
762 | |
763 | @param pBuffer Pointer to a Buffer which contains the attribute-value. |
764 | |
765 | @param BufferLen contains the length of the Buffer. |
766 | |
767 | @return True if the option could be changed. |
768 | */ |
769 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setSocketOption( oslSocket Socket, |
770 | oslSocketOptionLevel Level, |
771 | oslSocketOption Option, |
772 | void* pBuffer, |
773 | sal_uInt32 BufferLen); |
774 | |
775 | /** Enables/disables non-blocking-mode of the socket. |
776 | @param Socket Change mode for this socket. |
777 | @param On <code>sal_True</code> enables non-blocking mode, |
778 | <code>sal_False</code> disables non-blocking mode. |
779 | @return <code>sal_True</code> if mode could be changed. |
780 | */ |
781 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_enableNonBlockingMode( |
782 | oslSocket Socket, sal_Bool On); |
783 | |
784 | |
785 | /** Query state of non-blocking-mode of the socket. |
786 | @param Socket Query mode for this socket. |
787 | @return True if non-blocking-mode is enabled. |
788 | */ |
789 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isNonBlockingMode( |
790 | oslSocket Socket); |
791 | |
792 | |
793 | /** Queries the socket for its type. |
794 | @param[in] Socket The socket to query. |
795 | @return one of: |
796 | <ul> |
797 | <li> osl_Socket_TypeStream |
798 | <li> osl_Socket_TypeDgram |
799 | <li> osl_Socket_TypeRaw |
800 | <li> osl_Socket_TypeRdm |
801 | <li> osl_Socket_TypeSeqPacket |
802 | <li> osl_invalid_SocketType, if an error occurred |
803 | </ul> |
804 | */ |
805 | SAL_DLLPUBLIC oslSocketType SAL_CALL osl_getSocketType( |
806 | oslSocket Socket); |
807 | |
808 | /** returns a string which describes the last socket error. |
809 | @param[in] Socket The socket to query. |
810 | @param[out] strError The string that receives the error message. |
811 | */ |
812 | SAL_DLLPUBLIC void SAL_CALL osl_getLastSocketErrorDescription( |
813 | oslSocket Socket, rtl_uString **strError); |
814 | |
815 | /** returns a constant decribing the last error for the socket system. |
816 | @return <code>osl_Socket_E_NONE</code> if no error occurred, |
817 | <code>osl_invalid_SocketError</code> if an unknown (unmapped) |
818 | error occurred, otherwise an enum describing the error. |
819 | */ |
820 | SAL_DLLPUBLIC oslSocketError SAL_CALL osl_getLastSocketError( |
821 | oslSocket Socket); |
822 | |
823 | /** Type for the representation of socket sets. |
824 | */ |
825 | typedef struct oslSocketSetImpl * oslSocketSet; |
826 | |
827 | /** Creates a set of sockets to be used with osl_demultiplexSocketEvents(). |
828 | @return A oslSocketSet or 0 if creation failed. |
829 | */ |
830 | SAL_DLLPUBLIC oslSocketSet SAL_CALL osl_createSocketSet(void); |
831 | |
832 | /** Destroys a oslSocketSet. |
833 | */ |
834 | SAL_DLLPUBLIC void SAL_CALL osl_destroySocketSet(oslSocketSet Set); |
835 | |
836 | /** Clears the set from all previously added sockets. |
837 | @param Set the set to be cleared. |
838 | */ |
839 | SAL_DLLPUBLIC void SAL_CALL osl_clearSocketSet(oslSocketSet Set); |
840 | |
841 | |
842 | /** Adds a socket to the set. |
843 | @param Set the set were the socket is added. |
844 | @param Socket the socket to be added. |
845 | */ |
846 | SAL_DLLPUBLIC void SAL_CALL osl_addToSocketSet(oslSocketSet Set, oslSocket Socket); |
847 | |
848 | /** Removes a socket from the set. |
849 | @param Set the set were the socket is removed from. |
850 | @param Socket the socket to be removed. |
851 | */ |
852 | SAL_DLLPUBLIC void SAL_CALL osl_removeFromSocketSet(oslSocketSet Set, oslSocket Socket); |
853 | |
854 | /** Checks if socket is in the set. |
855 | @param Set the set to be checked. |
856 | @param Socket check if this socket is in the set. |
857 | @return <code>sal_True</code> if socket is in the set. |
858 | */ |
859 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isInSocketSet(oslSocketSet Set, oslSocket Socket); |
860 | |
861 | /** Checks multiple sockets for events. |
862 | @param IncomingSet Checks the sockets in this set |
863 | for incoming events (read, accept). If the set is 0, |
864 | it is just skipped. |
865 | @param OutgoingSet Checks the sockets in this set |
866 | for outgoing events (write, connect). If the set is 0, |
867 | it is just skipped. |
868 | @param OutOfBandSet Checks the sockets in this set |
869 | for out-of-band events. If the set is 0, it is just skipped. |
870 | @param pTimeout Address of the number of milliseconds to wait for events. If |
871 | *pTimeout is -1, the call will block until an event or an error |
872 | occurs. |
873 | @return -1 on errors, otherwise the number of sockets with |
874 | pending events. In case of timeout, the number might be 0. |
875 | */ |
876 | SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_demultiplexSocketEvents(oslSocketSet IncomingSet, |
877 | oslSocketSet OutgoingSet, |
878 | oslSocketSet OutOfBandSet, |
879 | const TimeValue* pTimeout); |
880 | |
881 | /** Closes the socket terminating any ongoing dataflow. |
882 | @param[in] Socket The socket to close. |
883 | */ |
884 | SAL_DLLPUBLIC void SAL_CALL osl_closeSocket(oslSocket Socket); |
885 | |
886 | |
887 | /** Retrieves n bytes from the stream and copies them into pBuffer. |
888 | The function avoids incomplete reads due to packet boundaries. |
889 | @param[in] Socket The socket to read from. |
890 | @param[out] pBuffer receives the read data. |
891 | @param[out] nSize the number of bytes to read. pBuffer must be large enough |
892 | to hold the n bytes! |
893 | @return the number of read bytes. The number will only be smaller than |
894 | n if an exceptional condition (e.g. connection closed) occurs. |
895 | */ |
896 | SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_readSocket( oslSocket Socket, void *pBuffer, sal_Int32 nSize ); |
897 | |
898 | |
899 | /** Writes n bytes from pBuffer to the stream. The method avoids |
900 | incomplete writes due to packet boundaries. |
901 | @param[out] Socket The socket to write to. |
902 | @param[in] pBuffer contains the data to be written. |
903 | @param[in] nSize the number of bytes to write. |
904 | @return the number of written bytes. The number will only be smaller than |
905 | nSize if an exceptional condition (e.g. connection closed) occurs. |
906 | */ |
907 | SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_writeSocket( oslSocket Socket, const void *pBuffer, sal_Int32 nSize ); |
908 | |
909 | /**@} end section oslSocket |
910 | */ |
911 | |
912 | |
913 | |
914 | #ifdef __cplusplus |
915 | } |
916 | #endif |
917 | |
918 | #endif // INCLUDED_OSL_SOCKET_H |
919 | |
920 | /* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |
921 | |