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