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