/*===========================================================================
                    IMPORTANT NOTICE

                  OEM DISTRIBUTION ONLY

   S O C K E T   A P I   H E A D E R   F I L E
                   
DESCRIPTION

 The OEM Socket Header File. Contains declarations for functions.


        Copyright © 2000-2002 QUALCOMM Incorporated.
               All Rights Reserved.
            QUALCOMM Proprietary/GTDR
===========================================================================*/
#ifndef OEMSOCK_H
#define OEMSOCK_H


#include "AEE_OEMComdef.h"
#include "AEEComdef.h"
#include "AEEError.h"
#include "AEENet.h"

#include "AEEQoSSession.h"

#define AEE_NET_WRITE_EVENT  0x01     /* writeable socket */
#define AEE_NET_READ_EVENT   0x02     /* readable socket */
#define AEE_NET_CLOSE_EVENT  0x04     /* closeable socket */

#include "OEMSock_QoSSpec.h"

#if defined(__cplusplus)
extern "C" {
#endif
  

/*===========================================================================

                      PUBLIC FUNCTION DECLARATIONS

===========================================================================*/

extern OEMCONTEXT OEMNet_Open
(
   int          nNetwork,
   AEECallback *pcbNetWaiter,
   AEECallback *pcbSocketWaiter,
   AEECallback *pcbQoSWaiter,
   int16       *err
);

extern int16 OEMNet_Close
(
   OEMCONTEXT netd
);

extern void OEMNet_SetNetWaiter
(
   OEMCONTEXT   netd,
   AEECallback *pcbWaiter
);

extern void OEMNet_SetMTPDWaiter
(
   OEMCONTEXT   netd,
   AEECallback *pcbWaiter
);

extern void OEMNet_SetQoSWaiter
(
   OEMCONTEXT   netd,
   AEECallback *pcbWaiter
);

extern int16 OEMNet_RegisterToMTPD
(
   OEMCONTEXT   netd,
   AEECallback *pcbWaiter
);

extern int16 OEMNet_DeRegisterFromMTPD
(
   OEMCONTEXT   netd
);

extern void OEMNet_SetSocketWaiter
(
   OEMCONTEXT   netd,
   AEECallback *pcbWaiter
);

extern PFNNOTIFY OEMNet_InstallSocketEventHandler
(
   OEMCONTEXT netd,
   PFNNOTIFY
);

extern int16 OEMNet_PPPOpen
(
   OEMCONTEXT netd
);

extern int16 OEMNet_PPPClose
(
   OEMCONTEXT netd
);

extern NetState OEMNet_PPPState
( 
   OEMCONTEXT netd
);

extern int16 OEMNet_NameServers
(
   OEMCONTEXT netd,
   INAddr    *ainaAddrs,
   int       *pnNumAddrs
);

extern int16 OEMNet_GetRLP3Cfg
(
   OEMCONTEXT  netd,
   int16       nOptName,
   AEERLP3Cfg *prlp3
);

extern int16 OEMNet_SetRLP3Cfg
(
   OEMCONTEXT        netd,
   int16             nOptName,
   const AEERLP3Cfg *prlp3
);

extern int16 OEMNet_SetPPPAuth
(
   OEMCONTEXT  netd,
   const char *pszAuth
);

extern int16 OEMNet_GetPPPAuth
(
   OEMCONTEXT netd,
   char      *pszAuth, 
   int       *pnLen
);

extern int16 OEMNet_SetDDTMPref
(
   OEMCONTEXT netd,
   boolean    bOn
);

extern int16 OEMNet_MyIPAddr
(
   OEMCONTEXT netd,
   INAddr    *addr          /* IP address: network byte order */
);

extern int16 OEMNet_GetUrgent
(
   OEMCONTEXT    netd,
   AEEUDPUrgent *pUrgent
);

extern int16 OEMNet_GetNativeDescriptor
(
   OEMCONTEXT netd,
   uint32    *pdwDesc
);

extern int16 OEMNet_GetDefaultNetwork
(
   int       *pnNetwork
);

extern int16 OEMNet_GetUMTSCount
(
   uint16    *pwCount
);

extern int16 OEMNet_GetUMTSInfo
(
   uint16       wNumber,
   AEEUMTSInfo* pInfo
);

extern int16 OEMNet_SetDormancyTimeout
(
   OEMCONTEXT netd,
   uint8      ucSecs
);

extern int16 OEMNet_RequestQoS
(
   OEMCONTEXT           netd,
   oem_qos_spec_type   *pQoS,
   oem_qos_handle_type *pHandle
);

extern int16 OEMNet_ReleaseQoS
(
   OEMCONTEXT           netd,
   oem_qos_handle_type  handle
);

extern int16 OEMNet_GetQoSFlowSpec
(
   OEMCONTEXT           netd,
   oem_qos_handle_type  handle,
   oem_ip_flow_type    *pRxFlow,
   oem_ip_flow_type    *pTxFlow
);

extern uint16 OEMNet_GetQoSStatus
(
   OEMCONTEXT           netd,
   oem_qos_handle_type  handle
);

extern uint16 OEMNet_QoSGoActive
(
   OEMCONTEXT           netd,
   oem_qos_handle_type  handle
);

extern uint16 OEMNet_SetQoSDormancyTimeout
(
   OEMCONTEXT           netd,
   oem_qos_handle_type  handle,
   uint8                ucSecs
);

extern int32 OEMNet_GetQoSEventInfo(
   OEMCONTEXT           netd,
   oem_qos_handle_type *pHandle,
   AEEQoSEvent         *pEvent,
   AEEQoSInfoCode      *pInfoCode
);

extern int16 OEMSocket_GetSockName
(
   OEMCONTEXT            sockd,         /* Socket descriptor */
   INAddr               *addr,          /* IP address: network byte order */
   INPort               *port           /* port number: network byte order */
);

extern int16 OEMSocket_GetPeerName
(
   OEMCONTEXT            sockd,         /* Socket descriptor */
   INAddr               *addr,          /* IP address: network byte order */
   INPort               *port           /* port number: network byte order */
);

extern OEMCONTEXT OEMSocket_Open
(
   OEMCONTEXT            netd,
   NetSocket             type,          /* socket type */
   int16                *err
);

extern int16 OEMSocket_Connect
(
   OEMCONTEXT            sockd,         /* Socket descriptor */
   INAddr                addr,          /* IP address: network byte order */
   INPort                port           /* port number: network byte order */
);

extern int16 OEMSocket_Bind
(
   OEMCONTEXT            sockd,         /* socket descriptor */
   INAddr                addr,          /* IP addr: network byte order */
   INPort                port           /* port number: network byte order */
);

extern int16 OEMSocket_Close
(
   OEMCONTEXT            sockd          /* socket descriptor */
);

extern int32 OEMSocket_Write
(
   OEMCONTEXT            sockd,         /* socket descriptor */
   const byte           *buffer,        /* user buffer from which to copy data */
   uint32                nbytes,        /* number of bytes to be written to socket */
   int16                *err
);

extern int32 OEMSocket_Read
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  byte                 *buffer,        /* user buffer to which to copy data */
  uint32                nbytes,        /* number of bytes to be read from socket */
  int16                 *err
);

extern int32 OEMSocket_Writev
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  const SockIOBlock     iov[],         /* array of data buffers from which to copy data */
  uint16                iovcount,      /* number of array items */
  int16                 *err
);

extern int32 OEMSocket_Readv
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  SockIOBlock           iov[],         /* array of data buffers to copy data into */
  uint16                iovcount,      /* number of array items */
  int16                 *err
);

extern int32 OEMSocket_SendTo
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  const byte            *buffer,       /* user buffer from which to copy the data */
  uint32                nbytes,        /* number of bytes to be written */
  uint32                flags,         /* data transport options */
  INAddr                addr,          /* IP address: network byte order */
  INPort                port,          /* port number: network byte order */
  int16                 *err
);

extern int32 OEMSocket_RecvFrom
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  byte                 *buffer,        /* user buffer from which to copy the data */
  uint32                nbytes,        /* number of bytes to be written */
  uint32                flags,         /* unused */
  INAddr               *addr,          /* IP address: network byte order */
  INPort               *port,          /* port number: network byte order */
  int16                 *err
);

extern int16 OEMSocket_AsyncSelect
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  int32                 mask           /* bitmask of events to set */
);

extern int32 OEMSocket_GetNextEvent
( 
  OEMCONTEXT            *sockd,        /* socket descriptor */
  int16                 *err
);

extern int16 OEMSocket_Listen
(
  OEMCONTEXT             sockd,        /* socket descriptor */
  int16                  nMaxBacklog   /* maximum backlog of unaccepted sockets */
);

extern OEMCONTEXT OEMSocket_Accept
(
  OEMCONTEXT            sockd,         /* Listen socket descriptor */
  int16                *err
);

extern int16 OEMSocket_Shutdown
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  int32                 how            /* how to shutdown (AEE_SHUTDOWN_*) */
);

extern int16 OEMSocket_GetNativeDescriptor
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  uint32               *pdwDesc
);

extern int16 OEMSocket_SetKeepAlive
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean               bKeepAlive
);

extern int16 OEMSocket_SetLinger
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean               bOn,           // linger on or off
  uint32                dwLinger       // linger time, in seconds
);

extern int16 OEMSocket_SetRcvBuf
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  int                   nRcvBuf
);

extern int16 OEMSocket_SetSndBuf
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  int                   nSndBuf
);

extern int16 OEMSocket_SetNoDelay
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean               bNoDelay
);

extern int16 OEMSocket_SetDelayedAck
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean               bDelayedAck
);

extern int16 OEMSocket_SetSACK
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean               bSACK
);

extern int16 OEMSocket_SetTimeStamp
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean               bTimeStamp
);

extern int16 OEMSocket_SetMembership
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean               bAdd,          // Add or Drop membership
  INAddr                nMCast         // multicast group to join/leave
);

extern int16 OEMSocket_GetKeepAlive
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean              *pbKeepAlive
);

extern int16 OEMSocket_GetLinger
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean              *pbOn,          // linger on or off
  uint32               *pdwLinger      // linger time, in seconds
);

extern int16 OEMSocket_GetRcvBuf
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  int                  *pnRcvBuf
);

extern int16 OEMSocket_GetSndBuf
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  int                  *pnSndBuf
);

extern int16 OEMSocket_GetNoDelay
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean              *pbNoDelay
);

extern int16 OEMSocket_GetDelayedAck
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean              *pbDelayedAck
);

extern int16 OEMSocket_GetSACK
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean              *pbSACK
);

extern int16 OEMSocket_GetTimeStamp
(
  OEMCONTEXT            sockd,         /* socket descriptor */
  boolean              *pbTimeStamp
);

#if defined(__cplusplus)
}
#endif

/*========================================================================
  INTERFACES DOCUMENTATION
=======================================================================
OEMNet Interface
=======================================================================

Function: OEMNet_Open()

Description:
   Opens up a network.  
  
Prototype:
   OEMCONTEXT OEMNet_Open
   (
        int          nNetwork,
        AEECallback *pcbNetWaiter,
        AEECallback *pcbSocketWaiter,
        AEECallback *pcbQoSWaiter,
        int16       *err
   );
      
Parameters:
   int: network type (AEE_NETWORK_*)
   pcbNetWaiter: callback to be resumed when a network event occurs
   pcbSocketWaiter: callback to be resumed when a socket event occurs
   pcbQoSWaiter: callback to be resumed when a QoS event occurs
   err: error code (returned by operation) 

Return Value:
   On successful creation of a network, this function returns network 
   descriptor which is a signed value greater than or equal to 0.  On error, 
   returns AEE_NET_ERROR.  Error specifics are returned via the err parameter.

Comments:
   None

Side Effects:
   None

See Also:
   None

=======================================================================

Function: OEMNet_Close()

Description:
   Closes the specified network.  All corresponding sockets must have
   been closed for the network, prior to closing.
  
Prototype:
   int16 OEMNet_Close( OEMCONTEXT netd );
      
Parameters:
   netd: network descriptor

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

=======================================================================

Function: OEMNet_SetSocketWaiter()

Description:
   Registers new socket waiter callback, which waits for socket events,
   while replacing the previous waiter.
  
Prototype:
   void OEMNet_SetSocketWaiter
   (
      OEMCONTEXT   netd,
      AEECallback *pcbWaiter
   );
      
Parameters:
   netd: network descriptor
   pcbWaiter: callback to be resumed when a socket event occurs

Return Value:
   None

Comments:
   The installed socket event handler (see OEMNet_InstallSocketEventHandler)
   is not affected by calling this function.

Side Effects:
   None

See Also:
   None

=======================================================================

Function: OEMNet_SetNetWaiter()

Description:
   Registers a new network waiter, which waits for network events,
   while replacing the previous waiter.
  
Prototype:
   void OEMNet_SetNetWaiter
   (
      OEMCONTEXT   netd,
      AEECallback* pcbWaiter
   );
      
Parameters:
   netd: network descriptor
   pcbWaiter: callback to be resumed when a network event occurs

Return Value:
   None

Comments:
   None

Side Effects:
   None

See Also:
   None

=======================================================================

Function: OEMNet_SetMTPDWaiter()

Description:
   Registers a new MT packet data waiter, which waits for MT packet data
   events, while replacing the previous waiter.
  
Prototype:
   void OEMNet_SetMTPDWaiter
   (
      OEMCONTEXT   netd,
      AEECallback *pcbWaiter
   );
      
Parameters:
   netd: network descriptor
   pcbWaiter: callback to be resumed when a MT packet data event occurs

Return Value:
   None

Comments:
   None

Side Effects:
   None

See Also:
   None

=======================================================================

Function: OEMNet_SetQoSWaiter()

Description:
   Registers a new QoS event waiter, which waits for QoS events,
   while replacing the previous waiter.
  
Prototype:
   void OEMNet_SetQoSWaiter
   (
      OEMCONTEXT   netd,
      AEECallback *pcbWaiter
   );
      
Parameters:
   netd: network descriptor
   pcbWaiter: callback to be resumed when a QoS event occurs

Return Value:
   None

Comments:
   None

Side Effects:
   None

See Also:
   None

=======================================================================

Function: OEMNet_RegisterToMTPD()

Description:
   Sets the MT packet data waiter and then registers to MT packet data events.
  
Prototype:
   int16 OEMNet_RegisterToMTPD
   (
      OEMCONTEXT   netd,
      AEECallback *pcbWaiter
   );
      
Parameters:
   netd: network descriptor
   pcbWaiter: callback to be resumed when a MT packet data event occurs

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   OEMNet_DeRegisterFromMTPD()

=======================================================================

Function: OEMNet_DeRegisterFromMTPD()

Description:
   Clears the MT packet data waiter and then de-registers from MT packet data
   events.
  
Prototype:
   int16 OEMNet_DeRegisterFromMTPD
   (
      OEMCONTEXT   netd
   );
      
Parameters:
   netd: network descriptor

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   OEMNet_RegisterToMTPD()

=======================================================================

Function: OEMNet_InstallSocketEventHandler()

Description:
   Installs a socket event handler that will be called whenever a
   socket event occurs.  If the socket handler returns TRUE, the event
   is assumed to be consumed, and no further processing will be done on
   the event.  If the socket handler does not consume the event, it
   should return FALSE.
  
Prototype:
   PFNNOTIFY OEMNet_InstallSocketEventHandler(OEMCONTEXT netd,
                                              PFNNOTIFY pfnSocketEventHandler);
      
Parameters:
   netd: network descriptor
   pfnSocketEventHandler - pointer to new socket event handler, or NULL
                           to deinstall an existing handler

Return Value:
   The previous socket event handler (may be NULL).

Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================

Function: OEMNet_PPPOpen()

Description:
   Starts up the network subsystem and establishes a network connection
   to the internet.  After the connection is established, the OEM should
   resume the net waiter callback to indicate to the libraries that
   the connection is ready for use.
  
Prototype:
   int16 OEMNet_PPPOpen( OEMCONTEXT netd );
      
Parameters:
   netd: network descriptor

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   Initiates call origination and PPP negotiation.

See Also:
   None

========================================================================

Function: OEMNet_PPPClose()

Description:
   Initiates termination to bring down any network connections started with
   OEMNET_PPPOpen.  

   This function is asynchronous, and should resume the net waiter callback
   upon completion of the close operation.

Prototype:
   int16 OEMNet_PPPClose( OEMCONTEXT netd );

Parameters:
   netd: network descriptor

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   Initiates termination of PPP and any lower layer connections.

See Also:
   None

===========================================================================

Function: OEMNet_NameServers()

Description:
        This function allows the caller to discover the configured name
server addresses.  The addresses may come from PPP setup or from phone
configuration, or both.  If it's both, the phone config addresses are listed
first, followed by the PPP setup addresses.  This has the effect of the 
phone config addresses being treated as overrides by AEEDNS, etc.

Prototype:
   int16  OEMNet_NameServers(OEMCONTEXT netd, INAddr *ainaAddrs, int *pnNumAddrs);

Parameters:
   netd: network descriptor
   ainaAddrs: [in/out] a caller-allocated array of INAddrs, filled by INetMgr
              with the answer to the question: "which nameservers?"  If NULL,
              pnNumAddrs is filled with the number of addresses available .
   pnNumAddrs: [in/out] caller sets this to array size of ainaAddrs, set by
              INetMgr to the number filled(if ainaAddrs is non-null)/available

Return Value:
   SUCCESS: if the addresses are found, filled
   EBADPARM: if pnNumAddrs is null

Comments:  
   pnNumAddrs may be set to 0 if there is no servers configured in 
    NVRam and there is no PPP setup available

  the addresses returned in ainaAddrs must be in network byte-order

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMNet_GetRLP3Cfg()

Description:
        This function allows the caller to discover the configured RLP 
settings, if the OEM's network layer is implemented using RLP.

Prototype:
   int16 OEMNet_GetRLP3Cfg(OEMCONTEXT netd, int16 nOptName,AEERLP3Cfg *prlp3)

Parameters:
   netd: network descriptor
   int16 nOptName: one of 3 values:
              INET_OPT_DEF_RLP3 : retrieve default RLP3 settings
              INET_OPT_CUR_RLP3 : retrieve current RLP3 settings
              INET_OPT_NEG_RLP3 : retrieve negotiated RLP3 settings

   AEERLP3Cfg prlp3: [out] filled with relevant settings

Return Value:
   SUCCESS: if the settings were retrieved
   EUNSUPPORTED: if RLP isn't employed or this API is otherwise unsupported

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMNet_SetRLP3Cfg()

Description:
        This function allows the caller to modify the configured RLP 
     settings, if the OEM's network layer is implemented using RLP.

Prototype:
   int16 OEMNet_SetRLP3Cfg(OEMCONTEXT netd, int16 nOptName,AEERLP3Cfg *prlp3)

Parameters:
   netd: network descriptor
   int16 nOptName: one of 2 values:
              INET_OPT_DEF_RLP3 : set default RLP3 settings
              INET_OPT_CUR_RLP3 : set current RLP3 settings

   AEERLP3Cfg prlp3: the new settings

Return Value:
   SUCCESS: if the settings were configured
   EUNSUPPORTED: if RLP isn't employed or this API is otherwise unsupported

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMNet_SetPPPAuth()

Description:
        This function allows the caller to modify the configured PPP
   authentication settings, if this is relevant to the network implementation.

Prototype:
   int16 OEMNet_SetPPPAuth(OEMCONTEXT netd, const char *cpszAuth)


Parameters:
   netd: network descriptor
   const char *cpszAuth: the new credentials, in the form of 2 concatenated, null terminated strings, e.g.: "userid@vzw.com\000password\000"

Return Value:
   SUCCESS: if the credentials were set
   EUNSUPPORTED: if PPP authentication cannot be configured

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMNet_GetPPPAuth()

Description:
        This function allows the caller to retrieve the configured PPP
   authentication settings, if this is relevant to the network implementation.

Prototype:
   int16 OEMNet_GetPPPAuth(OEMCONTEXT netd, char *pszAuth, int *pnLen)


Parameters:
   netd: network descriptor
   char *pszAuth: [out] the buffer into which the credentials are to 
                  be copied, in the form of 2 concatenated, null 
                  terminated strings, e.g.: "userid@vzw.com\000password\000"
   int *pnLen: [in/out] the size of pszAuth.  If pszAuth is NULL, pnLen is 
                ignored on input, and set to the number of bytes required to 
                hold authentication information on output.

Return Value:
   SUCCESS: if the credentials were retrieved
   EUNSUPPORTED: if PPP authentication cannot be configured

Comments:  
   None

Side Effects: 
   None

See Also:
   None

===========================================================================

Function: OEMNet_SetDDTMPref()

Description:
        This function allows the caller to modify the data dedicated
        transmission mode preference, if this is relevant to the
        network implementation.

Prototype:
   int16 OEMNet_SetDDTMPref(OEMCONTEXT netd, boolean bOn)


Parameters:
   netd: network descriptor
   boolean bOn: TRUE to turn DDTM on, FALSE otherwise

Return Value:
   SUCCESS: if the DDTM preference was set
   EUNSUPPORTED: if DDTM preference cannot be configured

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMNet_PPPState()

Description:
   Returns a value indicating the status of the PPP connection.

   This function is synchronous, and should not callback any notification
   function.

Prototype:
   NetState OEMNet_PPPState
   (
      OEMCONTEXT netd
   );

Parameters:
   netd: network descriptor

Return Value:
   Returns an enumerated value of type NetState describing the network layer's
   current status.  These are:
      NET_PPP_OPENING - The network layer is being opened.  The AEE libraries
                        will defer work until NET_PPP_OPEN is returned.

      NET_PPP_OPEN - The network layer is open, and can make new sockets,
                     service existing sockets, or both.

      NET_PPP_CLOSING - The network layer is in the process of closing.
                        The AEE libraries will not try to create new sockets,
                        service existing sockets, or open the net library
                        while in this state.

      NET_PPP_CLOSED -  The network layer is closed.  The AEE libraries will
                        not try to create or service sockets in this state,
                        but may open the library.

Side Effects:
   None

See Also:
   None

========================================================================

Function: OEMNet_MyIPAddr()

Description:
   Returns the IP address of the active session.  NOTE: The IP address is
   in network byte order.

   This function is synchronous, and therefore should not callback any 
   notification function.
  
Prototype:
   int16 OEMSocket_MyIPAddr
   (
     OEMCONTEXT netd,
     INAddr    *addr
   );

Parameters:
   netd: network descriptor
   addr: pointer to location where IP will be placed

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================

Function: OEMNet_GetUrgent()

Description:
   Determines whether urgent sendto option is supported and the payload
   limit, if any.

   This function is synchronous, and therefore should not callback any 
   notification function.
  
Prototype:
   int16 OEMNet_GetUrgent
   (
     OEMCONTEXT    netd,
     AEEUDPUrgent *pUrgent
   );

Parameters:
   netd: network descriptor
   pUrgent: pointer to AEEUDPUrgent struct

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMNet_GetNativeDescriptor()

Description:
   Returns the native network descriptor from the underlying implementation.

Prototype:
   int16 OEMNet_NativeDescriptor
   (
      OEMCONTEXT netd,
      uint32    *pdwDesc
   );

Parameters:
   netd: network descriptor
   pdwDesc: pointer to dword, which will be filled in with the native descriptor

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMNet_GetDefaultNetwork()

Description:
   Returns the default network (AEE_NETWORK_*)

Prototype:
   int16 OEMNet_GetDefaultNetwork
   (
      int *pnDefault
   );

Parameters:
   pnNetwork: pointer to int, which will be filled in with the
                    default network (AEE_NETWORK_*)

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMNet_GetUMTSCount()

Description:
   Returns the number of PDP contexts.

Prototype:
   int16 OEMNet_GetUMTSCount
   (
      uint16 *pwCount
   );

Parameters:
   pwCount: pointer to word, which will be filled in with the
                   number of PDP contexts

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================
Function: OEMNet_GetUMTSInfo()

Description:
   Returns the requested PDP information.

Prototype:
   int16 OEMNet_GetUMTSInfo
   (
      uint16       wNumber,
      AEEUMTSInfo *pInfo
   );

Parameters:
   wNumber: the PDP of interest
   pInfo  : filled in with profile info

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================
Function: OEMNet_SetDormancyTimeout()

Description:
  Set the packet data dormancy timeout value (idle timeout after which mobile
  should enter dormancy).
  Applies only to IS-707 (cdma2000 1x) networks.

Prototype:
   int16 OEMNet_SetDormancyTimeout
   (
      OEMCONTEXT netd,
      uint8      ucSecs
   );

Parameters:
   netd:   network descriptor
   ucSecs: timeout value in seconds

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================
Function: OEMNet_RequestQoS()

Description:
   Requests Quality of Service

Prototype:
   int16 OEMNet_RequestQoS
   (
      OEMCONTEXT           netd,
      oem_qos_spec_type   *pQoS,
      oem_qos_handle_type *pHandle
   );

Parameters:
   netd: network descriptor
   pQoS:  pointer to a valid input and output QoS specification.
          the QoS specification will be read and its error mask fields
          will be updated as needed to indicate erronious paramters.
          (pre-allocated by caller)
   pHandle: filled in with a new QoS handle that identifies the QoS 
            instance that handles the QoS request
            (pre-allocated by caller)

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================

Function: OEMNet_ReleaseQoS()

Description:
   Releases a granted Quality of Service, identified by its handle value

Prototype:
   int16 OEMNet_ReleaseQoS
   (
      OEMCONTEXT           netd,
      oem_qos_handle_type  handle
   );

Parameters:
   netd: network descriptor
   handle: handle to the granted QoS instance
 
Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================

Function: OEMNet_GetQoSFlowSpec()

Description:
   Retrieve the flow specification of a granted Quality of Service instance,
   identified by its handle value 

Prototype:
   int16 OEMNet_GetQoSFlowSpec
   (
      OEMCONTEXT           netd,
      oem_qos_handle_type  handle,
      oem_ip_flow_type    *pRxFlow,
      oem_ip_flow_type    *pTxFlow
   )

Parameters:
   netd: network descriptor
   handle: handle to the granted QoS instance
   pRxFlow: pointer to the QoS Flow in the Rx direction, which will be
            filled with the QoS' Rx flow spec (pre-allocated by caller)
   pTxFlow: pointer to the QoS Flow in the Rx direction, which will be
            filled with the QoS' Rx flow spec (pre-allocated by caller)
 
Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================

Function: OEMNet_GetQoSStatus()

Description:
   Returns the status of a QoS instace

Prototype:
   uint16 OEMNet_GetQoSStatus
   (
      OEMCONTEXT          netd,
      oem_qos_handle_type handle
   );

Parameters:
   netd: network descriptor
   handle: handle to the QoS instance
 
Return Value:
   Returns NET_QOS_STATUS // TBD

Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================

Function: OEMNet_QoSGoActive()

Description:
   Tries to make a QoS instance go active

Prototype:
   uint16 OEMNet_QoSGoActive
   (
      OEMCONTEXT          netd,
      oem_qos_handle_type handle
   );

Parameters:
   netd: network descriptor
   handle: handle to the QoS instance
 
Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================

Function: OEMNet_SetQoSDormancyTimeout()

Description:
   Set a QoS inactivity timeout value (idle timeout after which the QoS
   should enter dormancy)

Prototype:
   uint16 OEMNet_SetQoSDormancyTimeout
   (
      OEMCONTEXT          netd,
      oem_qos_handle_type handle,
      uint8               ucSecs
   );

Parameters:
   netd: network descriptor
   handle: handle to the QoS instance
   ucSecs: timeout value in seconds
 
Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================

Function: OEMNet_GetQoSEventInfo()

Description:
   Retrieve QoS event information.

Prototype:
   int32 OEMNet_GetQoSEventInfo(
      OEMCONTEXT           netd,
      oem_qos_handle_type *pHandle,
      AEEQoSEvent         *pEvent,
      uint32              *pInfoCode
   );

Parameters:
   netd: network descriptor
   pHandle: filled in with the QoS event's handle identification 
            (pre-allocated by caller)
   pEvent: filled in with the QoS event that occurred
           (pre-allocated by caller)
   pInfoCode: filled in with the QoS event's information code
              (pre-allocated by caller)
 
Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   Should be called after AEE recives a notification that QoS events  
   have occurred, in order to retrieve the data of these QoS events.

Side Effects:
   None

See Also:
   None

========================================================================
 INTERFACES   DOCUMENTATION
=======================================================================
Interface Name: OEMSocket 
=======================================================================

Function: OEMSocket_GetSockName()

Description:
   Returns the local IP address and port of a socket.  NOTE: the address
   and port will be in network byte order.

   This function is synchronous, and therefore should not call any notification
   functions.
  
Prototype:
   int16 OEMSocket_GetSockName
   (
      OEMCONTEXT sockd,
      INAddr    *addr,
      INPort	*port
   );

Parameters:
   sockd: [in] socket descriptor
   addr:   [out] IP address
   port:   [out] port number

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   INAddr, INPort

========================================================================

Function: OEMSocket_GetPeerName()

Description:
   Returns the IP address and port of a connected peer.  NOTE: the address
   and port will be in network byte order.

   This function is synchronous, and therefore should not call any notification
   functions.
  
Prototype:
   int16 OEMSocket_GetPeerName
   (
      OEMCONTEXT sockd,
      INAddr    *addr,
      INPort	*port
   );

Parameters:
   sockd:  [in] socket descriptor
   addr:   [out] IP address
   port:   [out] port number

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

==========================================================================

Function: OEMSocket_Open()

Description:
   Create a TCP or UDP socket and related data structures, and return a 
   reference to that socket.

   Supported Types:
   The OEM must support SOCK_STREAM (TCP) and SOCK_DGRAM (UDP) data types.

   Note this function must be called to obtain a valid socket descriptor, for
   use with all other socket-related functions.  Thus, before any socket
   functions can be used (e.g. I/O, asynchronous notification, etc.), this
   call must have successfully returned a valid socket descriptor.

   This function is synchronous, and therefore should not callback any 
   notification function.

Prototype:
   OEMCONTEXT OEMSocket_Open
   (
      OEMCONTEXT netd,
      NetSocket  type, 
      int16     *err
   );

Parameters:
   netd: network descriptor
   type: socket type (see above)
   err: error code (returned by operation) 

Return Value:
   On successful creation of a socket, this function returns socket  
   descriptor which is a signed value greater than or equal to 0.  On error, 
   returns AEE_NET_ERROR.  Error specifics are returned via the err parameter.
 
Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================

Function: OEMSocket_Connect()

Description:
   For TCP, attempts to establish the TCP connection.  Upon successful
   connection, should resume the socket waiter callback.
   OEMs implementations must not support connected UDP sockets, and must
   return an error if OEMSocket_Connect is called with a UDP socket.

   This function is asynchronous, and should resume the socket waiter
   callback if the connection attempt is completed or aborted, and the
   original error value was AEE_NET_SUCCESS or AEE_NET_EWOULDBLOCK.

Prototype:
   int16 OEMSocket_Connect
   (
      OEMCONTEXT sockd,                                       
      INAddr     addr,			
      INPort     port
   );

Parameters:
   sockd: socket descriptor
   addr: destination address in network byte order
   port: destination port in network byte order

Return Value:
   Returns AEE_NET_SUCCESS if arguments are valid, and the connection process
   could be started.  Thus, a return value of AEE_NET_SUCCESS does not indicate
   that the socket could be connected.  If an error can be detected immediately,
   returns one of the AEE designated error codes indicating reason for failure.

Comments:
   Must have called OEMSocket_Open() prior to use.

Side Effects:
   Starts connection process for a socket.  May automatically call bind() on
   that socket.

See Also:
   None

===========================================================================

Function: OEMSocket_Bind()

Description:
   For all client sockets, attaches a local address and port value to the 
   socket.  If the call is not explicitly issued, the socket will implicitly
   bind in calls to OEMSocket_Connect() or OEMSocket_SendTo().  Note that this 
   function does not support binding a local IP address, but rather ONLY a 
   local port number.  The local IP address is assigned automatically by the 
   sockets library.  The function must receive (as a parameter) a valid socket 
   descriptor, implying a previous successful call to OEMSocket_Open().

   OEMs are not required to provide bind() functionality to TCP sockets.

   This function is synchronous, and therefore should not callback any
   notification functions.

Prototype:
   int16 OEMSocket_Bind
   (
      OEMCONTEXT sockd,                                       
      INAddr     addr,			
      INPort     port
   );

Parameters:
   sockd: socket descriptor
   addr: destination address in network byte order
   port: local port in network byte order

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

========================================================================

Function: OEMSocket_Close()

Description:
   Non-blocking close of a socket.  Performs all necessary clean-up of data 
   structures and frees the socket for re-use.  For TCP initiates the active 
   close for connection termination.  After the TCP connection is complete,
   the socket resources may optionally not be freed.  In this case, this
   function should return AEE_NET_ERROR and set err to AEE_NET_EWOULDBLOCK.
   The aee libraries will receive notification via OEMSocket_AsyncSelect, 
   and call OEMSocket_Close again to free the resources.

   This function can be synchronous (returning anything other than *err
   set to AEE_NET_EWOULDBLOCK), or asynchronous as described above.  For
   asynchronous incantations, the socket waiter callback should be resumed
   if and only if the AEE_NET_CLOSE_EVENT was registered with
   OEMSocket_AsyncSelect.

Prototype:
   int16 OEMSocket_Close
   (
      OEMCONTEXT sockd
   );

Parameters:
   sockd: socket descriptor

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.  It should be noted
   that if the socket cannot be closed right away, the OEM may return an
   AEE_NET_EWOULDBLOCK error, indication that it should be called at a later
   time (through an indication via the OEMSocket_AsyncSelect() function.

Comments:
   None

Side Effects:
   Initiates active close for TCP connections.

See Also:
   OEMSocket_AsyncSelect()

========================================================================

Function: OEMSocket_Write()

Description:
   Sends specified number of bytes in the buffer over the TCP transport.
   If a socket is connected, but it is not possible to send or buffer
   data, the function should return AEE_NET_ERROR and set *err to be
   AEE_NET_WOULDBLOCK.

Prototype:
   int32 OEMSocket_Write
   (
      OEMCONTEXT  sockd,                                       
      const byte *buffer,
      uint32      bytes,
      int16      *err
   );

Parameters:
   sockd: socket descriptor
   buffer: user buffer from which to copy data
   nbytes: number of bytes to be written to socket
   err: error code (returned by operation) 

Return Value:
   On success, returns the number of bytes written, which could be less than
   the number of bytes specified.  On error (including AEE_NET_EWOULDBLOCK), 
   returns AEE_NET_ERROR. 

Comments:
   None

Side Effects:
   None

See Also:
   None

==========================================================================

Function: OEMSocket_Read()

Description:
   Reads specified number of bytes into buffer from the TCP transport.
   If the socket is connected, but there is no data to read, the function
   should return AEE_NET_ERROR and set *err to AEE_NET_EWOULDBLOCK.

Prototype:
   int32 OEMSocket_Read
   (
      OEMCONTEXT sockd,                                       
      byte      *buffer,
      uint32     nbytes,
      int16     *err
   );

Parameters:
   sockd: socket descriptor
   buffer: user buffer to which to copy data
   nbytes: number of bytes to be read from socket
   err: error code (returned by operation) 

Return Value:
   On success, returns the number of bytes read, which could be less than
   the number of bytes specified.  On error, returns AEE_NET_ERROR, including
   when *err == AEE_NET_EWOULDBLOCK.

   NOTE: A return of 0, indicates that an End-of-File condition has occurred.

Comments:
   None

Side Effects:
   None

See Also:
   None

==========================================================================

Function: OEMSocket_Writev()

Description:
   Provides the gather write variant of OEMSocket_Write(), which 
   allows the application to write from non-contiguous buffers.    Sends 
   specified number of bytes in the buffer over the TCP transport.

Prototype:
   int32 OEMSocket_Writev
   (
      OEMCONTEXT        sockd,                                       
      const SockIOBlock iov[],     
      uint16            iovcount,
      int16            *err
   );

Parameters:
   sockd: socket descriptor
   iov: array of data buffers from which to copy data
   iovcount: number of array items
   err: error code (returned by operation) 

Return Value:
   On success, returns the number of bytes written, which could be less
   than the number of bytes specified.  On error, returns AEE_NET_ERROR.

Comments:
   None

Side Effects:
   None

See Also:
   None

==========================================================================

Function: OEMSocket_Readv()

Description:
   Provides the scatter read variant of OEMSocket_Read(), which 
   allows the application to read into non-contiguous buffers.    Reads
   specified number of bytes into the buffer from the TCP transport.

Prototype:
   int32 OEMSocket_Readv
   (
      OEMCONTEXT  sockd,                                       
      SockIOBlock iov[],           
      uint16      iovcount,                                   
      int16      *err
   );

Parameters:
   sockd: socket descriptor
   iov: array of data buffers to copy data into
   iovcount: number of array items
   err: error code (returned by operation) 

Return Value:
   On success, returns the number of bytes read, which could be less than
   the number of bytes specified.  On error, returns AEE_NET_ERROR.

   NOTE: A return of 0, indicates that an End-of-File condition has occurred.

Comments:
   None

Side Effects:
   None

See Also:
   None

==========================================================================

Function: OEMSocket_SendTo()

Description:
   Sends 'nbytes' bytes in the buffer over the UDP transport.

Prototype:
   int32 OEMSocket_SendTo
   (
      OEMCONTEXT  sockd,                                       
      const byte *buffer,               
      uint32      nbytes,                          
      uint32      flags,
      INAddr      addr,
      INPort      port,
      int16      *err
   );

Parameters:
   sockd: socket descriptor
   buffer: user buffer from which to copy the data
   nbytes: number of bytes to be written
   flags: send flags
   addr: destination IP address in network byte order
   port: destination UDP port
   err: error code (returned by operation) 

Return Value:
   On success, returns the number of bytes to be written, which could be
   less than the number of bytes specified.  On error, returns AEE_NET_ERROR.

Comments:
   Currently supported flags are documented in AEENet.h.

   For cdma2000, the URGENT flag corresponds to use of Short Data Burst (SDB)
   over the reversed enhanced access channel (R-EACH). The WAKEUP flag requests
   traffic channel origination immediately after the SDB attempt.  This is
   necessary because the cdma2000 standard currently requires origination to
   take priority over any other access attempt, and thus the short data burst
   would either be prematurely aborted or undesirably delayed.

Side Effects:
   None

See Also:
   None

==========================================================================

Function: OEMSocket_RecvFrom()

Description:
   Reads 'nbytes' bytes in the buffer from the UDP transport.  Fills in
   address structure with values from who sent the data.

Prototype:
   int32 OEMSocket_RecvFrom
   (
      OEMCONTEXT sockd,                                       
      byte      *buffer,               
      uint32     nbytes,
      INAddr    *addr,
      INPort    *port,
      int16     *err
   );

Parameters:
   sockd: socket descriptor
   buffer: user buffer from which to copy the data
   nbytes: number of bytes to be written
   addr: pointer to sender's IP address, in network byte order (returned 
         by operation)
   port: pointer to source UDP port, in network byte order (returned by 
         operation)
   err: error code (returned by operation) 

Return Value:
   On success, returns the number of bytes read, which could be less than the
   number of bytes specified.  On error, returns AEE_NET_ERROR.

Comments:
   None

Side Effects:
   None

See Also:
   None

==========================================================================

Function: OEMSocket_AsyncSelect()

Description:
   Enables the events to be notified about through the asynchronous 
   notification mechanism.  Application specifies a bitmask of events that it
   is interested in, for which it will receive asynchronous notification via
   its application callback function.  This function also performs a real-time
   check to determine if any of the events have already occurred, and if so
   resume either the Net waiter callback or the socket waiter callback
   according to the event.

   Events OEMs need to support are:
~
      AEE_NET_READ_EVENT: Socket is now available to read, or connect~
      AEE_NET_WRITE_EVENT: Socket is now available for writing~
      AEE_NET_CLOSE_EVENT: Socket is being closed~
*

Prototype:
   int16 OEMSocket_AsyncSelect
   (
      OEMCONTEXT sockd,                                       
      int32      interest_mask
   );

Parameters:
   sockd: socket descriptor
   mask: bitmask of events to set (see above)

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   Sets the relevant event mask in the socket control block.  Will also 
   notify the application via the callback function.

See Also:
   None

===========================================================================

Function: OEMSocket_GetNextEvent()

Description:
   This function performs a real-time check to determine if any of the events 
   of interest specified with the mask in OEMSocket_AsyncSelect() have 
   occurred.  It also clears any bits in the event mask that have occurred.
   The application must re-enable these events through a subsequent call to 
   OEMSocket_AsyncSelect().  The application passes in a pointer to a single 
   socket descriptor to determine if any events have occurred for that socket.

Prototype:
   int32 OEMSocket_GetNextEvent
   ( 
      OEMCONTEXT *sockd, 
      int16      *err
   );

Parameters:
   sockd: socket descriptor
   err: error code (returned by operation) 

Return Value:
   Returns an event mask of the events that were asserted.  A value of zero
   indicates that no events have occurred.

   On error, returns AEE_NET_ERROR.
   
Comments:
   None

Side Effects:
   Clears the bits in the socket control block event mask, corresponding to 
   the events that have occurred.

See Also:
   OEMSocket_AsyncSelect()

===========================================================================

Function: OEMSocket_Listen()

Description:
   Performs a passive open for connections, such that incoming connections 
   may be subsequently accepted.

   The socket must be a TCP socket that has been bound to a local port. The
   backlog parameter indicates the maximum length for the queue of pending
   connections.  If backlog is larger than the system maximum, it will be
   silently reduced to the system maximum. 

Prototype:
   int16 OEMSocket_Listen
   (
      OEMCONTEXT sockd,
      int16      backlog
   );

Parameters:
   sockd: socket descriptor
   backlog: maximum number of pending connections

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   OEMSocket_Accept()

===========================================================================

Function: OEMSocket_Accept()

Description:
   The accept function is used on listening sockets to respond when
   AEE_NET_READ_EVENT is asserted.  The first backlog queued connection is
   removed from the queue, and bound to a new socket (as if
   you called OEMSocket_Open).  The newly created socket is in the
   connected state.  The listening socket is unaffected and the queue
   size is maintained (i.e. there is no need to call listen again.)

Prototype:
   OEMCONTEXT OEMSocket_Accept
   (
      OEMCONTEXT sockd,
      int16     *err
   );

Parameters:
   sockd: listening socket descriptor
   err: error code (returned by operation) 

Return Value:
   On successful creation of a socket, this function returns socket file 
   descriptor which is OEM defined.  
   On error, returns AEE_NET_ERROR.  Error specifics are returned via the err parameter.

Comments:
   None

Side Effects:
   None

See Also:
   OEMSocket_Listen

===========================================================================

Function: OEMSocket_Shutdown()

Description:
   Causes all or part of a full-duplex connection to be terminated gracefully.

   If how is AEE_SHUTDOWN_RD, no more reads will be allowed.  If how is AEE_SHUTDOWN_WR,
   no more writes will be allowed (AKA half-close).  If how is AEE_SHUTDOWN_RDWR,
   both read and write will be disallowed.

Prototype:
   int16 OEMSocket_Shutdown
   (
      OEMCONTEXT sockd,
      int32      how
   );

Parameters:
   sockd: socket descriptor
   how: dictates which portion(s) of the connection to shutdown

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes (including AEE_NET_WOULDBLOCK) indicating
   reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_GetNativeDescriptor()

Description:
   Returns the native socket descriptor from the underlying implementation.

Prototype:
   int16 OEMSocket_GetNativeDescriptor
   (
      OEMCONTEXT sockd,
      uint32    *pdwDesc
   );

Parameters:
   sockd: socket descriptor of interest
   pdwDesc: pointer to dword, which will be filled in with the native descriptor

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_SetKeepAlive()

Description:
   Sets whether or not to periodically test if connection still alive.

Prototype:
   int16 OEMSocket_SetKeepAlive
   (
      OEMCONTEXT sockd,
      boolean    bKeepAlive
   );

Parameters:
   sockd: socket descriptor of interest
   bKeepAlive: whether or not to periodically test if connection still alive

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_SetLinger()

Description:
   Sets how to long to linger on close if data to send.

Prototype:
   int16 OEMSocket_SetLinger
   (
      OEMCONTEXT sockd,
      boolean    bOn,          // linger on or off
      uint32     dwLinger      // linger time, in seconds
   );

Parameters:
   sockd: socket descriptor of interest
   bOn: linger on or off
   dwLinger: linger time, in seconds

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_SetRcvBuf()

Description:
   Sets the receive buffer size.

Prototype:
   int16 OEMSocket_SetRcvBuf
   (
      OEMCONTEXT sockd,
      int        nRcvBuf
   );

Parameters:
   sockd: socket descriptor of interest
   nRcvBuf: the desired receive buffer size

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_SetSndBuf()

Description:
   Sets the send buffer size.

Prototype:
   int16 OEMSocket_SetSndBuf
   (
      OEMCONTEXT sockd,
      int        nSndBuf
   );

Parameters:
   sockd: socket descriptor of interest
   nSndBuf: the desired send buffer size

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_SetNoDelay()

Description:
   Disables the Nagle algorithm.

Prototype:
   int16 OEMSocket_SetNoDelay
   (
      OEMCONTEXT sockd,
      boolean    bNodelay
   );

Parameters:
   sockd: socket descriptor of interest
   bNoDelay: whether or not to disable the Nagle algorithm

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_SetDelayedAck()

Description:
   Sets the state of delayed ack.

Prototype:
   int16 OEMSocket_SetDelayedAck
   (
      OEMCONTEXT sockd,
      boolean    bDelayedAck
   );

Parameters:
   sockd: socket descriptor of interest
   bDelayedAck: whether or not to enable delayed ack

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_SetSACK()

Description:
   Enable SACK.

Prototype:
   int16 OEMSocket_SetSACK
   (
      OEMCONTEXT sockd,
      boolean    bSACK
   );

Parameters:
   sockd: socket descriptor of interest
   bSACK: whether or not to Enable SACK

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_SetTimeStamp()

Description:
   Enable TCP time stamp option.

Prototype:
   int16 OEMSocket_SetTimeStamp
   (
      OEMCONTEXT sockd,
      boolean    bTimeStamp
   );

Parameters:
   sockd: socket descriptor of interest
   bTimeStamp: whether or not to Enable TCP time stamp option

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_SetMembership()

Description:
   Join/leave a multicast group

Prototype:
int16 OEMSocket_SetMembership
(
  OEMCONTEXT sockd,
  boolean    bAdd,
  INAddr     nMCast
);


Parameters:
   sockd: socket descriptor of interest
   bAdd:  whether to add or drop membership
   nMCast: the multicast group to join/leave
    
Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_GetKeepAlive()

Description:
   Gets whether or not a connection is periodically tested if it is still alive.

Prototype:
   int16 OEMSocket_GetKeepAlive
   (
      OEMCONTEXT sockd,
      boolean   *pbKeepAlive
   );

Parameters:
   sockd: socket descriptor of interest
   pbKeepAlive: whether or not a connection is periodically tested if it is still alive (returned)

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_GetLinger()

Description:
   Gets how to long to linger on close if data to send.

Prototype:
   int16 OEMSocket_GetLinger
   (
      OEMCONTEXT sockd,
      boolean   *pbOn,          // linger on or off
      uint32    *pdwLinger      // linger time, in seconds
   );

Parameters:
   sockd: socket descriptor of interest
   *pbOn: linger on or off (returned)
   *pdwLinger: linger time, in seconds (returned)

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_GetRcvBuf()

Description:
   Gets the receive buffer size.

Prototype:
   int16 OEMSocket_GetRcvBuf
   (
      OEMCONTEXT sockd,
      int       *pnRcvBuf
   );

Parameters:
   sockd: socket descriptor of interest
   pnRcvBuf: the desired receive buffer size (returned)

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_GetSndBuf()

Description:
   Gets the send buffer size.

Prototype:
   int16 OEMSocket_GetSndBuf
   (
      OEMCONTEXT sockd,
      int       *pnSndBuf
   );

Parameters:
   sockd: socket descriptor of interest
   pnSndBuf: the desired send buffer size (returned)

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_GetNoDelay()

Description:
   Gets the state of the Nagle algorithm.

Prototype:
   int16 OEMSocket_GetSndBuf
   (
      OEMCONTEXT sockd,
      boolean   *pbNodelay
   );

Parameters:
   sockd: socket descriptor of interest
   pbNoDelay: whether or not the Nagle algorithm is disabled (returned)

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_GetDelayedAck()

Description:
   Gets the state of delayed ack.

Prototype:
   int16 OEMSocket_GetDelayedAck
   (
      OEMCONTEXT sockd,
      boolean   *pbDelayedAck
   );

Parameters:
   sockd: socket descriptor of interest
   pbDelayedAck: whether or not delayed ack is enabled (returned)

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_GetSACK()

Description:
   Gets the state of SACK.

Prototype:
   int16 OEMSocket_GetSACK
   (
      OEMCONTEXT sockd,
      boolean   *pbSACK
   );

Parameters:
   sockd: socket descriptor of interest
   pbSACK: whether or not SACK is enabled (returned)

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

===========================================================================

Function: OEMSocket_GetTimeStamp()

Description:
   Gets the state of TCP time stamp option.

Prototype:
   int16 OEMSocket_GetTimeStamp
   (
      OEMCONTEXT sockd,
      boolean   *pbTimeStamp
   );

Parameters:
   sockd: socket descriptor of interest
   pbTimeStamp: whether or not TCP time stamp option is enabled (returned)

Return Value:
   On success, returns AEE_NET_SUCCESS.  On error, returns one of the AEE
   designated error codes indicating reason for failure.

Comments:
   None

Side Effects:
   None

See Also:
   None

====================================================================== */

#endif /* OEMSOCK_H */

