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