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