PageRenderTime 48ms CodeModel.GetById 2ms app.highlight 38ms RepoModel.GetById 1ms app.codeStats 0ms

/OOO330_m20/sal/inc/osl/socket.h

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