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