/* 
+------------------------------------------------------------------------------
|  File:       socket.h
+------------------------------------------------------------------------------
|  Copyright 2002 Texas Instruments Berlin, AG 
|                 All rights reserved. 
| 
|                 This file is confidential and a trade secret of Texas 
|                 Instruments Berlin, AG 
|                 The receipt of or possession of this file does not convey 
|                 any rights to reproduce or disclose its contents or to 
|                 manufacture, use, or sell anything it may describe, in 
|                 whole, or in part, without the specific written consent of 
|                 Texas Instruments Berlin, AG. 
+----------------------------------------------------------------------------- 
|  Purpose :  This file implements the socket specific definitions to be used by applications in order to
|             set up a connection(GPRS or CSD) or create sockets for data receiption.
|             For a description of the socket API read g23m\condat\doc\8462_601.doc
+----------------------------------------------------------------------------- 
*/ 

#ifndef __SOCKET_H__
#define __SOCKET_H__

#include "typedefs.h"
#include "vsi.h"
#include "gsm.h"
#include "prim.h" // to get the DCM defines


/***************** Defines added for TCPIP testing with the application. ***********/

/*
 * Value constants for VAL_bearer_select
 */
#define DCM_SOCK_BEARER_ANY            (0x1)      /* DCM will decide which connection type to be used */
#define DCM_SOCK_BEARER_GPRS           (0x2)      /* Use a GPRS context as bearer, DCM will decide which GPRS settings to be used */
#define DCM_SOCK_BEARER_GSM            (0x3)      /* Use GSM data connection as bearer DCM will decide which GSM settings to be used */
#define DCM_SOCK_BEARER_USE_PROFILE    (0x4)      /* Use a specific data account for this connection */
#define DCM_SOCK_BEARER_AS_SPECIFIED   (0x5)      /* Use the data account information which is which is delivered within this signal */

/*
 * Value constants for VAL_authtype
 */
#define DCM_SOCK_AUTH_PAP              (0x1)      /* PAP authentification protocol  */
#define DCM_SOCK_AUTH_CHAP             (0x2)      /* CHAP authentification protocol !!! NOT SUPPORTED */
#define DCM_SOCK_AUTH_NO               (0x3)      /* No authentication              */

/*
 * user defined constants
 */
#define CDCM_APN_MAX_LEN               (0x64)     
#define CDCM_PHONE_NR_LEN              (0x54) 
#define CDCM_USER_MAX_LEN              (0x19)     
#define CDCM_PASSWORD_MAX_LEN          (0x19)     

/************************************************************************************/

/*
 * Maximum length of the full-qualified domain name of an Internet host
 */
#define SOCK_MAXHOSTNAMELEN 255

/* Maximum length (in octets) of a GPRS Access Point Name (APN). */
#define SOCK_MAX_APN_LEN CDCM_APN_MAX_LEN

/* Maximum length (in octets) of a telephone number. */
#define SOCK_MAX_PHONENUM_LEN CDCM_PHONE_NR_LEN

/* Maximum length (in octets) of a user id. */
#define SOCK_MAX_USERID_LEN CDCM_USER_MAX_LEN

/* Maximum length (in octets) of a user password. */
#define SOCK_MAX_PASSWORD_LEN CDCM_PASSWORD_MAX_LEN

/*
 * Type of an IP protocol
 * The values of this type are used as the 'ipproto' argument when creating
 * a socket to specify if a UDP socket or a TCP socket shall be created.
 */
typedef enum {
  SOCK_IPPROTO_TCP =  6,
  SOCK_IPPROTO_UDP = 17
} T_SOCK_IPPROTO;


/*
 * Type of a socket descriptor
 */
typedef unsigned long       T_SOCK_SOCKET;

/*
 * Type of an API instance
 */
typedef unsigned long       T_SOCK_API_INSTANCE;

/*
 * Type of an IP version 4 addresses in network byte order
 */
typedef unsigned long       T_SOCK_IPADDR;

#define SOCK_IPADDR_ANY    (T_SOCK_IPADDR)0  /*  Unspecified IP address */

/*
 * UDP or TCP port number in network byte order
 */
typedef unsigned short     T_SOCK_PORT;

#define SOCK_PORT_ANY      (T_SOCK_PORT)0    /* Unspecified port number */

/*
 * Convert U32 value from host byte order to network byte order
 */
#define SOCK_HTONL( x )  \
        ((U32)((((U32)( x )  & 0x000000ffU) << 24) | \
               (((U32)( x )  & 0x0000ff00U) <<  8) | \
               (((U32)( x )  & 0x00ff0000U) >>  8) | \
               (((U32)( x )  & 0xff000000U) >> 24)))

/*
 * Convert U16 value from host byte order to network byte order
 */
#define SOCK_HTONS( x )  \
        ((U16)((((U16)( x )  & 0x00ff) << 8) | \
               (((U16)( x )  & 0xff00) >> 8)))

/*
 * Convert U32 value from network byte order to host byte order
 */
#define SOCK_NTOHL( x ) \
        ((U32)((((U32)( x ) & 0x000000ffU) << 24) | \
               (((U32)( x ) & 0x0000ff00U) <<  8) | \
               (((U32)( x ) & 0x00ff0000U) >>  8) | \
               (((U32)( x ) & 0xff000000U) >> 24)))

/*
 * Convert U16 value from network byte order to host byte order
 */
#define SOCK_NTOHS( x ) \
        ((U16)((((U16)( x ) & 0x00ff) << 8) | \
               (((U16)( x ) & 0xff00) >> 8)))

/*
 * Construct IP address in network byte order from single octets.
 */
#define SOCK_MK_IPADDR( a, b, c, d ) \
        ((T_SOCK_IPADDR)((a << 24) | (b << 16) | (c << 8) | d))

/*
 * Type of a Socket API event
 */
typedef enum {
  SOCK_CREATE_CNF      =  1, /* Result event of sock_create() */
  SOCK_CLOSE_CNF       =  2, /* Result event of sock_close() */
  SOCK_BIND_CNF        =  3, /* Result event of sock_bind() */
  SOCK_LISTEN_CNF      =  4, /* Result event of sock_listen() */
  SOCK_CONNECT_CNF     =  5, /* Result event of sock_connect() */
  SOCK_SOCKNAME_CNF    =  6, /* Result event of sock_getsockname() */
  SOCK_PEERNAME_CNF    =  7, /* Result event of sock_getpeername() */
  SOCK_HOSTINFO_CNF    =  8, /* Result event of sock_gethostbyname() or sock_gethostbyaddr() */
  SOCK_MTU_SIZE_CNF    =  9, /* Result event of sock_get_mtu_size() */
  SOCK_RECV_IND        = 10, /* Network event: data has been received */
  SOCK_CONNECT_IND     = 11, /* Network event: an incoming connection has been accepted. */
  SOCK_CONN_CLOSED_IND = 12, /* Network event: connection has been closed by the remote peer */
  SOCK_ERROR_IND       = 13, /* Network event: an asynchronous error has occurred */
  SOCK_FLOW_READY_IND  = 14, /* Flow control: the API is ready to send data again */

  SOCK_OPEN_BEARER_CNF,      // Result Event of sock_open_bearer()
  SOCK_CLOSE_BEARER_CNF,     // Result event of sock_close_bearer()
  SOCK_BEARER_INFO_CNF,      // Result event of sock_bearer_info()
  SOCK_BAERER_CLOSED_IND     // The bearer connection has been closed
} T_SOCK_EVENTTYPE;

/*
 * Result codes of the API functions to indicate success or an error condition.
 * This type is used as the result code of the function and as the result value
 * in the associated event. It is also used for the error codes of a
 * 'SOCK_ERROR_IND' event
 */
typedef enum {
  SOCK_RESULT_OK                =  0, /* No problem detected. a corresponding primitive has been sent to the TCP/IP entity */
  SOCK_RESULT_INVALID_PARAMETER =  1, /* A parameter given to the function is invalid */
  SOCK_RESULT_INTERNAL_ERROR    =  2, /* An internal error has happened */
  SOCK_RESULT_ADDR_IN_USE       =  3, /* The address or port is already in use */
  SOCK_RESULT_OUT_OF_MEMORY     =  4, /* There is not enough memory to fulfill the request */
  SOCK_RESULT_NOT_SUPPORTED     =  5, /* The socket is not of a type that can support this operation */
  SOCK_RESULT_UNREACHABLE       =  6, /* The specified host cannot be reached */
  SOCK_RESULT_CONN_REFUSED      =  7, /* The connection to the specified address was refused by the remote host */
  SOCK_RESULT_TIMEOUT           =  8, /* The connection attempt timed out without establishing a connection */
  SOCK_RESULT_IS_CONNECTED      =  9, /* The request could not be fulfilled because the socket is already connected */
  SOCK_RESULT_HOST_NOT_FOUND    = 10, /* The specified host could not be found in the DNS */
  SOCK_RESULT_DNS_TEMP_ERROR    = 11, /* A temporary DNS error has occurred. Retrying the query may be successful */
  SOCK_RESULT_DNS_PERM_ERROR    = 12, /* A permanent DNS error has occurred */
  SOCK_RESULT_NO_IPADDR         = 13, /* The specified name has been found in the DNS, but no IP address is available */
  SOCK_RESULT_NOT_CONNECTED     = 14, /* The socket has not been connected yet */
  SOCK_RESULT_MSG_TOO_BIG       = 15, /* The size of the data buffer is too large for a UDP socket */
  SOCK_RESULT_CONN_RESET        = 16, /* The connection has been reset by the remote peer */
  SOCK_RESULT_CONN_ABORTED      = 17, /* The connection was aborted due to timeout or some other error condition */
  SOCK_RESULT_NO_BUFSPACE       = 18, /* Sending failed temporarily because the space to buffer the message was exhausted. */
  SOCK_RESULT_NETWORK_LOST, //	As a result code: The operation failed because TCP/IP's bearer connection has been disconnected.As an asynchronous event code: The bearer connection has been closed.
  SOCK_RESULT_NOT_READY, //	The operation failed because the bearer connection has not been opened.
  SOCK_RESULT_BEARER_NOT_READY, //	The bearer connection could not be opened because the mobile is not yet completely attached to the network. A retry at a later time may be successful.
  SOCK_RESULT_IN_PROGRESS, //	The operation failed because a similar operation is already in progress.
  SOCK_RESULT_BEARER_ACTIVE//	The operation failed because a bearer connection is already open.
} T_SOCK_RESULT;


/* Type of the bearer_select parameter of sock_open_bearer(), used to select the
 * type of the bearer connection to be opened by the Data Connection Manager 
 * (DCM), and of the bearer_type field of the T_SOCK_BEARER_INFO struct.
 */
typedef enum {
  SOCK_BEARER_ANY = DCM_SOCK_BEARER_ANY,
  SOCK_BEARER_GPRS = DCM_SOCK_BEARER_GPRS,
  SOCK_BEARER_GSM = DCM_SOCK_BEARER_GSM,
  SOCK_BEARER_USE_PROFILE = DCM_SOCK_BEARER_USE_PROFILE,
  SOCK_BEARER_AS_SPECIFIED = DCM_SOCK_BEARER_AS_SPECIFIED
} T_SOCK_BEARER_TYPE;

// FST: ?????
typedef enum {
  SOCK_AUTH_PAP = DCM_SOCK_AUTH_PAP,
  SOCK_AUTH_CHAP = DCM_SOCK_AUTH_CHAP,
  SOCK_AUTH_NO= DCM_SOCK_AUTH_NO
} T_SOCK_AUTHTYPE;

/*
 * Type of the generic event data structure passed
 * to the callback function on an event.
 * The actual event structure may be bigger(depending on its type),
 * but it will contain these fields at the beginning
 */
typedef struct {
  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
  T_SOCK_RESULT      result;      /* Result code of the operation */
  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
} T_SOCK_EVENTSTRUCT;

/*
 * Pointer to the callback function specified by the application
 */
typedef void (*T_SOCK_CALLBACK)(T_SOCK_EVENTSTRUCT* event, void *context);

/* System wide handle of a bearer connection.
 * Variables of this type are used as handles to identify a bearer connection. 
 * !! NOT NEEDED FOR CURRENT IMPLEMENTATION ONLY MENTIONED FOR FUTURE SUPPOSE.!!
 */
typedef U16 T_SOCK_BEARER_HANDLE;

typedef struct {
  T_SOCK_BEARER_HANDLE bearer_handle;
  T_HANDLE             app_handle;
  T_SOCK_BEARER_TYPE   bearer_type;
  BOOL                 apn_valid;
  char                 apn[SOCK_MAX_APN_LEN+1];
  BOOL                 phone_nr_valid;
  char                 phone_nr[SOCK_MAX_PHONENUM_LEN+1];
  BOOL                 user_id_valid;
  char                 user_id[SOCK_MAX_USERID_LEN+1];
  BOOL                 password_valid;
  char                 password[SOCK_MAX_PASSWORD_LEN+1];
  int                  cid;
  T_SOCK_IPADDR        ip_address;
  T_SOCK_IPADDR        dns1;
  T_SOCK_IPADDR        dns2;
  T_SOCK_IPADDR        gateway;
  T_SOCK_AUTHTYPE      authtype;
  BOOL                 data_compr;
  BOOL                 header_comp;
  int                  precedence;
  int                  delay;
  int                  reliability;
  int                  peak_throughput;
  int                  mean_througput;
  BOOL                 shareable;
} T_SOCK_BEARER_INFO;

/* ========================================================================== */
/* ==============================  Result Events from TCPIP ================= */

typedef struct {
  T_SOCK_EVENTTYPE     event_type;  /* Type of the event. */
  T_SOCK_RESULT        result;      /* Result code of the operation */
  T_SOCK_SOCKET        socket;      /* Socket for which the event occurred */
  T_SOCK_BEARER_HANDLE bearer_handle;
} T_SOCK_OPEN_BEARER_CNF;

typedef T_SOCK_EVENTSTRUCT T_SOCK_CLOSE_BEARER_CNF;

typedef struct {
  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
  T_SOCK_RESULT      result;      /* Result code of the operation */
  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
  T_SOCK_BEARER_INFO bearer_params;
} T_SOCK_BEARER_INFO_CNF;

typedef struct {
  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
  T_SOCK_RESULT      result;      /* Result code of the operation */
  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
  U32                dcm_error;   /* The parameter contains errors received from
                                   * PS (ETSI Spec 07.07) */
} T_SOCK_BAERER_CLOSED_IND;

typedef struct {
  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
  T_SOCK_RESULT      result;      /* Result code of the operation */
  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
} T_SOCK_CREATE_CNF;

typedef T_SOCK_EVENTSTRUCT      T_SOCK_CLOSE_CNF;
typedef T_SOCK_EVENTSTRUCT      T_SOCK_BIND_CNF;
typedef T_SOCK_EVENTSTRUCT      T_SOCK_LISTEN_CNF;
typedef T_SOCK_EVENTSTRUCT      T_SOCK_CONNECT_CNF;

typedef struct {
  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
  T_SOCK_RESULT      result;      /* Result code of the operation */
  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
  T_SOCK_IPADDR      ipaddr;      /* The local IP address of the socket */
  T_SOCK_PORT        port;        /* The local port number of the socket */
} T_SOCK_SOCKNAME_CNF;

typedef T_SOCK_SOCKNAME_CNF   T_SOCK_PEERNAME_CNF;

typedef struct {
  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
  T_SOCK_RESULT      result;      /* Result code of the operation */
  T_SOCK_SOCKET      socket;      /* unused */
  char               hostname[SOCK_MAXHOSTNAMELEN+1]; /* The name of the host as 
                                                      a zero-terminated string */
  T_SOCK_IPADDR      ipaddr;      /* The local IP address of the socket */
} T_SOCK_HOSTINFO_CNF;

typedef struct {
  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
  T_SOCK_RESULT      result;      /* Result code of the operation */
  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
  U16                mtu_size;    /* MTU size */
} T_SOCK_MTU_SIZE_CNF;

typedef struct {
  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
  T_SOCK_RESULT      result;      /* Result code of the operation */
  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
  U32                data_length; /* Length of the data portion received. */
  char               *data_buffer; /*  Pointer to the data received. The application
                                       shall free this data buffer after use. */
} T_SOCK_RECV_IND;


typedef struct {
  T_SOCK_EVENTTYPE   event_type;  /* Type of the event. */
  T_SOCK_RESULT      result;      /* Result code of the operation */
  T_SOCK_SOCKET      socket;      /* Socket for which the event occurred */
  T_SOCK_SOCKET      new_socket;  /* New socket allocated for the connection. */
  T_SOCK_IPADDR      peer_ipaddr; /* IP address of the remote peer. */
  T_SOCK_PORT        peer_port;   /* Port number on the remote side. */
} T_SOCK_CONNECT_IND;

typedef T_SOCK_EVENTSTRUCT      T_SOCK_CONN_CLOSED_IND;
typedef T_SOCK_EVENTSTRUCT      T_SOCK_ERROR_IND;
typedef T_SOCK_EVENTSTRUCT      T_SOCK_FLOW_READY_IND;



/* ========================================================================== */
/* ================== Prototypes of socket API ============================== */


/* ******************* API administrative functions ************************* */

/*------------------------------------------------------------------------------
   Function     : sock_api_initialize
   Parameter    : - T_SOCK_API_INSTANCE * :
                    'The function returns an API instance value. The value is needed
                     for several API functions.'
                  - T_HANDLE :
                    'Application task handle as passed to pei_init()'
                  - char* :
                    'Name of the application entity as used with vsi_c_open().'
   Return       : The function returns TRUE if the initialization was successful.
   Description  : Initializes the socket interface API.
------------------------------------------------------------------------------*/
BOOL sock_api_initialize(T_SOCK_API_INSTANCE *api_instance, 
                         T_HANDLE app_handle,
                         char* app_name);


/*------------------------------------------------------------------------------
   Function     : sock_api_deinitialize
   Parameter    : - T_SOCK_API_INSTANCE :
                    'API instance value.'
   Return       : None
   Description  : Deinitializes the socket interface API. The function releases 
                  all associated memory.
------------------------------------------------------------------------------*/
void sock_api_deinitialize(T_SOCK_API_INSTANCE api_instance);


/*------------------------------------------------------------------------------
   Function     : sock_api_handles_primitive
   Parameter    : - T_SOCK_API_INSTANCE: API instance value
                  - T_PRIM:              Pointer to primitive received from 
                                         the primitive queue'
   Return       : The function returns TRUE if the primitive has been handled by 
                  this function.In this case the application should not do 
                  anything else with the primitive and should not call PFREE()
                  to free the memory block used for the primitive.
                  The function returns FALSE if the primitive has not been 
                  handled by this function. In this case the application should 
                  process the primitive as usual. 
   Description  : Handles primitives for the socket API.
                  To free the application from the handling of the event 
                  primitives sent by the TCP/IP entity, the Socket API provides
                  this function that checks if a primitive is to be handled by 
                  the Socket API and if it is, handles it. The application is 
                  supposed to call it immediately after receiving a primitive.
                  If the primitive is meant for the Socket API, it is handled by
                  this function. This will in most cases include calling the 
                  callback function supplied by the application to deliver an 
                  event. If the primitive is not meant for the Socket API,
                  no action is taken.
                  It is recommended to call this function early in the 
                  application entity's pei_primitive() function.
------------------------------------------------------------------------------*/
BOOL sock_api_handles_primitive(T_SOCK_API_INSTANCE api_instance, 
                                T_PRIM *prim);


/* ******************* Bearer related functions ***************************** */

/*------------------------------------------------------------------------------
   Function     : sock_open_bearer()
   Parameter    : - T_SOCK_API_INSTANCE: API instance value
                  - T_SOCK_BEARER_TYPE :  CSD or GPRS
                  - int:                  Number of the selected profile with a bearer 
                                          selection of SOCK_BEARER_USE_PROFILE.
                                          Unused in other cases.
                  - T_SOCK_BEARER_INFO:   requested parameters of the bearer connection
                  - T_SOCK_CALLBACK:      callback function to be called for return events.
                  - void*:                An arbitrary pointer to be passed to the 
                                          callback function when it is called
   Return       : T_SOCK_RESULT indicates successor a problem that happend
   Return Event : T_SOCK_OPEN_BEARER_CNF
   Description  : Opens a CSD or GPRS connection for use with TCP/IP.
                  This function a bearer connection for use with TCP/IP. It must be 
                  called after sock_api_initialize() and before any other 
                  TCP/IP-related functions.
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_open_bearer(T_SOCK_API_INSTANCE api_instance,
                               T_SOCK_BEARER_TYPE bearer_select,
                               int profile_number,
                               T_SOCK_BEARER_INFO *params,
                               T_SOCK_CALLBACK sock_cb,
                               void *context);


/*------------------------------------------------------------------------------
   Function     : sock_close_bearer()
   Parameter    : - T_SOCK_API_INSTANCE : API instance value
                  - T_SOCK_BEARER_HANDLE: returned by SOCK_OPEN_BEARER_CNF
                  - T_SOCK_CALLBACK:      Callback function to be called for return events.
                  - void*:                An arbitrary pointer to be passed to the 
                                          callback function when it is called
   Return       : T_SOCK_RESULT indicates successor a problem that happend
   Return Event : T_SOCK_CLOSE_BEARER_CNF
   Description  : Close a bearer connection that has been opened with sock_open_bearer().
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_close_bearer(T_SOCK_API_INSTANCE api_instance,
                                T_SOCK_BEARER_HANDLE bearer_handle,
                                T_SOCK_CALLBACK sock_cb,
                                void *context);


/*------------------------------------------------------------------------------
   Function     : sock_bearer_info()
   Parameter    : - T_SOCK_API_INSTANCE:  API instance value
                  - T_SOCK_BEARER_HANDLE: returned by SOCK_OPEN_BEARER_CNF
                  - T_SOCK_CALLBACK:      Callback function to be called for 
                                          return events.
                  - void*:                An arbitrary pointer to be passed to the 
                                          callback function when it is called
   Return       : T_SOCK_RESULT
   Return Event : T_SOCK_BEARER_INFO_CNF
   Description  : Get information about a bearer connection that has been opened 
                  with sock_open_bearer().
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_bearer_info(T_SOCK_API_INSTANCE api_instance,
                               T_SOCK_BEARER_HANDLE bearer_handle,
                               T_SOCK_CALLBACK sock_cb,
                               void *context);


/* ******************* Socket related functions ***************************** */

/*------------------------------------------------------------------------------
   Function     : sock_create
   Parameter    : - T_SOCK_API_INSTANCE :
                    'API instance value.'
                  - T_SOCK_IPPROTO :
                      'The protocol (UDP or TCP) to be used with this socket'
                  - T_SOCK_CALLBACK :
                      'The callback function to be called for events on this socket'
                  - void * :
                      'An arbitrary pointer to be passed to 
                       the callback function when it is called'
   Return       : (T_SOCK_RESULT)
   Return Event : 'SOCK_CREATE_CNF'
                    - T_SOCK_RESULT : Result code
                    - T_SOCK_SOCKET : The socket descriptor returned by the TCP/IP entity
   Description  : - Create a new UDP or TCP socket
                  - This function creates a socket that can subsequently be used with 
                    the other Socket API functions
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_create(T_SOCK_API_INSTANCE api_instance,
                          T_SOCK_IPPROTO ipproto, 
                          T_SOCK_CALLBACK callback,
                          void *context);


/*------------------------------------------------------------------------------
   Function     : sock_close
   Parameter    :  - T_SOCK_SOCKET :
                      'The socket descriptor to be closed'
   Return       : (T_SOCK_RESULT)
   Return Event : 'SOCK_CLOSE_CNF'
                    - T_SOCK_RESULT : Result code
                    - T_SOCK_SOCKET : The socket descriptor to be  closed
   Description  : - Close socket, shutdown connection if present
                  - This function closes a socket that has previously 
                    been created with sock_create(). 
                    If a connection is open for this socket, it will be closed. 
                    If this socket has listened for connections, 
                    no further connections will be accepted
   History      : 0001    03.08.11    shkim    Created
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_close(T_SOCK_SOCKET socket);


/*------------------------------------------------------------------------------
   Function     : sock_bind
   Parameter    :  - T_SOCK_SOCKET :
                      'The socket descriptor to be closed'
                   - T_SOCK_PORT   :
                      'The port number to bind the socket to'
   Return       : (T_SOCK_RESULT)
   Return Event : 'SOCK_BIND_CNF'
                    - T_SOCK_RESULT : Result code
                    - T_SOCK_SOCKET : The socket descriptor to be bound
   Description  : - Bind socket to a specific local port number
                  - This function binds a socket to the specified local port
   History      : 0001    03.08.11    shkim    Created
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_bind(T_SOCK_SOCKET socket,
                        T_SOCK_PORT port);


/*------------------------------------------------------------------------------
   Function     : sock_listen
   Parameter    :  - T_SOCK_SOCKET :
                      'The socket descriptor to listen on'
   Return       : (T_SOCK_RESULT)
   Return Event : 'SOCK_LISTEN_CNF'
                    - T_SOCK_RESULT : Result code
                    - T_SOCK_SOCKET : The socket descriptor to listen on
   Description  : - Accept TCP connections on this socket
                  - This function makes TCP/IP listen for 
                    TCP connections on this socket. 
                    The socket should have been bound to a specific port 
                    using sock_bind() before.
   History      : 0001    03.08.11    shkim    Created
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_listen(T_SOCK_SOCKET socket);


/*------------------------------------------------------------------------------
   Function     : sock_connect
   Parameter    :  - T_SOCK_SOCKET :
                      'The socket descriptor to connect'
                   - T_SOCK_IPADDR :
                      'The IP address to connect to'
                   - T_SOCK_PORT   :
                      'The port number to connect to'
   Return       : (T_SOCK_RESULT)
   Return Event : 'SOCK_CONNECT_CNF'
                    - T_SOCK_RESULT : Result code
                    - T_SOCK_SOCKET : The socket descriptor to connect
   Description  : - Connect the socket to a remote endpoint
                  - With TCP sockets, a TCP connection is established to 
                      the specified IP address and the specified port. 
                      The connection can then be used to send data using sock_send(); 
                      received data is indicated by a SOCK_RECV_IND event.
                    With UDP sockets, the specified IP address and port number 
                      are stored with the socket; 
                      subsequent UDP messages can be sent to this address 
                      using sock_send(); 
                      only messages from this address will be received.
   History      : 0001    03.08.11    shkim    Created
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_connect(T_SOCK_SOCKET socket, 
                           T_SOCK_IPADDR ipaddr,
                           T_SOCK_PORT port);


/*------------------------------------------------------------------------------
   Function     : sock_getsockname
   Parameter    :  - T_SOCK_SOCKET :
                      'The socket descriptor to retrieve information about'
   Return       : (T_SOCK_RESULT)
   Return Event : 'SOCK_SOCKNAME_CNF'
                    - T_SOCK_RESULT : Result code
                    - T_SOCK_SOCKET : The socket descriptor to connect
                    - T_SOCK_IPADDR : The local IP address of the socket
                    - T_SOCK_PORT   : The local port number of the socket
   Description  : - Retrieve local address information
                  - The function retrieves local address information of the socket. 
                    If the socket has not yet been bound to an address using sock_bind(), 
                    the port number is unspecified (SOCK_PORT_ANY)
   History      : 0001    03.08.11    shkim    Created
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_getsockname(T_SOCK_SOCKET socket);


/*------------------------------------------------------------------------------
   Function     : sock_getpeername
   Parameter    :  - T_SOCK_SOCKET :
                      'The socket descriptor to retrieve information about'
   Return       : (T_SOCK_RESULT)
   Return Event : 'SOCK_PEERNAME_CNF'
                    - T_SOCK_RESULT : Result code
                    - T_SOCK_SOCKET : The socket descriptor to connect
                    - T_SOCK_IPADDR : The IP address of the remote peer
                    - T_SOCK_PORT   : The port number at the remote peer
   Description  : - Retrieve remote address information
                  - The function retrieves address information of 
                    the connection at the remote peer.
                    If the socket is not connected, 
                    the IP address and port number are unspecified
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_getpeername(T_SOCK_SOCKET socket);


/*------------------------------------------------------------------------------
   Function     : sock_gethostbyname
   Parameter    : - T_SOCK_API_INSTANCE :
                      'API instance value.'
                  - char * :
                      'The name of the referenced host'
                   - T_SOCK_CALLBACK :
                      'The callback function to be called for the result event'
                   - void * :
                      'An arbitrary pointer to be passed to the callback
                       function when it is called'
   Return       : (T_SOCK_RESULT)
   Return Event : 'SOCK_HOSTINFO_CNF'
                    - T_SOCK_RESULT : Result code
                    - char hostname[SOCK_MAXHOSTNAMELEN+1] : The name of the 
                      host as a zero-terminated string
                    - T_SOCK_IPADDR : The IP address of the host
   Description  : - Get the IP address of a host
                  - The function queries the IP address information of 
                    the specified host from the DNS.
                    Because the function is not associated to any socket, 
                    a callback function and a context 
                    pointer must be specified separately
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_gethostbyname(T_SOCK_API_INSTANCE api_instance, 
                                 char *hostname,
                                 T_SOCK_CALLBACK callback, 
                                 void *context);


/*------------------------------------------------------------------------------
   Function     : sock_gethostbyaddr
   Parameter    : - T_SOCK_API_INSTANCE :
                      'API instance value.'
                  - T_SOCK_IPADDR  :
                      'The IP address of the referenced host'
                   - T_SOCK_CALLBACK  :
                      'The callback function to be called for the result event'
                   - void * :
                      'An arbitrary pointer to be passed to the callback function 
                      when it is called'
   Return       : (T_SOCK_RESULT)
   Return Event : 'SOCK_HOSTINFO_CNF'
                    - T_SOCK_RESULT : Result code
                    - char hostname[SOCK_MAXHOSTNAMELEN+1] : The name of the 
                      host as a zero-terminated string
                    - T_SOCK_IPADDR : The IP address of the host
   Description  : - Get the name of a host
                  - The function queries the hostname for the specified 
                    IP address from the DNS.
                    Because the function is not associated to any socket, 
                    a callback function and a context pointer must be specified separately
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_gethostbyaddr(T_SOCK_API_INSTANCE api_instance,
                                 T_SOCK_IPADDR ipaddr,
                                 T_SOCK_CALLBACK callback,
                                 void *context);


/*------------------------------------------------------------------------------
   Function     : sock_send
   Parameter    :  - T_SOCK_SOCKET :
                      'The socket to send the data on'
                   - char * :
                      'The data buffer to be sent'
                   - U16 :
                      'The length of the data buffer in bytes'
   Return       : (T_SOCK_RESULT)
   Return Event : None
   Description  : - Send data on a socket ( TCP only )
                  - The function sends the specified data buffer over the socket. 
                    The socket must be connected, 
                    i. e. it must have been connected to a remote peer 
                    using sock_connect() or been created when accepting 
                    a connection as indicated by SOCK_SONNECT_IND.
                    Implementation note: In order to send the payload data via DTI, 
                        the data must be copied into a DTI descriptor by the Socket API; 
                        there is no way to avoid the copy operation without 
                        putting the burden of knowing DTI-internal data 
                        structures on the application. 
                        It has been decided to pay the cost of the copy operation 
                        in order to free the application from this responsibility
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_send(T_SOCK_SOCKET socket, 
                        char *buffer, 
                        U16 buffer_length);


/*------------------------------------------------------------------------------
   Function     : sock_sendto
   Parameter    :  - T_SOCK_SOCKET :
                      'The socket to send the data on'
                   - char * :
                      'The data buffer to be sent'
                   - U16 :
                      'The length of the data buffer'
                   - T_SOCK_IPADDR :
                      'IP address of the host to send data to'
                   - T_SOCK_PORT :
                      'Remote port to send data to'
   Return       : (T_SOCK_RESULT)
   Return Event : None
   Description  : - Send data on a socket( UDP only )
                  - The function sends the specified data buffer 
                    over the socket to the specified address. The socket must be
                    a UDP socket.
                    Implementation note: In order to send the payload data via DTI, 
                        the data must be copied into a DTI descriptor by the Socket API; 
                        there is no way to avoid the copy operation without putting 
                        the burden of knowing DTI-internal data structures on 
                        the application. It has been decided to pay the cost of 
                        the copy operation in order to free the application from 
                        this responsibility
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_sendto(T_SOCK_SOCKET socket, 
                          char *buffer, 
                          U16 buffer_length, 
                          T_SOCK_IPADDR ipaddr, 
                          T_SOCK_PORT port);


/*------------------------------------------------------------------------------------
   Function     : sock_set_callback
   Parameter    : - T_SOCK_SOCKET :
                      'Socket to set callback and context for'
                  - T_SOCK_CALLBACK :
                      'New callback function for the socket'
                  - void * :
                      'New context pointer for the socket'
   Return       : (T_SOCK_RESULT)
   Return Event : None
   Description  : - Set a new callback function and context pointer for the socket
                  - The function defines a new callback function and a new context
                    pointer for the socket. All socket events after this call will be
                    delivered using the new callback function and the new context
                    pointer
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_set_callback(T_SOCK_SOCKET socket,
                                T_SOCK_CALLBACK callback, 
                                void *context);


/*------------------------------------------------------------------------------
   Function     : sock_get_callback
   Parameter    : - T_SOCK_SOCKET :
                      'Socket to get callback and context from'
                  - T_SOCK_CALLBACK * :
                      'Return callback function pointer for the socket'
                  - void ** :
                      'Return context pointer for the socket'
   Return       : (T_SOCK_RESULT)
   Return Event : None
   Description  : - Get callback function pointer and context pointer for the socket
                  - The function returns callback function pointer and context pointer
                    for the socket.
                    pointer
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_get_callback(T_SOCK_SOCKET socket,
                                T_SOCK_CALLBACK *callback_p, 
                                void **context_p);


/*------------------------------------------------------------------------------
   Function     : sock_flow_xoff
   Parameter    :  - T_SOCK_SOCKET :
                      'Socket to switch to "xoff" status'
   Return       : (T_SOCK_RESULT)
   Return Event : None
   Description  : - Flow control: make TCP/IP stop sending data
                  - This function makes the Socket API stop TCP/IP sending data.
                    If TCP/IP has already been stopped, the function has no effect.
   History      : 0001    03.08.11    shkim    Created
                  0002    03.09.12    STW      T_SOCK_RESULT added
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_flow_xoff(T_SOCK_SOCKET socket);


/*------------------------------------------------------------------------------
   Function     : sock_flow_xon
   Parameter    :  - T_SOCK_SOCKET :
                      'Socket to switch to "xon" status'
   Return       : (T_SOCK_RESULT)
   Return Event : None
   Description  : - Flow control: make TCP/IP resume sending data
                  - This function makes TCP/IP resume sending data.
                    If TCP/IP has not been stopped, the function has no effect
   History      : 0001    03.08.11    shkim    Created
                  0002    03.09.12    STW      T_SOCK_RESULT added
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_flow_xon(T_SOCK_SOCKET socket);


/*------------------------------------------------------------------------------
   Function     : sock_get_mtu_size
   Parameter    :  - T_SOCK_SOCKET :
                      'Socket to get MTU size from'
   Return       : (T_SOCK_RESULT)
   Return Event : 'SOCK_MTU_SIZE_CNF'
                    - T_SOCK_RESULT : Result code
                    - T_SOCK_SOCKET : The socket descriptor (unused).
                    - U16           : MTU size
   Description  : - Get MTU size of network connection
                  - The function retrieves the size of 
                    the Maximum Transfer Unit(MTU) of the network connection.
   History      : 0001    03.08.11    shkim    Created
                  0002    03.09.12    STW      T_SOCK_SOCKET added
------------------------------------------------------------------------------*/
T_SOCK_RESULT sock_get_mtu_size(T_SOCK_SOCKET socket);


#endif  /* __SOCKET_H__ */