summaryrefslogtreecommitdiff
path: root/include/osl/socket.h
blob: f8ec7862b03ded1ed6f5c018b533761ce2c92be2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */

#ifndef INCLUDED_OSL_SOCKET_H
#define INCLUDED_OSL_SOCKET_H

#include <rtl/ustring.h>
#include <rtl/byteseq.h>

#include <osl/time.h>
#include <rtl/tencinfo.h>

#ifdef __cplusplus
extern "C" {
#endif

/* error returns */
#define OSL_INADDR_NONE             0xffffffff
#define OSL_INVALID_PORT (-1)
#define OSL_INVALID_IPX_SOCKET_NO   0xffffffff

/**
    Opaque datatype SocketAddr.
*/
typedef struct oslSocketAddrImpl * oslSocketAddr;


/**
    Represents the address-family of a socket
*/
typedef enum {
    osl_Socket_FamilyInet,      /* IP */
    osl_Socket_FamilyIpx,       /* Novell IPX/SPX */
    osl_Socket_FamilyInvalid,   /* always last entry in enum! */
    osl_Socket_Family_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
} oslAddrFamily;

/**
    represent a specific protocol within a address-family
*/
typedef enum {
    osl_Socket_ProtocolIp,      /* for all af_inet */
    osl_Socket_ProtocolIpx,     /* af_ipx datagram sockets (IPX) */
    osl_Socket_ProtocolSpx,     /* af_ipx seqpacket or stream for SPX */
    osl_Socket_ProtocolSpxII,   /* af_ipx seqpacket or stream for SPX II */
    osl_Socket_ProtocolInvalid,
    osl_Socket_Protocol_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
} oslProtocol;


/**
    Represents the type of a socket
*/
typedef enum {
    osl_Socket_TypeStream,
    osl_Socket_TypeDgram,
    osl_Socket_TypeRaw,
    osl_Socket_TypeRdm,
    osl_Socket_TypeSeqPacket,
    osl_Socket_TypeInvalid,     /* always last entry in enum! */
    osl_Socket_Type_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
} oslSocketType;


/**
    Represents socket-options
*/
typedef enum {
    osl_Socket_OptionDebug,
    osl_Socket_OptionAcceptConn,
    osl_Socket_OptionReuseAddr,
    osl_Socket_OptionKeepAlive,
    osl_Socket_OptionDontRoute,
    osl_Socket_OptionBroadcast,
    osl_Socket_OptionUseLoopback,
    osl_Socket_OptionLinger,
    osl_Socket_OptionOOBinLine,
    osl_Socket_OptionSndBuf,
    osl_Socket_OptionRcvBuf,
    osl_Socket_OptionSndLowat,
    osl_Socket_OptionRcvLowat,
    osl_Socket_OptionSndTimeo,
    osl_Socket_OptionRcvTimeo,
    osl_Socket_OptionError,
    osl_Socket_OptionType,
    osl_Socket_OptionTcpNoDelay,
    osl_Socket_OptionInvalid,       /* always last entry in enum! */
    osl_Socket_Option_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
} oslSocketOption;

/**
    Represents the different socket-option levels
*/
typedef enum  {
    osl_Socket_LevelSocket,
    osl_Socket_LevelTcp,
    osl_Socket_LevelInvalid,            /* always last entry in enum! */
    osl_Socket_Level_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
} oslSocketOptionLevel;


/**
    Represents flags to be used with send/recv-calls.
*/
typedef enum {
    osl_Socket_MsgNormal,
    osl_Socket_MsgOOB,
    osl_Socket_MsgPeek,
    osl_Socket_MsgDontRoute,
    osl_Socket_MsgMaxIOVLen,
    osl_Socket_MsgInvalid,          /* always last entry in enum! */
    osl_Socket_Msg_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
} oslSocketMsgFlag;

/**
    Used by shutdown to denote which end of the socket to "close".
*/
typedef enum {
    osl_Socket_DirRead,
    osl_Socket_DirWrite,
    osl_Socket_DirReadWrite,
    osl_Socket_DirInvalid,          /* always last entry in enum! */
    osl_Socket_Dir_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
} oslSocketDirection;

/** Describes the various error socket error conditions, which may
    occur */
typedef enum {
    osl_Socket_E_None,              /* no error */
    osl_Socket_E_NotSocket,         /* Socket operation on non-socket */
    osl_Socket_E_DestAddrReq,       /* Destination address required */
    osl_Socket_E_MsgSize,           /* Message too long */
    osl_Socket_E_Prototype,         /* Protocol wrong type for socket */
    osl_Socket_E_NoProtocol,        /* Protocol not available */
    osl_Socket_E_ProtocolNoSupport, /* Protocol not supported */
    osl_Socket_E_TypeNoSupport,     /* Socket type not supported */
    osl_Socket_E_OpNotSupport,      /* Operation not supported on socket */
    osl_Socket_E_PfNoSupport,       /* Protocol family not supported */
    osl_Socket_E_AfNoSupport,       /* Address family not supported by */
                                    /* protocol family */
    osl_Socket_E_AddrInUse,         /* Address already in use */
    osl_Socket_E_AddrNotAvail,      /* Can't assign requested address */
    osl_Socket_E_NetDown,           /* Network is down */
    osl_Socket_E_NetUnreachable,    /* Network is unreachable */
    osl_Socket_E_NetReset,          /* Network dropped connection because */
                                    /* of reset */
    osl_Socket_E_ConnAborted,       /* Software caused connection abort */
    osl_Socket_E_ConnReset,         /* Connection reset by peer */
    osl_Socket_E_NoBufferSpace,     /* No buffer space available */
    osl_Socket_E_IsConnected,       /* Socket is already connected */
    osl_Socket_E_NotConnected,      /* Socket is not connected */
    osl_Socket_E_Shutdown,          /* Can't send after socket shutdown */
    osl_Socket_E_TooManyRefs,       /* Too many references: can't splice */
    osl_Socket_E_TimedOut,          /* Connection timed out */
    osl_Socket_E_ConnRefused,       /* Connection refused */
    osl_Socket_E_HostDown,          /* Host is down */
    osl_Socket_E_HostUnreachable,   /* No route to host */
    osl_Socket_E_WouldBlock,        /* call would block on non-blocking socket */
    osl_Socket_E_Already,           /* operation already in progress */
    osl_Socket_E_InProgress,        /* operation now in progress */
    osl_Socket_E_InvalidError,      /* unmapped error: always last entry in enum! */
    osl_Socket_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
} oslSocketError;

/** Common return codes of socket related functions.
 */
typedef enum {
    osl_Socket_Ok,          /* successful completion */
    osl_Socket_Error,       /* error occurred, check osl_getLastSocketError() for details */
    osl_Socket_TimedOut,    /* blocking operation timed out */
    osl_Socket_Interrupted, /* blocking operation was interrupted */
    osl_Socket_InProgress,  /* nonblocking operation is in progress */
    osl_Socket_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
} oslSocketResult;

typedef sal_uInt8 oslSocketIpxNetNumber[4];
typedef sal_uInt8 oslSocketIpxNodeNumber[6];

/**@} end section types
*/

/**@{ begin section oslSocketAddr
*/

/** Creates a socket-address for the given family.
    @param Family If family == osl_Socket_FamilyInet the address is
                  set to INADDR_ANY port 0.
    @return 0 if address could not be created.
*/
SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createEmptySocketAddr(
        oslAddrFamily Family);


/** Creates a new SocketAddress and fills it from Addr.
*/
SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_copySocketAddr(
        oslSocketAddr Addr);

/** Compares the values of two SocketAddresses.
    @return <code>sal_True</code> if both addresses denote the same socket address,
            <code>sal_False</code> otherwise.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isEqualSocketAddr(
    oslSocketAddr Addr1, oslSocketAddr Addr2);

/** Uses the systems name-service interface to find an address for strHostname.
    @param[in] strHostname The name for which you search for an address.
    @return The desired address if one could be found, otherwise 0.
    Don't forget to destroy the address if you don't need it any longer.
*/
SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_resolveHostname(
        rtl_uString *strHostname);

/** Create an internet address usable for sending broadcast datagrams.
    To limit the broadcast to your subnet, pass your hosts IP address
    in dotted decimal notation as first argument.
    @see    osl_sendToSocket()
    @see    oslSocketAddr
    @param[in]  strDottedAddr dotted decimal internet address, may be 0.
    @param[in]  Port port number in host byte order.
    @return 0 if address could not be created.
*/
SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createInetBroadcastAddr (
    rtl_uString *strDottedAddr, sal_Int32 Port);


/** Create an internet-address, consisting of hostaddress and port.
    We interpret strDottedAddr as a dotted-decimal inet-addr
    (e.g. "141.99.128.50").
    @param strDottedAddr [in] String with dotted address.
    @param Port [in] portnumber in host byte order.
    @return 0 if address could not be created.
*/
SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createInetSocketAddr (
    rtl_uString *strDottedAddr, sal_Int32 Port);


/** Frees all resources allocated by Addr. The handle Addr must not
    be used after the call anymore.
*/
SAL_DLLPUBLIC void SAL_CALL osl_destroySocketAddr(
        oslSocketAddr Addr);

/** Looks up the port-number designated to the specified service/protocol-pair.
    (e.g. "ftp" "tcp").
    @return OSL_INVALID_PORT if no appropriate entry was found, otherwise the port-number.
*/
SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getServicePort(
        rtl_uString *strServicename, rtl_uString *strProtocol);



/** Retrieves the address-family from the Addr.
    @return the family of the socket-address.
    In case of an unknown family you get <code>osl_Socket_FamilyInvalid</code>.
*/
SAL_DLLPUBLIC oslAddrFamily SAL_CALL osl_getFamilyOfSocketAddr(
        oslSocketAddr Addr);


/** Retrieves the internet port-number of Addr.
    @return the port-number of the address in host-byte order. If Addr
    is not an address of type <code>osl_Socket_FamilyInet</code>, it returns <code>OSL_INVALID_PORT</code>
*/
SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getInetPortOfSocketAddr(
        oslSocketAddr Addr);


/** Sets the Port of Addr.
    @param[in] Addr the SocketAddr to perfom the operation on.
    @param[in] Port is expected in host byte-order.
    @return <code>sal_False</code> if Addr is not an inet-addr.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setInetPortOfSocketAddr(
        oslSocketAddr Addr, sal_Int32 Port);


/** Returns the hostname represented by Addr.
    @param[in] Addr The socket address from which to extract the hostname.
    @param[out] strHostname The hostname represented by the address. If
    there is no hostname to be found, it returns 0.
*/
SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getHostnameOfSocketAddr(
        oslSocketAddr Addr, rtl_uString **strHostname);


/** Gets the address in dotted decimal format.
    @param[in] Addr The socket address from which to extract the dotted decimal address.
    @param[out] strDottedInetAddr Contains the dotted decimal address
    (e.g. 141.99.20.34) represented by the address.
    If the address is invalid or not of type <code>osl_Socket_FamilyInet</code>,
    it returns 0.
    @return <code>osl_Socket_Ok</code> or <code>osl_Socket_Error</code>
*/
SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getDottedInetAddrOfSocketAddr(
        oslSocketAddr Addr, rtl_uString **strDottedInetAddr);

/** Sets the addr field in the struct sockaddr with pByteSeq. pByteSeq must be in network byte order.
 */
SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_setAddrOfSocketAddr(
        oslSocketAddr Addr, sal_Sequence *pByteSeq );

/** Returns the addr field in the struct sockaddr.
    @param[in] Addr The socket address from which to extract the ipaddress.
    @param[out] ppByteSeq After the call, *ppByteSeq contains the ipaddress
                     in network byteorder. *ppByteSeq may be 0 in case of an invalid socket handle.
    @return <code>osl_Socket_Ok</code> or <code>osl_Socket_Error</code>
 */
SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getAddrOfSocketAddr(
        oslSocketAddr Addr, sal_Sequence **ppByteSeq );

/*
    Opaque datatype HostAddr.
*/
typedef struct oslHostAddrImpl * oslHostAddr;


/** Create an oslHostAddr from given hostname and socket address.
    @param[in] strHostname The hostname to be stored.
    @param[in] Addr The socket address to be stored.
    @return The created address or 0 upon failure.
*/
SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddr(
        rtl_uString *strHostname, const oslSocketAddr Addr);


/** Create an oslHostAddr by resolving the given strHostname.
    Successful name resolution should result in the fully qualified
    domain name (FQDN) and its address as hostname and socket address
    members of the resulting oslHostAddr.
    @param[in] strHostname The hostname to be resolved.
    @return The resulting address or 0 upon failure.
*/
SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddrByName(rtl_uString *strHostname);


/** Create an oslHostAddr by reverse resolution of the given Addr.
    Successful name resolution should result in the fully qualified
    domain name (FQDN) and its address as hostname and socket address
    members of the resulting oslHostAddr.
    @param[in] Addr The socket address to be reverse resolved.
    @return The resulting address or 0 upon failure.
*/
SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddrByAddr(const oslSocketAddr Addr);


/** Create a copy of the given Addr.
    @return The copied address or 0 upon failure.
*/
SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_copyHostAddr(const oslHostAddr Addr);


/** Frees all resources allocated by Addr. The handle Addr must not
    be used after the call anymore.
*/
SAL_DLLPUBLIC void SAL_CALL osl_destroyHostAddr(oslHostAddr Addr);


/** Get the hostname member of Addr.
    @return The hostname or 0 upon failure.
*/
SAL_DLLPUBLIC void SAL_CALL osl_getHostnameOfHostAddr(const oslHostAddr Addr, rtl_uString **strHostname);


/** Get the socket address member of Addr.
    @return The socket address or 0 upon failure.
*/
SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getSocketAddrOfHostAddr(const oslHostAddr Addr);

/** Retrieve this machines hostname.
    May not always be a fully qualified domain name (FQDN).
    @param  strLocalHostname out-parameter. The string that receives the local host name.
    @return <code>sal_True</code> upon success, <code>sal_False</code> otherwise.
*/
SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getLocalHostname(rtl_uString **strLocalHostname);


/**@} end section oslHostAddr
*/

/**@{ begin section oslSocket
*/


/*-***************************************************************************/
/* oslSocket */
/*-***************************************************************************/

typedef struct oslSocketImpl * oslSocket;

/** increases the refcount of the socket handle by one
 */
SAL_DLLPUBLIC void SAL_CALL osl_acquireSocket( oslSocket Socket );

/** decreases the refcount of the socket handle by one.

    If the refcount drops to zero, the underlying socket handle
    is destroyed and becomes invalid.
 */
SAL_DLLPUBLIC void SAL_CALL osl_releaseSocket( oslSocket Socket );

/** Create a socket of the specified Family and Type. The semantic of
    the Protocol parameter depends on the given family and type.
    @return 0 if socket could not be created, otherwise you get a handle
    to the allocated socket-datastructure.
*/
SAL_DLLPUBLIC oslSocket SAL_CALL osl_createSocket(
                                    oslAddrFamily   Family,
                                    oslSocketType   Type,
                                    oslProtocol     Protocol);

/** Retrieves the Address of the local end of the socket.
    Note that a socket must be bound or connected before
    a vaild address can be returned.
    @return 0 if socket-address could not be created, otherwise you get
    the created Socket-Address.
*/
SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getLocalAddrOfSocket(oslSocket Socket);

/** Retrieves the Address of the remote end of the socket.
    Note that a socket must be connected before
    a vaild address can be returned.
    @return 0 if socket-address could not be created, otherwise you get
    the created Socket-Address.
*/
SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getPeerAddrOfSocket(oslSocket Socket);

/** Binds the given address to the socket.
    @param[in] Socket
    @param[in] Addr
    @return <code>sal_False</code> if the bind failed, <code> sal_True</code> if successful.
    @see osl_getLastSocketError()
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_bindAddrToSocket(
                                       oslSocket Socket,
                                       oslSocketAddr Addr);

/** Connects the socket to the given address.

    @param[in] Socket a bound socket.
    @param[in] Addr the peer address.
    @param pTimeout Timeout value or NULL for blocking.

    @return <code>osl_Socket_Ok</code> on successful connection,
            <code>osl_Socket_TimedOut</code> if operation timed out,
            <code>osl_Socket_Interrupted</code> if operation was interrupted
            <code>osl_Socket_Error</code> if the connection failed.
*/
SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_connectSocketTo(
                                        oslSocket Socket,
                                        oslSocketAddr Addr,
                                        const TimeValue* pTimeout);


/** Prepares the socket to act as an acceptor of incoming connections.
    You should call "listen" before you use "accept".
    @param[in] Socket The socket to listen on.
    @param[in] MaxPendingConnections denotes the length of the queue of
    pending connections for this socket. If MaxPendingConnections is
    -1, the systems default value will be used (Usually 5).
    @return <code>sal_False</code> if the listen failed.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_listenOnSocket(
                           oslSocket Socket,
                           sal_Int32 MaxPendingConnections);


/** Waits for an ingoing connection on the socket.
    This call blocks if there is no incoming connection present.
    @param[in] Socket The socket to accept the connection on.
    @param[in] pAddr if pAddr is != 0, the peers address is returned.
    @return 0 if the accept-call failed, otherwise you get a socket
    representing the new connection.
*/
SAL_DLLPUBLIC oslSocket SAL_CALL osl_acceptConnectionOnSocket
                                       (oslSocket Socket,
                                       oslSocketAddr* pAddr);

/** Tries to receive BytesToRead data from the connected socket,
    if no error occurs. Note that incomplete recvs due to
    packet boundaries may occur.

    @param[in] Socket A connected socket to be used to listen on.
    @param[out] pBuffer Points to a buffer that will be filled with the received
    data.
    @param[in] BytesToRead The number of bytes to read. pBuffer must have at least
    this size.
    @param[in] Flag Modifier for the call. Valid values are:
    <ul>
    <li><code>osl_Socket_MsgNormal</code>
    <li><code>osl_Socket_MsgOOB</code>
    <li><code>osl_Socket_MsgPeek</code>
    <li><code>osl_Socket_MsgDontRoute</code>
    <li><code>osl_Socket_MsgMaxIOVLen</code>
    </ul>

    @return the number of received bytes.
*/
SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_receiveSocket(
                          oslSocket Socket,
                          void* pBuffer,
                           sal_uInt32 BytesToRead,
                          oslSocketMsgFlag Flag);

/** Tries to receives BufferSize data from the (usually unconnected)
    (datagram-)socket, if no error occurs.

    @param[in] Socket A bound socket to be used to listen for a datagram.
    @param[out] SenderAddr A pointer to a created oslSocketAddr handle
    or to a null handle. After the call, it will contain the constructed
    oslSocketAddr of the datagrams sender. If pSenderAddr itself is 0,
    it is ignored.
    @param[out] pBuffer Points to a buffer that will be filled with the received
    datagram.
    @param[in] BufferSize The size of pBuffer.
    @param[in] Flag Modifier for the call. Valid values are:
    <ul>
    <li><code>osl_Socket_MsgNormal</code>
    <li><code>osl_Socket_MsgOOB</code>
    <li><code>osl_Socket_MsgPeek</code>
    <li><code>osl_Socket_MsgDontRoute</code>
    <li><code>osl_Socket_MsgMaxIOVLen</code>
    </ul>

    @return the number of received bytes.
*/
SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_receiveFromSocket(
                              oslSocket Socket,
                              oslSocketAddr SenderAddr,
                              void* pBuffer,
                              sal_uInt32 BufferSize,
                              oslSocketMsgFlag Flag);

/** Tries to send BytesToSend data from the connected socket,
    if no error occurs.

    @param[in] Socket A connected socket.
    @param[in] pBuffer Points to a buffer that contains the send-data.
    @param[in] BytesToSend The number of bytes to send. pBuffer must have at least
    this size.
    @param[in] Flag Modifier for the call. Valid values are:
    <ul>
    <li><code>osl_Socket_MsgNormal</code>
    <li><code>osl_Socket_MsgOOB</code>
    <li><code>osl_Socket_MsgPeek</code>
    <li><code>osl_Socket_MsgDontRoute</code>
    <li><code>osl_Socket_MsgMaxIOVLen</code>
    </ul>

    @return the number of transferred bytes.
*/
SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendSocket(
                       oslSocket Socket,
                       const void* pBuffer,
                        sal_uInt32 BytesToSend,
                       oslSocketMsgFlag Flag);

/** Tries to send one datagram with BytesToSend data to the given ReceiverAddr
    via the (implicitly unconnected) datagram-socket.
    Since there is only sent one packet, the function sends the data always complete
    even with incomplete packet boundaries.

    @param[in] Socket A bound or unbound socket. Socket will be bound
    after a successful call.

    @param[in] ReceiverAddr An initialized oslSocketAddress that contains
    the destination address for this send.

    @param[in] pBuffer Points to a buffer that contains the send-data.
    @param[in] BytesToSend The number of bytes to send. pBuffer must have at least
    this size.
    @param Flag [in] Modifier for the call. Valid values are:
    <ul>
    <li><code>osl_Socket_MsgNormal</code>
    <li><code>osl_Socket_MsgOOB</code>
    <li><code>osl_Socket_MsgPeek</code>
    <li><code>osl_Socket_MsgDontRoute</code>
    <li><code>osl_Socket_MsgMaxIOVLen</code>
    </ul>

    @return the number of transferred bytes.
*/
SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendToSocket(
                         oslSocket Socket,
                         oslSocketAddr ReceiverAddr,
                          const void* pBuffer,
                         sal_uInt32 BytesToSend,
                         oslSocketMsgFlag Flag);

/** Checks if read operations will block.

    You can specify a timeout-value in seconds/microseconds that denotes
    how long the operation will block if the Socket is not ready.

    @return <code>sal_True</code> if read operations (recv, recvFrom, accept) on the Socket
    will NOT block; <code>sal_False</code> if it would block or if an error occurred.

    @param Socket the Socket to perfom the operation on.
    @param pTimeout if NULL, the operation will block without a timeout.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isReceiveReady(
        oslSocket Socket, const TimeValue* pTimeout);

/** Checks if send operations will block.
    You can specify a timeout-value in seconds/microseconds that denotes
    how long the operation will block if the Socket is not ready.
    @return <code>sal_True</code> if send operations (send, sendTo) on the Socket
    will NOT block; <code>sal_False</code> if it would block or if an error occurred.

    @param Socket the Socket to perfom the operation on.
    @param pTimeout if NULL, the operation will block without a timeout. Otherwise
    the time define by timeout value.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isSendReady(
        oslSocket Socket, const TimeValue* pTimeout);

/** Checks if a request for out-of-band data will block.
    You can specify a timeout-value in seconds/microseconds that denotes
    how long the operation will block if the Socket has no pending OOB data.
    @return <code>sal_True</code> if OOB-request operations (recv with appropriate flags)
    on the Socket will NOT block; <code>sal_False</code> if it would block or if an error occurred.

    @param Socket the Socket to perfom the operation on.
    @param pTimeout if NULL, the operation will block without a timeout.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isExceptionPending(
        oslSocket Socket, const TimeValue* pTimeout);

/** Shuts down communication on a connected socket.
    @param[in] Socket the Socket to perfom the operation on.
    @param[in] Direction denotes which end of the socket
    should be closed:
    <ul>
    <li> <code>osl_Socket_DirRead</code>    closes read operations.
    <li> <code>osl_Socket_DirReadWrite</code> closes write operations.
    <li> <code>osl_Socket_DirWrite</code> closes read and write operations.
    </ul>
    @return <code>sal_True</code> if the socket could be closed down.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_shutdownSocket(oslSocket Socket,
                           oslSocketDirection Direction);

/** Retrieves attributes associated with the socket.
    @param Socket is the socket to query.

    @param Level selects the level for which an option should be queried.
    Valid values are:
    <ul>
    <li> osl_sol_socket:    Socket Level
    <li> osl_sol_tcp:       Level of Transmission Control Protocol
    </ul>

    @param Option denotes the option to query.
    Valid values (depending on the Level) are:
    <ul>
    <li> <code>osl_Socket_Option_Debug</code><br>
    (sal_Bool) Socket debug flag 1 = enabled, 0 = disabled.

    <li> <code>osl_Socket_OptionAcceptConn</code><br>
    <li> <code>osl_Socket_OptionReuseAddr</code><br>
    (sal_Bool) Allows the socket to be bound to an address that is
    already in use.
    1 = multiple bound allowed, 0 = no multiple bounds allowed

    <li><code>osl_Socket_OptionKeepAlive</code><br>
    (sal_Bool) Keepalive packets are sent by the underlying socket.
    1 = enabled, 0 = disabled

    <li><code>osl_Socket_OptionDontRoute</code><br>
    (sal_Bool) Do not route: send directly to interface.
    1 = do not route , 0 = routing possible

    <li><code>osl_Socket_OptionBroadcast</code><br>
    (sal_Bool) Transmission of broadcast messages are allowed on the socket.
    1 = transmission allowed, 0 = transmission disallowed

    <li><code>osl_Socket_OptionUseLoopback</code><br>

    <li><code>osl_Socket_OptionLinger</code><br>
    (sal_Int32) Linger on close if unsent data is present.
    0 = linger is off, > 0  = timeout in seconds.

    <li><code>osl_Socket_OptionOOBinLine</code><br>


    <li><code>osl_Socket_OptionSndBuf</code><br>
    (sal_Int32) Size of the send buffer in bytes. Data is sent after
    SndTimeo or when the buffer is full. This allows faster writing
    to the socket.

    <li><code>osl_Socket_OptionRcvBuf</code><br>
    (sal_Int32) Size of the receive buffer in bytes. Data is sent after
    SndTimeo or when the buffer is full. This allows faster writing
    to the socket and larger packet sizes.

    <li><code>osl_Socket_OptionSndLowat</code><br>

    <li><code>osl_Socket_OptionRcvLowat</code><br>

    <li><code>osl_Socket_OptionSndTimeo</code><br>
    (sal_Int32) Data is sent after this timeout. This allows gathering
    of data to send larger packages but increases latency times.

    <li><code>osl_Socket_OptionRcvTimeo</code><br>

    <li><code>osl_Socket_OptionError</code><br>
    <li><code>osl_Socket_OptionType</code><br>

    <li><code>osl_Socket_OptionTcpNoDelay</code><br>
    Disables the Nagle algorithm for send coalescing. (Do not
    collect data until a packet is full, instead send immediately.
    This increases network traffic but might improve latency-times.)
    1 = disables the algorithm, 0 = keeps it enabled.
    </ul>
    If not above mentioned otherwise, the options are only valid for
    level <code>osl_Socket_LevelSocket</code>.

    @param pBuffer Pointer to a buffer large enough to take the desired
    attribute-value.

    @param BufferLen contains the length of the Buffer.

    @return -1 if an error occurred or else the size of the data copied into
    pBuffer.
    @see osl_setSocketOption()
*/
SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getSocketOption( oslSocket Socket,
                               oslSocketOptionLevel Level,
                            oslSocketOption      Option,
                            void*                pBuffer,
                            sal_uInt32               BufferLen);

/** Sets the sockets attributes.

    @param Socket is the socket to modify.

    @param Level selects the level for which an option should be changed.
    Valid values are:
    <ul>
    <li> osl_sol_socket:    Socket Level
    <li> osl_sol_tcp:       Level of Transmission Control Protocol
    </ul>

    @param Option denotes the option to modify. See osl_setSocketOption() for more
    details.

    @param pBuffer Pointer to a Buffer which contains the attribute-value.

    @param BufferLen contains the length of the Buffer.

    @return True if the option could be changed.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setSocketOption( oslSocket Socket,
                            oslSocketOptionLevel    Level,
                            oslSocketOption         Option,
                            void*                   pBuffer,
                            sal_uInt32              BufferLen);

/** Enables/disables non-blocking-mode of the socket.
    @param Socket Change mode for this socket.
    @param On <code>sal_True</code> enables non-blocking mode,
              <code>sal_False</code> disables non-blocking mode.
    @return <code>sal_True</code> if mode could be changed.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_enableNonBlockingMode(
        oslSocket Socket, sal_Bool On);


/** Query state of non-blocking-mode of the socket.
    @param Socket Query mode for this socket.
    @return True if non-blocking-mode is enabled.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isNonBlockingMode(
        oslSocket Socket);


/** Queries the socket for its type.
    @param[in] Socket The socket to query.
    @return one of:
    <ul>
    <li> osl_Socket_TypeStream
    <li> osl_Socket_TypeDgram
    <li> osl_Socket_TypeRaw
    <li> osl_Socket_TypeRdm
    <li> osl_Socket_TypeSeqPacket
    <li> osl_invalid_SocketType, if an error occurred
    </ul>
*/
SAL_DLLPUBLIC oslSocketType SAL_CALL osl_getSocketType(
        oslSocket Socket);

/** returns  a string which describes the last socket error.
    @param[in] Socket The socket to query.
    @param[out] strError The string that receives the error message.
*/
SAL_DLLPUBLIC void SAL_CALL osl_getLastSocketErrorDescription(
        oslSocket Socket, rtl_uString **strError);

/** returns a constant decribing the last error for the socket system.
    @return <code>osl_Socket_E_NONE</code> if no error occurred,
            <code>osl_invalid_SocketError</code> if an unknown (unmapped)
            error occurred, otherwise an enum describing the    error.
*/
SAL_DLLPUBLIC oslSocketError SAL_CALL osl_getLastSocketError(
        oslSocket Socket);

/** Type for the representation of socket sets.
*/
typedef struct oslSocketSetImpl * oslSocketSet;

/** Creates a set of sockets to be used with osl_demultiplexSocketEvents().
    @return A oslSocketSet or 0 if creation failed.
*/
SAL_DLLPUBLIC oslSocketSet SAL_CALL osl_createSocketSet(void);

/** Destroys a oslSocketSet.
*/
SAL_DLLPUBLIC void SAL_CALL osl_destroySocketSet(oslSocketSet Set);

/** Clears the set from all previously added sockets.
    @param Set the set to be cleared.
*/
SAL_DLLPUBLIC void SAL_CALL osl_clearSocketSet(oslSocketSet Set);


/** Adds a socket to the set.
    @param Set the set were the socket is added.
    @param Socket the socket to be added.
*/
SAL_DLLPUBLIC void SAL_CALL osl_addToSocketSet(oslSocketSet Set, oslSocket Socket);

/** Removes a socket from the set.
    @param Set the set were the socket is removed from.
    @param Socket the socket to be removed.
*/
SAL_DLLPUBLIC void SAL_CALL osl_removeFromSocketSet(oslSocketSet Set, oslSocket Socket);

/** Checks if socket is in the set.
    @param Set the set to be checked.
    @param Socket check if this socket is in the set.
    @return <code>sal_True</code> if socket is in the set.
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isInSocketSet(oslSocketSet Set, oslSocket Socket);

/** Checks multiple sockets for events.
    @param IncomingSet Checks the sockets in this set
    for incoming events (read, accept). If the set is 0,
    it is just skipped.
    @param OutgoingSet Checks the sockets in this set
    for outgoing events (write, connect). If the set is 0,
    it is just skipped.
    @param OutOfBandSet Checks the sockets in this set
    for out-of-band events. If the set is 0, it is just skipped.
    @param pTimeout Address of the number of milliseconds to wait for events. If
    *pTimeout is -1, the call will block until an event or an error
    occurs.
    @return -1 on errors, otherwise the number of sockets with
    pending events. In case of timeout, the number might be 0.
*/
SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_demultiplexSocketEvents(oslSocketSet IncomingSet,
                                    oslSocketSet OutgoingSet,
                                    oslSocketSet OutOfBandSet,
                                    const TimeValue* pTimeout);

/** Closes the socket terminating any ongoing dataflow.
    @param[in] Socket The socket to close.
 */
SAL_DLLPUBLIC void SAL_CALL osl_closeSocket(oslSocket Socket);


/** Retrieves n bytes from the stream and copies them into pBuffer.
    The function avoids incomplete reads due to packet boundaries.
    @param[in] Socket The socket to read from.
    @param[out] pBuffer receives the read data.
    @param[out] nSize the number of bytes to read. pBuffer must be large enough
    to hold the n bytes!
    @return the number of read bytes. The number will only be smaller than
    n if an exceptional condition (e.g. connection closed) occurs.
*/
SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_readSocket( oslSocket Socket, void *pBuffer, sal_Int32 nSize );


/** Writes n bytes from pBuffer to the stream. The method avoids
    incomplete writes due to packet boundaries.
    @param[out] Socket The socket to write to.
    @param[in] pBuffer contains the data to be written.
    @param[in] nSize the number of bytes to write.
    @return the number of written bytes. The number will only be smaller than
    nSize if an exceptional condition (e.g. connection closed) occurs.
*/
SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_writeSocket( oslSocket Socket, const void *pBuffer, sal_Int32 nSize );

/**@} end section oslSocket
*/



#ifdef __cplusplus
}
#endif

#endif // INCLUDED_OSL_SOCKET_H

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */