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