PageRenderTime 6ms CodeModel.GetById 2ms app.highlight 28ms RepoModel.GetById 1ms app.codeStats 0ms

/sal/inc/osl/socket.h

https://bitbucket.org/markjenkins/libreoffice_ubuntu-debian-fixes
C Header | 909 lines | 254 code | 116 blank | 539 comment | 0 complexity | 5ad2283d0657d94356cb32e630f41e74 MD5 | raw file
  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 _OSL_SOCKET_H_
 21#define _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
 30extern "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*/
 41typedef struct oslSocketAddrImpl * oslSocketAddr;
 42
 43
 44/**
 45    Represents the address-family of a socket
 46*/
 47typedef 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*/
 57typedef 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*/
 70typedef 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*/
 84typedef 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*/
110typedef 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*/
121typedef 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*/
134typedef 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 */
144typedef 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 */
183typedef 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
192typedef sal_uInt8 oslSocketIpxNetNumber[4];
193typedef 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*/
206SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createEmptySocketAddr(
207        oslAddrFamily Family);
208
209
210/** Creates a new SocketAddress and fills it from Addr.
211*/
212SAL_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*/
219SAL_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*/
227SAL_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*/
239SAL_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*/
250SAL_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*/
257SAL_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*/
264SAL_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*/
273SAL_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*/
281SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getInetPortOfSocketAddr(
282        oslSocketAddr Addr);
283
284
285/** Sets the Port of Addr.
286    @param[in] Port is expected in host byte-order.
287    @return <code>sal_False</code> if Addr is not an inet-addr.
288*/
289SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setInetPortOfSocketAddr(
290        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*/
297SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getHostnameOfSocketAddr(
298        oslSocketAddr Addr, rtl_uString **strHostname);
299
300
301/** Gets the address in dotted decimal format.
302    @param strDottedInetAddr out-parameter. Contains the dotted decimal address
303    (e.g. 141.99.20.34) represented by the address.
304    If the address is invalid or not of type <code>osl_Socket_FamilyInet</code>,
305    it returns 0.
306    @return <code>osl_Socket_Ok</code> or <code>osl_Socket_Error</code>
307*/
308SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getDottedInetAddrOfSocketAddr(
309        oslSocketAddr Addr, rtl_uString **strDottedInetAddr);
310
311/** Sets the addr field in the struct sockaddr with pByteSeq. pByteSeq must be in network byte order.
312 */
313SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_setAddrOfSocketAddr(
314        oslSocketAddr Addr, sal_Sequence *pByteSeq );
315
316/** Returns the addr field in the struct sockaddr.
317    @param ppByteSeq out parameter. After the call, *ppByteSeq contains the ipadrress
318                     in network byteorder. *ppByteSeq may be 0 in case of an invalid socket handle.
319    @return <code>osl_Socket_Ok</code> or <code>osl_Socket_Error</code>
320 */
321SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getAddrOfSocketAddr(
322        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[in] strHostname The hostname to be stored.
332    @param[in] Addr The socket address to be stored.
333    @return The created address or 0 upon failure.
334*/
335SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddr(
336        rtl_uString *strHostname, const oslSocketAddr Addr);
337
338
339/** Create an oslHostAddr by resolving the given strHostname.
340    Successful name resolution should result in the fully qualified
341    domain name (FQDN) and it's address as hostname and socket address
342    members of the resulting oslHostAddr.
343    @param[in] strHostname The hostname to be resolved.
344    @return The resulting address or 0 upon failure.
345*/
346SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddrByName(rtl_uString *strHostname);
347
348
349/** Create an oslHostAddr by reverse resolution of the given Addr.
350    Successful name resolution should result in the fully qualified
351    domain name (FQDN) and it's address as hostname and socket address
352    members of the resulting oslHostAddr.
353    @param[in] Addr The socket address to be reverse resolved.
354    @return The resulting address or 0 upon failure.
355*/
356SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddrByAddr(const oslSocketAddr Addr);
357
358
359/** Create a copy of the given Addr.
360    @return The copied address or 0 upon failure.
361*/
362SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_copyHostAddr(const oslHostAddr Addr);
363
364
365/** Frees all resources allocated by Addr. The handle Addr must not
366    be used after the call anymore.
367*/
368SAL_DLLPUBLIC void SAL_CALL osl_destroyHostAddr(oslHostAddr Addr);
369
370
371/** Get the hostname member of Addr.
372    @return The hostname or 0 upon failure.
373*/
374SAL_DLLPUBLIC void SAL_CALL osl_getHostnameOfHostAddr(const oslHostAddr Addr, rtl_uString **strHostname);
375
376
377/** Get the socket address member of Addr.
378    @return The socket address or 0 upon failure.
379*/
380SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getSocketAddrOfHostAddr(const oslHostAddr Addr);
381
382/** Retrieve this machines hostname.
383    May not always be a fully qualified domain name (FQDN).
384    @param  strLocalHostname out-parameter. The string that receives the local host name.
385    @return <code>sal_True</code> upon success, <code>sal_False</code> otherwise.
386*/
387SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getLocalHostname(rtl_uString **strLocalHostname);
388
389
390/**@} end section oslHostAddr
391*/
392
393/**@{ begin section oslSocket
394*/
395
396
397/*-***************************************************************************/
398/* oslSocket */
399/*-***************************************************************************/
400
401typedef struct oslSocketImpl * oslSocket;
402
403/** increases the refcount of the socket handle by one
404 */
405SAL_DLLPUBLIC void SAL_CALL osl_acquireSocket( oslSocket Socket );
406
407/** decreases the refcount of the socket handle by one.
408
409    If the refcount drops to zero, the underlying socket handle
410    is destroyed and becomes invalid.
411 */
412SAL_DLLPUBLIC void SAL_CALL osl_releaseSocket( oslSocket Socket );
413
414/** Create a socket of the specified Family and Type. The semantic of
415    the Protocol parameter depends on the given family and type.
416    @return 0 if socket could not be created, otherwise you get a handle
417    to the allocated socket-datastructure.
418*/
419SAL_DLLPUBLIC oslSocket SAL_CALL osl_createSocket(
420                                    oslAddrFamily   Family,
421                                    oslSocketType   Type,
422                                    oslProtocol     Protocol);
423
424/** Retrieves the Address of the local end of the socket.
425    Note that a socket must be bound or connected before
426    a vaild address can be returned.
427    @return 0 if socket-address could not be created, otherwise you get
428    the created Socket-Address.
429*/
430SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getLocalAddrOfSocket(oslSocket Socket);
431
432/** Retrieves the Address of the remote end of the socket.
433    Note that a socket must be connected before
434    a vaild address can be returned.
435    @return 0 if socket-address could not be created, otherwise you get
436    the created Socket-Address.
437*/
438SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getPeerAddrOfSocket(oslSocket Socket);
439
440/** Binds the given address to the socket.
441    @param[in] Socket
442    @param[in] Addr
443    @return <code>sal_False</code> if the bind failed, <code> sal_True</code> if successful.
444    @see osl_getLastSocketError()
445*/
446SAL_DLLPUBLIC sal_Bool SAL_CALL osl_bindAddrToSocket(
447                                       oslSocket Socket,
448                                       oslSocketAddr Addr);
449
450/** Connects the socket to the given address.
451
452    @param[in] Socket a bound socket.
453    @param[in] Addr the peer address.
454    @param pTimeout Timeout value or NULL for blocking.
455
456    @return <code>osl_Socket_Ok</code> on successful connection,
457            <code>osl_Socket_TimedOut</code> if operation timed out,
458            <code>osl_Socket_Interrupted</code> if operation was interrupted
459            <code>osl_Socket_Error</code> if the connection failed.
460*/
461SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_connectSocketTo(
462                                        oslSocket Socket,
463                                        oslSocketAddr Addr,
464                                        const TimeValue* pTimeout);
465
466
467/** Prepares the socket to act as an acceptor of incoming connections.
468    You should call "listen" before you use "accept".
469    @param[in] MaxPendingConnections denotes the length of the queue of
470    pending connections for this socket. If MaxPendingConnections is
471    -1, the systems default value will be used (Usually 5).
472    @return <code>sal_False</code> if the listen failed.
473*/
474SAL_DLLPUBLIC sal_Bool SAL_CALL osl_listenOnSocket(
475                           oslSocket Socket,
476                           sal_Int32 MaxPendingConnections);
477
478
479/** Waits for an ingoing connection on the socket.
480    This call blocks if there is no incoming connection present.
481    @param[in] pAddr if pAddr is != 0, the peers address is returned.
482    @return 0 if the accept-call failed, otherwise you get a socket
483    representing the new connection.
484*/
485SAL_DLLPUBLIC oslSocket SAL_CALL osl_acceptConnectionOnSocket
486                                       (oslSocket Socket,
487                                       oslSocketAddr* pAddr);
488
489/** Tries to receive BytesToRead data from the connected socket,
490    if no error occurs. Note that incomplete recvs due to
491    packet boundaries may occur.
492
493    @param[in] Socket A connected socket to be used to listen on.
494    @param[out] pBuffer Points to a buffer that will be filled with the received
495    data.
496    @param[in] BytesToRead The number of bytes to read. pBuffer must have at least
497    this size.
498    @param[in] Flag Modifier for the call. Valid values are:
499    <ul>
500    <li><code>osl_Socket_MsgNormal</code>
501    <li><code>osl_Socket_MsgOOB</code>
502    <li><code>osl_Socket_MsgPeek</code>
503    <li><code>osl_Socket_MsgDontRoute</code>
504    <li><code>osl_Socket_MsgMaxIOVLen</code>
505    </ul>
506
507    @return the number of received bytes.
508*/
509SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_receiveSocket(
510                          oslSocket Socket,
511                          void* pBuffer,
512                           sal_uInt32 BytesToRead,
513                          oslSocketMsgFlag Flag);
514
515/** Tries to receives BufferSize data from the (usually unconnected)
516    (datagram-)socket, if no error occurs.
517
518    @param[in] Socket A bound socket to be used to listen for a datagram.
519    @param[out] SenderAddr A pointer to a created oslSocketAddr handle
520    or to a null handle. After the call, it will contain the constructed
521    oslSocketAddr of the datagrams sender. If pSenderAddr itself is 0,
522    it is ignored.
523    @param[out] pBuffer Points to a buffer that will be filled with the received
524    datagram.
525    @param[in] BufferSize The size of pBuffer.
526    @param[in] Flag Modifier for the call. Valid values are:
527    <ul>
528    <li><code>osl_Socket_MsgNormal</code>
529    <li><code>osl_Socket_MsgOOB</code>
530    <li><code>osl_Socket_MsgPeek</code>
531    <li><code>osl_Socket_MsgDontRoute</code>
532    <li><code>osl_Socket_MsgMaxIOVLen</code>
533    </ul>
534
535    @return the number of received bytes.
536*/
537SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_receiveFromSocket(
538                              oslSocket Socket,
539                              oslSocketAddr SenderAddr,
540                              void* pBuffer,
541                              sal_uInt32 BufferSize,
542                              oslSocketMsgFlag Flag);
543
544/** Tries to send BytesToSend data from the connected socket,
545    if no error occurs.
546
547    @param[in] Socket A connected socket.
548    @param[in] pBuffer Points to a buffer that contains the send-data.
549    @param[in] BytesToSend The number of bytes to send. pBuffer must have at least
550    this size.
551    @param[in] Flag Modifier for the call. Valid values are:
552    <ul>
553    <li><code>osl_Socket_MsgNormal</code>
554    <li><code>osl_Socket_MsgOOB</code>
555    <li><code>osl_Socket_MsgPeek</code>
556    <li><code>osl_Socket_MsgDontRoute</code>
557    <li><code>osl_Socket_MsgMaxIOVLen</code>
558    </ul>
559
560    @return the number of transfered bytes.
561*/
562SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendSocket(
563                       oslSocket Socket,
564                       const void* pBuffer,
565                        sal_uInt32 BytesToSend,
566                       oslSocketMsgFlag Flag);
567
568/** Tries to send one datagram with BytesToSend data to the given ReceiverAddr
569    via the (implicitly unconnected) datagram-socket.
570    Since there is only sent one packet, the function sends the data always complete
571    even with incomplete packet boundaries.
572
573    @param[in] Socket A bound or unbound socket. Socket will be bound
574    after a successful call.
575
576    @param[in] ReceiverAddr An initialized oslSocketAddress that contains
577    the destination address for this send.
578
579    @param[in] pBuffer Points to a buffer that contains the send-data.
580    @param[in] BytesToSend The number of bytes to send. pBuffer must have at least
581    this size.
582    @param Flag [in] Modifier for the call. Valid values are:
583    <ul>
584    <li><code>osl_Socket_MsgNormal</code>
585    <li><code>osl_Socket_MsgOOB</code>
586    <li><code>osl_Socket_MsgPeek</code>
587    <li><code>osl_Socket_MsgDontRoute</code>
588    <li><code>osl_Socket_MsgMaxIOVLen</code>
589    </ul>
590
591    @return the number of transfered bytes.
592*/
593SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendToSocket(
594                         oslSocket Socket,
595                         oslSocketAddr ReceiverAddr,
596                          const void* pBuffer,
597                         sal_uInt32 BytesToSend,
598                         oslSocketMsgFlag Flag);
599
600/** Checks if read operations will block.
601
602    You can specify a timeout-value in seconds/microseconds that denotes
603    how long the operation will block if the Socket is not ready.
604
605    @return <code>sal_True</code> if read operations (recv, recvFrom, accept) on the Socket
606    will NOT block; <code>sal_False</code> if it would block or if an error occurred.
607
608    @param Socket the Socket to perfom the operation on.
609    @param pTimeout if NULL, the operation will block without a timeout.
610*/
611SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isReceiveReady(
612        oslSocket Socket, const TimeValue* pTimeout);
613
614/** Checks if send operations will block.
615    You can specify a timeout-value in seconds/microseconds that denotes
616    how long the operation will block if the Socket is not ready.
617    @return <code>sal_True</code> if send operations (send, sendTo) on the Socket
618    will NOT block; <code>sal_False</code> if it would block or if an error occurred.
619
620    @param Socket the Socket to perfom the operation on.
621    @param pTimeout if NULL, the operation will block without a timeout. Otherwise
622    the time define by timeout value.
623*/
624SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isSendReady(
625        oslSocket Socket, const TimeValue* pTimeout);
626
627/** Checks if a request for out-of-band data will block.
628    You can specify a timeout-value in seconds/microseconds that denotes
629    how long the operation will block if the Socket has no pending OOB data.
630    @return <code>sal_True</code> if OOB-request operations (recv with appropriate flags)
631    on the Socket will NOT block; <code>sal_False</code> if it would block or if an error occurred.
632
633    @param Socket the Socket to perfom the operation on.
634    @param pTimeout if NULL, the operation will block without a timeout.
635*/
636SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isExceptionPending(
637        oslSocket Socket, const TimeValue* pTimeout);
638
639/** Shuts down communication on a connected socket.
640    @param Direction denotes which end of the socket
641    should be closed:
642    <ul>
643    <li> <code>osl_Socket_DirRead</code>    closes read operations.
644    <li> <code>osl_Socket_DirReadWrite</code> closes write operations.
645    <li> <code>osl_Socket_DirWrite</code> closes read and write operations.
646    </ul>
647    @return <code>sal_True</code> if the socket could be closed down.
648*/
649SAL_DLLPUBLIC sal_Bool SAL_CALL osl_shutdownSocket(oslSocket Socket,
650                           oslSocketDirection Direction);
651
652/** Retrieves attributes associated with the socket.
653    @param Socket is the socket to query.
654
655    @param Level selects the level for which an option should be queried.
656    Valid values are:
657    <ul>
658    <li> osl_sol_socket:    Socket Level
659    <li> osl_sol_tcp:       Level of Transmission Control Protocol
660    </ul>
661
662    @param Option denotes the option to query.
663    Valid values (depending on the Level) are:
664    <ul>
665    <li> <code>osl_Socket_Option_Debug</code><br>
666    (sal_Bool) Socket debug flag 1 = enabled, 0 = disabled.
667
668    <li> <code>osl_Socket_OptionAcceptConn</code><br>
669    <li> <code>osl_Socket_OptionReuseAddr</code><br>
670    (sal_Bool) Allows the socket to be bound to an address that is
671    already in use.
672    1 = multiple bound allowed, 0 = no multiple bounds allowed
673
674    <li><code>osl_Socket_OptionKeepAlive</code><br>
675    (sal_Bool) Keepalive packets are sent by the underlying socket.
676    1 = enabled, 0 = disabled
677
678    <li><code>osl_Socket_OptionDontRoute</code><br>
679    (sal_Bool) Do not route: send directly to interface.
680    1 = do not route , 0 = routing possible
681
682    <li><code>osl_Socket_OptionBroadcast</code><br>
683    (sal_Bool) Transmission of broadcast messages are allowed on the socket.
684    1 = transmission allowed, 0 = transmission disallowed
685
686    <li><code>osl_Socket_OptionUseLoopback</code><br>
687
688    <li><code>osl_Socket_OptionLinger</code><br>
689    (sal_Int32) Linger on close if unsent data is present.
690    0 = linger is off, > 0  = timeout in seconds.
691
692    <li><code>osl_Socket_OptionOOBinLine</code><br>
693
694
695    <li><code>osl_Socket_OptionSndBuf</code><br>
696    (sal_Int32) Size of the send buffer in bytes. Data is sent after
697    SndTimeo or when the buffer is full. This allows faster writing
698    to the socket.
699
700    <li><code>osl_Socket_OptionRcvBuf</code><br>
701    (sal_Int32) Size of the receive buffer in bytes. Data is sent after
702    SndTimeo or when the buffer is full. This allows faster writing
703    to the socket and larger packet sizes.
704
705    <li><code>osl_Socket_OptionSndLowat</code><br>
706
707    <li><code>osl_Socket_OptionRcvLowat</code><br>
708
709    <li><code>osl_Socket_OptionSndTimeo</code><br>
710    (sal_Int32) Data is sent after this timeout. This allows gathering
711    of data to send larger packages but increases latency times.
712
713    <li><code>osl_Socket_OptionRcvTimeo</code><br>
714
715    <li><code>osl_Socket_OptionError</code><br>
716    <li><code>osl_Socket_OptionType</code><br>
717
718    <li><code>osl_Socket_OptionTcpNoDelay</code><br>
719    Disables the Nagle algorithm for send coalescing. (Do not
720    collect data until a packet is full, instead send immediatly.
721    This increases network traffic but might improve latency-times.)
722    1 = disables the algorithm, 0 = keeps it enabled.
723    </ul>
724    If not above mentioned otherwise, the options are only valid for
725    level <code>osl_Socket_LevelSocket</code>.
726
727    @param pBuffer Pointer to a buffer large enough to take the desired
728    attribute-value.
729
730    @param BufferLen contains the length of the Buffer.
731
732    @return -1 if an error occurred or else the size of the data copied into
733    pBuffer.
734    @see osl_setSocketOption()
735*/
736SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getSocketOption( oslSocket Socket,
737                               oslSocketOptionLevel Level,
738                            oslSocketOption      Option,
739                            void*                pBuffer,
740                            sal_uInt32               BufferLen);
741
742/** Sets the sockets attributes.
743
744    @param Socket is the socket to modify.
745
746    @param Level selects the level for which an option should be changed.
747    Valid values are:
748    <ul>
749    <li> osl_sol_socket:    Socket Level
750    <li> osl_sol_tcp:       Level of Transmission Control Protocol
751    </ul>
752
753    @param Option denotes the option to modify. See osl_setSocketOption() for more
754    details.
755
756    @param pBuffer Pointer to a Buffer which contains the attribute-value.
757
758    @param BufferLen contains the length of the Buffer.
759
760    @return True if the option could be changed.
761*/
762SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setSocketOption( oslSocket Socket,
763                            oslSocketOptionLevel    Level,
764                            oslSocketOption         Option,
765                            void*                   pBuffer,
766                            sal_uInt32              BufferLen);
767
768/** Enables/disables non-blocking-mode of the socket.
769    @param Socket Change mode for this socket.
770    @param On <code>sal_True</code> enables non-blocking mode,
771              <code>sal_False</code> disables non-blocking mode.
772    @return <code>sal_True</code> if mode could be changed.
773*/
774SAL_DLLPUBLIC sal_Bool SAL_CALL osl_enableNonBlockingMode(
775        oslSocket Socket, sal_Bool On);
776
777
778/** Query state of non-blocking-mode of the socket.
779    @param Socket Query mode for this socket.
780    @return True if non-blocking-mode is enabled.
781*/
782SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isNonBlockingMode(
783        oslSocket Socket);
784
785
786/** Queries the socket for its type.
787    @return one of:
788    <ul>
789    <li> osl_Socket_TypeStream
790    <li> osl_Socket_TypeDgram
791    <li> osl_Socket_TypeRaw
792    <li> osl_Socket_TypeRdm
793    <li> osl_Socket_TypeSeqPacket
794    <li> osl_invalid_SocketType, if an error occurred
795    </ul>
796
797*/
798SAL_DLLPUBLIC oslSocketType SAL_CALL osl_getSocketType(
799        oslSocket Socket);
800
801/** returns  a string which describes the last socket error.
802    @param strError out-parameter. The string that receives the error message.
803*/
804SAL_DLLPUBLIC void SAL_CALL osl_getLastSocketErrorDescription(
805        oslSocket Socket, rtl_uString **strError);
806
807/** returns a constant decribing the last error for the socket system.
808    @return <code>osl_Socket_E_NONE</code> if no error occurred,
809            <code>osl_invalid_SocketError</code> if an unknown (unmapped)
810            error occurred, otherwise an enum describing the    error.
811*/
812SAL_DLLPUBLIC oslSocketError SAL_CALL osl_getLastSocketError(
813        oslSocket Socket);
814
815/** Type for the representation of socket sets.
816*/
817typedef struct oslSocketSetImpl * oslSocketSet;
818
819/** Creates a set of sockets to be used with osl_demultiplexSocketEvents().
820    @return A oslSocketSet or 0 if creation failed.
821*/
822SAL_DLLPUBLIC oslSocketSet SAL_CALL osl_createSocketSet(void);
823
824/** Destroys a oslSocketSet.
825*/
826SAL_DLLPUBLIC void SAL_CALL osl_destroySocketSet(oslSocketSet Set);
827
828/** Clears the set from all previously added sockets.
829    @param Set the set to be cleared.
830*/
831SAL_DLLPUBLIC void SAL_CALL osl_clearSocketSet(oslSocketSet Set);
832
833
834/** Adds a socket to the set.
835    @param Set the set were the socket is added.
836    @param Socket the socket to be added.
837*/
838SAL_DLLPUBLIC void SAL_CALL osl_addToSocketSet(oslSocketSet Set, oslSocket Socket);
839
840/** Removes a socket from the set.
841    @param Set the set were the socket is removed from.
842    @param Socket the socket to be removed.
843*/
844SAL_DLLPUBLIC void SAL_CALL osl_removeFromSocketSet(oslSocketSet Set, oslSocket Socket);
845
846/** Checks if socket is in the set.
847    @param Set the set to be checked.
848    @param Socket check if this socket is in the set.
849    @return <code>sal_True</code> if socket is in the set.
850*/
851SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isInSocketSet(oslSocketSet Set, oslSocket Socket);
852
853/** Checks multiple sockets for events.
854    @param IncomingSet Checks the sockets in this set
855    for incoming events (read, accept). If the set is 0,
856    it is just skipped.
857    @param OutgoingSet Checks the sockets in this set
858    for outgoing events (write, connect). If the set is 0,
859    it is just skipped.
860    @param OutOfBandSet Checks the sockets in this set
861    for out-of-band events. If the set is 0, it is just skipped.
862    @param pTimeout Address of the number of milliseconds to wait for events. If
863    *pTimeout is -1, the call will block until an event or an error
864    occurs.
865    @return -1 on errors, otherwise the number of sockets with
866    pending events. In case of timeout, the number might be 0.
867*/
868SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_demultiplexSocketEvents(oslSocketSet IncomingSet,
869                                    oslSocketSet OutgoingSet,
870                                    oslSocketSet OutOfBandSet,
871                                    const TimeValue* pTimeout);
872
873/** Closes the socket terminating any ongoing dataflow.
874 */
875SAL_DLLPUBLIC void SAL_CALL osl_closeSocket(oslSocket Socket);
876
877
878/** Retrieves n bytes from the stream and copies them into pBuffer.
879    The function avoids incomplete reads due to packet boundaries.
880    @param pBuffer receives the read data.
881    @param nSize the number of bytes to read. pBuffer must be large enough
882    to hold the n bytes!
883    @return the number of read bytes. The number will only be smaller than
884    n if an exceptional condition (e.g. connection closed) occurs.
885*/
886SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_readSocket( oslSocket Socket, void *pBuffer, sal_Int32 nSize );
887
888
889/** Writes n bytes from pBuffer to the stream. The method avoids
890    incomplete writes due to packet boundaries.
891    @param pBuffer contains the data to be written.
892    @param nSize the number of bytes to write.
893    @return the number of written bytes. The number will only be smaller than
894    nSize if an exceptional condition (e.g. connection closed) occurs.
895*/
896SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_writeSocket( oslSocket Socket, const void *pBuffer, sal_Int32 nSize );
897
898/**@} end section oslSocket
899*/
900
901
902
903#ifdef __cplusplus
904}
905#endif
906
907#endif  /* _OSL_SOCKET_H_ */
908
909/* vim:set shiftwidth=4 softtabstop=4 expandtab: */