1/* ------------------------------------------------------------------ 2 * Copyright (C) 1998-2009 PacketVideo 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 13 * express or implied. 14 * See the License for the specific language governing permissions 15 * and limitations under the License. 16 * ------------------------------------------------------------------- 17 */ 18// -*- c++ -*- 19// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 20 21// O S C L _ S O C K E T 22 23// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 24 25/*! \addtogroup osclio OSCL IO 26 * 27 * @{ 28 */ 29 30 31/*! \file oscl_socket.h 32 \brief The file oscl_socket.h defines the OSCL Socket APIs. 33 34*/ 35#ifndef OSCL_SOCKET_H_INCLUDED 36#define OSCL_SOCKET_H_INCLUDED 37 38#ifndef OSCLCONFIG_IO_H_INCLUDED 39#include "osclconfig_io.h" 40#endif 41 42#ifndef OSCL_SOCKET_TYPES_H_INCLUDED 43#include "oscl_socket_types.h" 44#endif 45 46#ifndef OSCL_HEAPBASE_H_INCLUDED 47#include "oscl_heapbase.h" 48#endif 49 50#ifndef OSCL_DEFALLOC_H_INCLUDED 51#include "oscl_defalloc.h" 52#endif 53 54#ifndef OSCL_VECTOR_H_INCLUDED 55#include "oscl_vector.h" 56#endif 57 58#ifndef OSCL_MEM_H_INCLUDED 59#include "oscl_mem.h" 60#endif 61 62/** 63* Socket server 64*/ 65class OsclSocketServI; 66 67class OsclSocketServ : public HeapBase 68{ 69 public: 70 /** 71 * Create a socket server. 72 * May leave if failure. 73 * 74 * @param alloc: Memory allocator. 75 * @return Returns pointer to socket server 76 */ 77 OSCL_IMPORT_REF static OsclSocketServ *NewL(Oscl_DefAlloc &alloc); 78 79 /** 80 * Destructor. The server object must be deleted using 81 * the same allocator used in the NewL call. 82 */ 83 OSCL_IMPORT_REF ~OsclSocketServ(); 84 85 /** 86 * Connect to socket server. 87 * This is a synchronous method. 88 * 89 * @param Number of message slots. 90 * @return Returns OsclErrNone for success, 91 * or a platform-specific code. 92 */ 93 OSCL_IMPORT_REF int32 Connect(uint32 aMessageSlots = 8); 94 95 /** 96 * Close socket server. 97 * This is a synchronous method. 98 * @param aCleanup: cleanup the socket system? 99 * the socket cleanup should only be done when 100 * all parts of the application are done using 101 * sockets. 102 */ 103 OSCL_IMPORT_REF void Close(bool aCleanup = true); 104 105 private: 106 OsclSocketServ(Oscl_DefAlloc &alloc): iServ(NULL), iAlloc(alloc) {} 107 108 OsclSocketServI *iServ; 109 Oscl_DefAlloc &iAlloc; 110 111 friend class OsclTCPSocket; 112 friend class OsclUDPSocket; 113 friend class OsclDNS; 114 115}; 116 117 118class OsclUDPSocketI; 119 120/** 121* The UDP Socket class 122*/ 123 124class OsclUDPSocket : public HeapBase 125{ 126 public: 127 /** 128 * Create a UDP Socket. 129 * May leave if failure. 130 * 131 * @param alloc: Memory allocator. 132 * @param aServ: Socket server. Must be connected. 133 * @param aObserver: Socket observer. 134 * @param aId: Socket ID. The caller must assign an ID 135 * to each socket. The ID is used to identify the socket 136 * in observer callbacks. 137 * @return Returns pointer to socket. 138 */ 139 OSCL_IMPORT_REF static OsclUDPSocket *NewL(Oscl_DefAlloc &alloc, 140 OsclSocketServ& aServ, 141 OsclSocketObserver *aObserver, 142 uint32 aId); 143 144 /** 145 * Destructor. The object must be deleted using 146 * the same allocator used in the NewL call. 147 */ 148 OSCL_IMPORT_REF ~OsclUDPSocket(); 149 150 /** 151 * Close a UDP socket. 152 * This is a synchronous method. 153 * 154 * Once it is closed a socket cannot be re-opened. 155 * Sockets are automatically closed when they 156 * are deleted. This method may be used to see 157 * any error code returned from the platform's 158 * socket close call. 159 * @return Returns OsclErrNone for success, or a 160 * platform-specific error code. 161 */ 162 OSCL_IMPORT_REF int32 Close(); 163 164 /** 165 * Bind a UDP socket to an address. 166 * This is a synchronous method. 167 * 168 * @param aAddress: Bind address. 169 * @return Returns OsclErrNone for success, or a 170 * platform-specific error code. 171 */ 172 OSCL_IMPORT_REF int32 Bind(OsclNetworkAddress& aAddress); 173 174 /** 175 * Bind a UDP socket to an address 176 * and Join the multicast group. 177 * This is a synchronous method. 178 * 179 * @param aAddress: Bind address. 180 * @return Returns OsclErrNone for success, or a 181 * platform-specific error code. 182 * May throw an OsclErrNotSupported Exception 183 */ 184 OSCL_IMPORT_REF int32 Join(OsclNetworkAddress& aAddress); 185 186 /** 187 * Bind a UDP socket to an address. 188 * This is an asynchronous method. 189 * 190 * @param aAddress: Bind address. 191 * @param aTimeoutMsec: Optional timeout. Use a negative 192 * value for infinite wait. 193 * @return Will return EPVSocketPending if successful. 194 * When the operation is complete, a callback to the 195 * observer will occur with the completion status. 196 * If the operation cannot be initiated, the call will 197 * return EPVSocketFailure and there will be no callback. 198 */ 199 OSCL_IMPORT_REF TPVSocketEvent BindAsync(OsclNetworkAddress& aAddress 200 , int32 aTimeoutMsec = (-1)); 201 202 /** 203 * Cancel Bind 204 * 205 * This method will cancel any pending BindAsync operation 206 * on the current socket, causing the BindAsync to complete 207 * with error EPVSocketCancel. If there is no pending 208 * BindAsync operation, this method will have no effect. 209 */ 210 OSCL_IMPORT_REF void CancelBind(); 211 212 /** 213 * Retrieve the received data after a successful 214 * RecvFrom operation. 215 * This is a synchronous method. 216 * 217 * @param aLength: (output) number of bytes of data received. 218 * @return Returns pointer to received data, or NULL 219 * if none. 220 */ 221 OSCL_IMPORT_REF uint8 *GetRecvData(int32 *aLength); 222 223 /** 224 * Retrieve the sent data after a successful 225 * SendTo operation. 226 * This is a synchronous method. 227 * 228 * @param aLength: (output) number of bytes of data sent. 229 * @return Returns pointer to sent data, or NULL 230 * if none. 231 */ 232 OSCL_IMPORT_REF uint8 *GetSendData(int32 *aLength); 233 234 /** 235 * Send Data. 236 * This is an asynchronous method. 237 * 238 * @param aPtr: Data to send. 239 * @param aLen: Length of data to send. 240 * @param aAddress: Destination address. 241 * @param aTimeoutMsec: Timeout in milliseconds, or (-1) 242 * for infinite wait. 243 * @return Will return EPVSocketPending if successful. 244 * When the operation is complete, a callback to the 245 * observer will occur with the completion status. 246 * If the operation cannot be initiated, the call will 247 * return EPVSocketFailure and there will be no callback. 248 */ 249 OSCL_IMPORT_REF TPVSocketEvent SendTo(const uint8* aPtr, uint32 aLen, 250 OsclNetworkAddress& aAddress, 251 int32 aTimeoutMsec = -1); 252 /** 253 * Cancel SendTo 254 * 255 * This method will cancel any pending SendTo operation 256 * on the current socket, causing the SendTo to complete 257 * with error EPVSocketCancel. If there is no pending 258 * SendTo operation, this method will have no effect. 259 */ 260 OSCL_IMPORT_REF void CancelSendTo(); 261 262 /** 263 * Receive Data. 264 * This is an asynchronous method. 265 * 266 * @param aPtr: Buffer to receive incoming data 267 * @param aMaxLen: Length of buffer. 268 * @param aAddress: (output) Source address. 269 * @param aTimeoutMsec: Timeout in milliseconds, or (-1) 270 * for infinite wait. 271 * 272 * @param aMultiRecvLimit (optional input): Configures multiple 273 * packet receive mode. As long as there are packets queued at 274 * the socket and at least aMultiRecvLimit bytes are available 275 * in the buffer, recvfrom operations will continue. 276 * A value of zero disabled multiple packet mode. 277 * The individual packet lengths can be retrieved in the 278 * aPacketLen parameter; and the individual packet 279 * source addresses can be retrieved in the aPacketSource parameter. 280 * @param aPacketLen: (optional output) a vector of packet lengths, 281 * in case multiple packets were received. 282 * @param aPacketSource: (optional output) a vector of source addresses, 283 * in case multiple packets were received. 284 * 285 * @return Will return EPVSocketPending if successful. 286 * When the operation is complete, a callback to the 287 * observer will occur with the completion status. 288 * If the operation cannot be initiated, the call will 289 * return EPVSocketFailure and there will be no callback. 290 */ 291 OSCL_IMPORT_REF TPVSocketEvent RecvFrom(uint8* aPtr, uint32 aMaxLen, 292 OsclNetworkAddress& aAddress, 293 int32 aTimeoutMsec = -1, 294 uint32 aMultiRecvLimit = 0, 295 Oscl_Vector<uint32, OsclMemAllocator>* aPacketLen = NULL, 296 Oscl_Vector<OsclNetworkAddress, OsclMemAllocator>* aPacketSource = NULL); 297 /** 298 * Cancel RecvFrom 299 * 300 * This method will cancel any pending RecvFrom operation 301 * on the current socket, causing the RecvFrom to complete 302 * with error EPVSocketCancel. If there is no pending 303 * RecvFrom operation, this method will have no effect. 304 */ 305 OSCL_IMPORT_REF void CancelRecvFrom(); 306 307 /** 308 * Set the buffer size of the socket 309 * This is a synchronous method. 310 * @param size: buffer size 311 * @return Returns OsclErrNone for success, or a 312 * platform-specific error code. 313 * May throw an OsclErrNotSupported Exception. 314 */ 315 316 OSCL_IMPORT_REF int32 SetRecvBufferSize(uint32 size); 317 318 private: 319 OsclUDPSocket(Oscl_DefAlloc &alloc): iUDPSocket(NULL), iAlloc(alloc) {} 320 OsclUDPSocketI *iUDPSocket; 321 Oscl_DefAlloc &iAlloc; 322}; 323 324class OsclTCPSocketI; 325 326/** 327* The TCP Socket class 328*/ 329 330class OsclTCPSocket : public HeapBase 331{ 332 public: 333 /** 334 * Create a TCP Socket. 335 * May leave if failure. 336 * 337 * @param alloc: Memory allocator. 338 * @param aServ: Socket server. Must be connected. 339 * @param aObserver: Socket observer. 340 * @param aId: Socket ID. The caller must assign an ID 341 * to each socket. The ID is used to identify the socket 342 * in observer callbacks. 343 * @return Returns pointer to socket. 344 */ 345 OSCL_IMPORT_REF static OsclTCPSocket *NewL(Oscl_DefAlloc &alloc, 346 OsclSocketServ& aServ, 347 OsclSocketObserver *aObserver, 348 uint32 aId); 349 350 /** 351 * Destructor. The object must be deleted using 352 * the same allocator used in the NewL call. 353 */ 354 OSCL_IMPORT_REF ~OsclTCPSocket(); 355 356 357 /** 358 * Close a TCP socket. 359 * This is a synchronous method. 360 * 361 * Once it is closed a socket cannot be re-opened. 362 * Sockets are automatically closed when they 363 * are deleted. This method may be used to see 364 * any error code returned from the platform's 365 * socket close call. 366 * @return Returns OsclErrNone for success, or a 367 * platform-specific error code. 368 */ 369 OSCL_IMPORT_REF int32 Close(); 370 371 /** 372 * Bind a TCP socket to an address. 373 * This is a synchronous method. 374 * 375 * @param aAddress: Bind address. 376 * @return Returns OsclErrNone for success, or a 377 * platform-specific error code. 378 */ 379 OSCL_IMPORT_REF int32 Bind(OsclNetworkAddress& aAddress); 380 381 /** 382 * Bind a TCP socket to an address. 383 * This is an asynchronous method. 384 * 385 * @param aAddress: Bind address. 386 * @param aTimeoutMsec: Optional timeout. Use a negative 387 * value for infinite wait. 388 * @return Will return EPVSocketPending if successful. 389 * When the operation is complete, a callback to the 390 * observer will occur with the completion status. 391 * If the operation cannot be initiated, the call will 392 * return EPVSocketFailure and there will be no callback. 393 */ 394 OSCL_IMPORT_REF TPVSocketEvent BindAsync(OsclNetworkAddress& aAddress 395 , int32 aTimeoutMsec = (-1)); 396 397 /** 398 * Cancel Bind 399 * 400 * This method will cancel any pending BindAsync operation 401 * on the current socket, causing the BindAsync to complete 402 * with error EPVSocketCancel. If there is no pending 403 * BindAsync operation, this method will have no effect. 404 */ 405 OSCL_IMPORT_REF void CancelBind(); 406 407 /** 408 * Listen. 409 * This is a synchronous method. 410 * 411 * @param aQueueSize: Queue size. 412 * @return Returns OsclErrNone for success, or a 413 * platform-specific error code. 414 */ 415 OSCL_IMPORT_REF int32 Listen(int32 aQueueSize); 416 417 /** 418 * ListenAsync 419 * This is an asynchronous method. 420 * 421 * @param aQueueSize: Queue size. 422 * @param aTimeoutMsec: Optional timeout. Use a negative 423 * value for infinite wait. 424 * @return Will return EPVSocketPending if successful. 425 * When the operation is complete, a callback to the 426 * observer will occur with the completion status. 427 * If the operation cannot be initiated, the call will 428 * return EPVSocketFailure and there will be no callback. 429 */ 430 OSCL_IMPORT_REF TPVSocketEvent ListenAsync(int32 aQueueSize, int32 aTimeoutMsec = (-1)); 431 432 /** 433 * Cancel Async Listen 434 * 435 * This method will cancel any pending ListenAsync operation 436 * on the current socket, causing the Listen to complete 437 * with error EPVSocketCancel. If there is no pending 438 * Listen operation, this method will have no effect. 439 */ 440 OSCL_IMPORT_REF void CancelListen(); 441 442 /** 443 * Retrieve the accept socket after a successful 444 * Accept operation. 445 * This is a synchronous method. 446 * 447 * @param aId: Socket ID. The caller must assign an ID 448 * to each socket. The ID is used to identify the socket 449 * in observer callbacks. 450 * @return Returns pointer to socket, or NULL if error. 451 * Note: The caller is reponsible for deleting any accepted 452 * socket that it retrieves. 453 */ 454 OSCL_IMPORT_REF OsclTCPSocket *GetAcceptedSocketL(uint32 aId); 455 456 /** 457 * Retrieve the received data after a successful 458 * Recv operation. 459 * This is a synchronous method. 460 * 461 * @param aLength: (output) number of bytes of data received. 462 * @return Returns pointer to received data, or NULL 463 * if none. 464 */ 465 OSCL_IMPORT_REF uint8 *GetRecvData(int32 *aLength); 466 467 /** 468 * Retrieve the sent data after a successful 469 * Send operation. 470 * This is a synchronous method. 471 * 472 * @param aLength: (output) number of bytes of data sent. 473 * @return Returns pointer to sent data, or NULL 474 * if none. 475 */ 476 OSCL_IMPORT_REF uint8 *GetSendData(int32 *aLength); 477 478 /** 479 * Connect to an address. 480 * This is an asynchronous method. 481 * 482 * @param aAddress: a network address. 483 * @param aTimeoutMsec: Timeout in milliseconds, or (-1) 484 * for infinite wait. 485 * @return Will return EPVSocketPending if successful. 486 * When the operation is complete, a callback to the 487 * observer will occur with the completion status. 488 * If the operation cannot be initiated, the call will 489 * return EPVSocketFailure and there will be no callback. 490 */ 491 OSCL_IMPORT_REF TPVSocketEvent Connect(OsclNetworkAddress& aAddress, 492 int32 aTimeoutMsec = -1); 493 494 /** 495 * Cancel Connect 496 * 497 * This method will cancel any pending Connect operation 498 * on the current socket, causing the Connect to complete 499 * with error EPVSocketCancel. If there is no pending 500 * Connect operation, this method will have no effect. 501 */ 502 OSCL_IMPORT_REF void CancelConnect(); 503 504 /** 505 * Shutdown a socket. 506 * This is an asynchronous method. 507 * 508 * @param aHow: type of shutdown 509 * @param aTimeoutMsec: Timeout in milliseconds, or (-1) 510 * for infinite wait. 511 * @return Will return EPVSocketPending if successful. 512 * When the operation is complete, a callback to the 513 * observer will occur with the completion status. 514 * If the operation cannot be initiated, the call will 515 * return EPVSocketFailure and there will be no callback. 516 */ 517 OSCL_IMPORT_REF TPVSocketEvent Shutdown(TPVSocketShutdown aHow, 518 int32 aTimeoutMsec = -1); 519 520 /** 521 * Cancel Shutdown 522 * 523 * This method will cancel any pending Shutdown operation 524 * on the current socket, causing the Shutdown to complete 525 * with error EPVSocketCancel. If there is no pending 526 * Shutdown operation, this method will have no effect. 527 */ 528 OSCL_IMPORT_REF void CancelShutdown(); 529 530 /** 531 * Accept incoming connections. 532 * This is an asynchronous method. 533 * 534 * @param aTimeoutMsec: Timeout in milliseconds, or (-1) 535 * for infinite wait. 536 * @return Will return EPVSocketPending if successful. 537 * When the operation is complete, a callback to the 538 * observer will occur with the completion status. 539 * If the operation cannot be initiated, the call will 540 * return EPVSocketFailure and there will be no callback. 541 */ 542 OSCL_IMPORT_REF TPVSocketEvent Accept(int32 aTimeout = -1); 543 544 /** 545 * Cancel Accept 546 * 547 * This method will cancel any pending Accept operation 548 * on the current socket, causing the Accept to complete 549 * with error EPVSocketCancel. If there is no pending 550 * Accept operation, this method will have no effect. 551 */ 552 OSCL_IMPORT_REF void CancelAccept(); 553 554 /** 555 * Send Data. 556 * This is an asynchronous method. 557 * 558 * @param aPtr: Data to send. 559 * @param aLen: Length of data to send. 560 * @param aTimeoutMsec: Timeout in milliseconds, or (-1) 561 * for infinite wait. 562 * @return Will return EPVSocketPending if successful. 563 * When the operation is complete, a callback to the 564 * observer will occur with the completion status. 565 * If the operation cannot be initiated, the call will 566 * return EPVSocketFailure and there will be no callback. 567 */ 568 OSCL_IMPORT_REF TPVSocketEvent Send(const uint8* aPtr, uint32 aLen, 569 int32 aTimeoutMsec = -1); 570 571 /** 572 * Cancel Send 573 * 574 * This method will cancel any pending Send operation 575 * on the current socket, causing the Send to complete 576 * with error EPVSocketCancel. If there is no pending 577 * Send operation, this method will have no effect. 578 */ 579 OSCL_IMPORT_REF void CancelSend(); 580 581 /** 582 * Receive Data. 583 * This is an asynchronous method. 584 * 585 * @param aPtr: Buffer for received data. 586 * @param aMaxLen: Length of buffer. 587 * @param aTimeoutMsec: Timeout in milliseconds, or (-1) 588 * for infinite wait. 589 * @return Will return EPVSocketPending if successful. 590 * When the operation is complete, a callback to the 591 * observer will occur with the completion status. 592 * If the operation cannot be initiated, the call will 593 * return EPVSocketFailure and there will be no callback. 594 */ 595 OSCL_IMPORT_REF TPVSocketEvent Recv(uint8* aPtr, uint32 aMaxLen, 596 int32 aTimeoutMsec = -1); 597 598 /** 599 * Cancel Recv 600 * 601 * This method will cancel any pending Recv operation 602 * on the current socket, causing the Recv to complete 603 * with error EPVSocketCancel. If there is no pending 604 * Recv operation, this method will have no effect. 605 */ 606 OSCL_IMPORT_REF void CancelRecv(); 607 608 private: 609 static OsclTCPSocket *NewL(Oscl_DefAlloc &alloc, OsclTCPSocketI* aSocket); 610 611 private: 612 OsclTCPSocket(Oscl_DefAlloc &alloc): iTCPSocket(NULL), iAlloc(alloc) {} 613 OsclTCPSocketI *iTCPSocket; 614 Oscl_DefAlloc &iAlloc; 615}; 616 617#endif 618 619 620