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