summaryrefslogtreecommitdiffstats
path: root/include/osl/socket.h
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 05:54:39 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 05:54:39 +0000
commit267c6f2ac71f92999e969232431ba04678e7437e (patch)
tree358c9467650e1d0a1d7227a21dac2e3d08b622b2 /include/osl/socket.h
parentInitial commit. (diff)
downloadlibreoffice-267c6f2ac71f92999e969232431ba04678e7437e.tar.xz
libreoffice-267c6f2ac71f92999e969232431ba04678e7437e.zip
Adding upstream version 4:24.2.0.upstream/4%24.2.0
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'include/osl/socket.h')
-rw-r--r--include/osl/socket.h863
1 files changed, 863 insertions, 0 deletions
diff --git a/include/osl/socket.h b/include/osl/socket.h
new file mode 100644
index 0000000000..474860b147
--- /dev/null
+++ b/include/osl/socket.h
@@ -0,0 +1,863 @@
+/* -*- 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 .
+ */
+
+/*
+ * This file is part of LibreOffice published API.
+ */
+
+#ifndef INCLUDED_OSL_SOCKET_H
+#define INCLUDED_OSL_SOCKET_H
+
+#include "rtl/ustring.h"
+#include "osl/time.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* error returns */
+#define OSL_INADDR_NONE 0xffffffff
+#define OSL_INVALID_PORT (-1)
+
+/**@{ begin section types
+*/
+
+/**
+ Opaque datatype SocketAddr.
+*/
+typedef struct oslSocketAddrImpl * oslSocketAddr;
+
+/**
+ Represents the address-family of a socket
+*/
+typedef enum {
+ osl_Socket_FamilyInet, /*!< IP (AF_INET) */
+ osl_Socket_FamilyIpx, /*!< Novell IPX/SPX (AF_IPX) */
+ osl_Socket_FamilyInvalid, /*!< always last entry in enum! */
+ osl_Socket_Family_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
+} oslAddrFamily;
+
+/**
+ represent a specific protocol within an 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, /*!< always last entry in enum */
+ osl_Socket_Protocol_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
+} oslProtocol;
+
+/**
+ Represents the type of a socket
+*/
+typedef enum {
+ osl_Socket_TypeStream, /*!< stream socket */
+ osl_Socket_TypeDgram, /*!< datagram socket */
+ osl_Socket_TypeRaw, /*!< raw socket */
+ osl_Socket_TypeRdm, /*!< connectionless, message-oriented,
+ reliably delivered message (RDM)
+ sockets */
+ osl_Socket_TypeSeqPacket, /*!< connection-oriented and reliable
+ two-way transport of ordered byte
+ streams */
+ 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, /*!< record debugging info */
+ osl_Socket_OptionAcceptConn, /*!< listen for connection */
+ osl_Socket_OptionReuseAddr, /*!< bind to address already in use */
+ osl_Socket_OptionKeepAlive, /*!< use keep-alive */
+ osl_Socket_OptionDontRoute, /*!< do not route packet, send direct to
+ interface addresses */
+ osl_Socket_OptionBroadcast, /*!< send broadcast message */
+ osl_Socket_OptionUseLoopback, /*!< socket receives copy of everything
+ sent on the socket */
+ osl_Socket_OptionLinger, /*!< don't immediately close - "linger"
+ a while to allow for graceful
+ connection closure */
+ osl_Socket_OptionOOBinLine, /*!< out-of-band (OOB) data placed in
+ normal input queue (i.e. OOB inline) */
+ osl_Socket_OptionSndBuf, /*!< send buffer */
+ osl_Socket_OptionRcvBuf, /*!< receive buffer */
+ osl_Socket_OptionSndLowat, /*!< send "low-water" mark - amount of
+ available space in send buffer for
+ select() to return "writable" */
+ osl_Socket_OptionRcvLowat, /*!< receive "low-water" mark - amount of
+ available space in receive buffer
+ for select() to receive "readable" */
+ osl_Socket_OptionSndTimeo, /*!< send timeout */
+ osl_Socket_OptionRcvTimeo, /*!< receive timeout */
+ osl_Socket_OptionError, /*!< socket error */
+ osl_Socket_OptionType, /*!< returns socket type (e.g. datagram,
+ stream). */
+ osl_Socket_OptionTcpNoDelay, /*!< disable TCP Nagle algorithm */
+ 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 oslSocket
+*/
+
+typedef struct oslSocketImpl * oslSocket;
+
+/** Create a socket of the specified Family and Type. The semantic of
+ the Protocol parameter depends on the given family and type.
+
+ @returns 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);
+
+/** 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);
+
+/** Retrieves the Address of the local end of the socket.
+ Note that a socket must be bound or connected before
+ a valid address can be returned.
+
+ @returns 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 valid address can be returned.
+ @retval 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
+ @retval sal_False if the bind failed
+ @retval sal_True if bind is 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.
+
+ @retval osl_Socket_Ok on successful connection,
+ @retval osl_Socket_TimedOut if operation timed out,
+ @retval osl_Socket_Interrupted if operation was interrupted
+ @retval osl_Socket_Error 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).
+ @retval sal_False 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.
+ @retval 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:
+ osl_Socket_MsgNormal
+ osl_Socket_MsgOOB
+ osl_Socket_MsgPeek
+ osl_Socket_MsgDontRoute
+ osl_Socket_MsgMaxIOVLen
+
+ @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:
+ osl_Socket_MsgNormal
+ osl_Socket_MsgOOB
+ osl_Socket_MsgPeek
+ osl_Socket_MsgDontRoute
+ osl_Socket_MsgMaxIOVLen
+
+ @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:
+ @li osl_Socket_MsgNormal
+ @li osl_Socket_MsgOOB
+ @li osl_Socket_MsgPeek
+ @li osl_Socket_MsgDontRoute
+ @li osl_Socket_MsgMaxIOVLen
+
+ @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[in] Flag
+ @parblock
+ Modifier for the call. Valid values are:
+ @li osl_Socket_MsgNormal
+ @li osl_Socket_MsgOOB
+ @li osl_Socket_MsgPeek
+ @li osl_Socket_MsgDontRoute
+ @li osl_Socket_MsgMaxIOVLen
+ @endparblock
+
+ @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.
+
+ @param Socket the Socket to perform the operation on.
+ @param pTimeout if NULL, the operation will block without a timeout.
+
+ @retval sal_True if read operations (recv, recvFrom, accept) on the Socket
+ will NOT block;
+ @retval sal_False if it would block or if an error occurred.
+*/
+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.
+
+ @param Socket the Socket to perform the operation on.
+ @param pTimeout if NULL, the operation will block without a timeout. Otherwise
+ the time define by timeout value.
+
+ @retval sal_True if send operations (send, sendTo) on the Socket
+ will NOT block
+ @retval sal_False if it would block or if an error occurred.
+*/
+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.
+
+ @param Socket the Socket to perform the operation on.
+ @param pTimeout if NULL, the operation will block without a timeout.
+
+ @retval sal_True if OOB-request operations (recv with appropriate flags)
+ on the Socket will NOT block
+ @retval sal_False if it would block or if an error occurred.
+*/
+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 perform the operation on.
+ @param[in] Direction
+ @parblock
+ Direction denotes which end of the socket should be closed:
+ @li osl_Socket_DirRead - closes read operations.
+ @li osl_Socket_DirReadWrite - closes write operations.
+ @li osl_Socket_DirWrite - closes read and write operations.
+ @endparblock
+
+ @retval sal_True 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
+ @parblock
+ Selects the level for which an option should be queried.
+ Valid values are:
+ @li osl_sol_socket - Socket Level
+ @li osl_sol_tcp - Level of Transmission Control Protocol
+ @endparblock
+
+ @param Option
+ @parblock
+ Denotes the option to query. Valid values (depending on the Level) are:
+ @li osl_Socket_Option_Debug - (sal_Bool) Socket debug flag 1 = enabled, 0 = disabled.
+ @li osl_Socket_OptionAcceptConn
+ @li osl_Socket_OptionReuseAddr - (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 osl_Socket_OptionKeepAlive (sal_Bool) Keepalive packets are sent by the underlying socket.
+ 1 = enabled, 0 = disabled
+ @li osl_Socket_OptionDontRoute - (sal_Bool) Do not route: send directly to interface.
+ 1 = do not route , 0 = routing possible
+ @li osl_Socket_OptionBroadcast - (sal_Bool) Transmission of broadcast messages are allowed on the socket.
+ 1 = transmission allowed, 0 = transmission disallowed
+ @li osl_Socket_OptionUseLoopback
+ @li osl_Socket_OptionLinger (sal_Int32) Linger on close if unsent data is present.
+ 0 = linger is off, > 0 = timeout in seconds.
+ @li osl_Socket_OptionOOBinLine
+ @li osl_Socket_OptionSndBuf (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 osl_Socket_OptionRcvBuf (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 osl_Socket_OptionSndLowat
+ @li osl_Socket_OptionRcvLowat
+ @li osl_Socket_OptionSndTimeo (sal_Int32) Data is sent after this timeout. This allows gathering
+ of data to send larger packages but increases latency times.
+ @li osl_Socket_OptionRcvTimeo
+ @li osl_Socket_OptionError
+ @li osl_Socket_OptionType
+ @li osl_Socket_OptionTcpNoDelay 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.
+
+ If not above mentioned otherwise, the options are only valid for level osl_Socket_LevelSocket.
+ @endparblock
+ @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
+ @parblock
+ selects the level for which an option should be changed.
+ Valid values are:
+ @li osl_sol_socket - Socket Level
+ @li osl_sol_tcp - Level of Transmission Control Protocol
+ @endparblock
+ @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.
+
+ @retval 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 sal_True enables non-blocking mode, sal_False disables non-blocking mode.
+
+ @retval sal_True 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.
+
+ @retval 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.
+
+ @retval osl_Socket_TypeStream
+ @retval osl_Socket_TypeDgram
+ @retval osl_Socket_TypeRaw
+ @retval osl_Socket_TypeRdm
+ @retval osl_Socket_TypeSeqPacket
+ @retval osl_invalid_SocketType if an error occurred
+*/
+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 describing the last error for the socket system.
+
+ @retval osl_Socket_E_NONE if no error occurred
+ @retval osl_invalid_SocketError if an unknown (unmapped)
+ error occurred, otherwise an enum describing the error.
+*/
+SAL_DLLPUBLIC oslSocketError SAL_CALL osl_getLastSocketError(
+ oslSocket Socket);
+
+/** 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
+*/
+/**@{ 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.
+ @retval sal_True if both addresses denote the same socket address.
+ @retval sal_False if both addresses do not denote the same socket address.
+*/
+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.
+ @retval 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 host address and port.
+ We interpret strDottedAddr as a dotted-decimal inet-addr
+ (e.g. "141.99.128.50").
+ @param[in] strDottedAddr String with dotted address.
+ @param[in] Port portnumber in host byte order.
+ @retval 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").
+ @retval 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 osl_Socket_FamilyInvalid.
+*/
+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 osl_Socket_FamilyInet, it returns OSL_INVALID_PORT
+*/
+SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getInetPortOfSocketAddr(
+ oslSocketAddr Addr);
+
+
+/** Sets the Port of Addr.
+ @param[in] Addr the SocketAddr to perform the operation on.
+ @param[in] Port is expected in host byte-order.
+ @retval sal_False 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.
+
+ @retval If the address is invalid or not of type osl_Socket_FamilyInet, it returns 0.
+ @retval osl_Socket_Ok
+ @retval osl_Socket_Error
+*/
+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 byte order. *ppByteSeq may be 0 in case of an invalid socket handle.
+ @retval osl_Socket_Ok
+ @retval osl_Socket_Error
+ */
+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.
+ @param Addr address for host name
+ @param strHostname The host name 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 (NOT the FQDN)
+ @param strLocalHostname out-parameter. The string that receives the local host name.
+ @retval sal_True upon success
+ @retval sal_False
+*/
+SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getLocalHostname(rtl_uString **strLocalHostname);
+
+
+/**@} end section oslHostAddr
+*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // INCLUDED_OSL_SOCKET_H
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */