GIVE W INGS TO YOUR IDEAS

Transcription

1 GIVE W INGS TO YOUR IDEAS Using TCP and UDP under Open-AT Revision: 001 Date: June 2003 PLUG IN TO THE WIRELESS WORLD

2 Author: Wavecom Support Consultant Date: 23 th June 2005 APN Content Level BASIC INTERMEDIATE ADVANCED Confidentiality Public Private Software Firmware 650a Open AT TM Compiler V3.01 edlib V3.0 Compatibility* Used * refer to software compatibility matrix section for more detail Modems: M1206B M1306B M2106B Hardware Quik (CDMA): Q2358C Q2438F Q2438R Compatibility Quik (GSM): Q2400A Q2403A Q2406A Q2406B Q2501B ADS Reference Hardware No GCC Reference Software Yes 1 INTRODUCTION This document describes the usage of TCP and UDP sockets using API s provided by the IP Connectivity library (also named edlib) in Open AT TM development environment. Applications samples given at the end of the document describes the steps to be followed to open a TCP/UDP connection, manipulate the connection to send/receive data and close the connection. Some of remarks which might help during development have also been described in this document. This document assumes that the user has knowledge establishing a session to GPRS/GSM network using edlib APIs. The user can refer Open AT TM Development Guide for IP connectivity in case more information is needed regarding edlib APIs and return codes. 2 APPLICATION DESCRIPTION edlib provides API s using which Open AT TM developers can have direct access to internet protocols like TCP, UDP, SMTP, FTP and POP3 with convenient and efficient ways to open and manipulate TCP and UDP sockets. These sockets can either be opened in client mode (TCP/UDP client) or server mode (TCP/UDP server). edlib provides various APIs in order to manage these TCP/UDP sockets. Important Note: All edlib APIs are only compatible with ADL mode of application development and should not be used with standard mode of application development. It is recommended to use edlib in Open AT TM application written in ADL mode. 2.1 Synopsis of Various Operations performed. There are several operations which have to be performed for a successful TCP/UDP socket connection. These operations are briefly described as under. Please note that the first six steps (i vi) are common for both client and server sockets (TCP/UDP). i. Call ed_init () API from adl_main (program entry point). ii. Wait for +WIND: 4 indication. iii. Perform GPRS attach operation. This can be done by issuing AT+CGATT=1 command using adl_atcmdcreate () API. Please note that this step is not required if the GSM data call is used to make TCP/UDP connection. In case, GPRS services are used to make TCP/UDP connection, only then GPRS attach should be performed. iv. Set the GPRS parameters using ed_gprssetconfig () API. These parameters include the Access Point Name (APN) string, APN username, APN password. ed_gprssetconfig () API is also used to set a mode parameter. This parameter indicates to edlib whether GSM data call or GPRS connection should be used for the TCP/UDP socket. Hence, ed_gprssetconfig () API has to be called irrespective of the fact whether GSM data call or GPRS connection is used for TCP/UDP socket. v. If GSM data call is used to establish a connection, then GSM call parameters have to be set too. This is done using DialupSetConfig () API. Please note this step should be performed only when GSM data call is used for TCP/UDP sockets. This step is not required if GPRS connection is used for TCP/UDP sockets. vi. Call ed_dialupconnectionstart () API. Depending upon the mode parameter (which is set using ed_gprssetconfig () API), GSM data call or GPRS connection will be made. If the connection is successful, an IP address will be received by the module. vii. If TCP socket has to be established, then set the TCP client/server parameters using ed_socketsetconfig () API. If UDP socket has to be established, then setup the UDP client/server parameters using ed_udpsocketsetconfig () API. viii. To use TCP client/server socket, call ed_sockettcpstart () API. To start a UDP client/server socket, call ed_socketudpstart () API. ix. The Response Handler function for TCP/UDP sockets (specified in the ed_sockettcpstart () or ed_socketudpstart ()) will indicate various events related to socket services (like successful socket connection, or failure to connect to server TCP)). x. The data handler function for TCP/UDP sockets (specified in the ed_sockettcpstart () or ed_socketudpstart ()) will be invoked whenever data is received from the peer TCP/UDP socket. xi. The data request handler function for TCP/UDP socket (specified in the ed_sockettcpstart () or ed_socketudpstart ()) will be invoked to indicate that the socket can now send data. The MaxLen parameter of data request handler will indicate the maximum length of data can be sent at this time. xii. In case of TCP sockets, data should be sent (to the peer TCP socket) using ed_senddataext () API. In case of UDP sockets, data should be sent (to the peer UDP socket) using ed_senddata () API. These APIs (ed_senddataext () and ed_senddata () should be used to close active TCP and UDP client/server sockets). It should be noted that a listening TCP server socket should be closed with ed_socketltcpstop () API and a listening UDP server socket should be closed with ed_socketludpstop () API. The sections below describe the details of various operations required for successful TCP/UDP connection establishment along with the precautions which must be taken for proper operation. 2.2 Preliminary Tasks before Opening a TCP/UDP socket. Before Opening a TCP/UDP socket, some tasks like attaching to GPRS network or connecting to GSM service provider (in case dialup connection is used) must be performed. These basic tasks allow the module to use the services offered by the network to use TCP/UDP sockets. edlib provide full set of APIs to allow application to do these preliminary tasks. The following section describes most used APIs to perform these tasks Starting up edlib Before using any APIs, edlib must initialise its own data structures and run some initialisation routines (like subscribing to different flows internally to send and receive data, loading IP connectivity parameters from EEPROM etc). This is done using ed_init 2004 All rights reserved Page: 1 / 11

3 function. This API must be called before calling any other edlib API. This API has the following prototype: s8 ed_init (void); None. 0 is returned on Success. activated in the WISMO product. ED_ERR_TCPIP_ALREADY_USED is returned if another application is already using IP connectivity library. ED_ERR_WM_UNABLE_SUBS_EVENT is returned if edlib failed to internally subscribe for commands, timers or unsolicited messages. ED_ERR_PARAM_READ_E2P is returned if Parameter reading from E2P failed. ed_init () must be called from adl_main () for proper operation. In case, the application wants to initialise PIN code using adl_simsubscribe () API, ed_init must be called after calling adl_simsubscribe () API WIND: 4 Indication and Configuration Modes TCP/UDP sockets use the data services provided by the network provider to exchange data and hence, establishing a connection to network service provider is important. Whenever SIM is inserted into the module, connection tried to be established with the service provider and it takes some time to initialise the SIM and register to the network. +WIND: 4 indication should be used to indicate complete network registration confirmation. Application can subscribe for +WIND: 4 indication (using adl_atunsosubscribe () API) to confirm complete network registration and then initiate the related TCP/UDP client/server operations. After receiving a +WIND: 4 indication, the application can start TCP/UDP socket using either GSM data call or GPRS connection. Initial settings need to be setup for GSM data call and/or GPRS connection prior to starting TCP/UDP connection. The GSM data call and GPRS connection which are used to transport TCP/UDP data are called mode for TCP/UDP sockets. The application can either use GSM data call mode or GPRS connection mode for TCP/UDP services How does Modem know which mode to use? It is very important to provide the information regarding the mode (GSM data call or GPRS connection) used for TCP/UDP socket connection. This information can be provided using ed_gprssetconfig (). This API is used to provide GPRS settings related information and the mode to be used for TCP/UDP connection to the module. ed_gprssetconfig () API requires an instance of ed_gprssetupparams_t structure as its argument. The members of ed_gprssetupparams_t structure include: Cid: This parameter represents the context id which has to be activated if a GPRS connection is made. Mode: This parameter indicates whether GSM data call or GPRS connection is used to provide data transport services for TCP/UDP sockets. The values which this parameter can take along with their meanings are: Mode Meaning 0 If this parameter is set to 0, it indicates that GSM data call should be used for providing data transport facility to the TCP/UDP client/server. In this case, the application should also set the dialup parameters using ed_dialupsetconfig () API. 1 If mode is set to 1, then GPRS connection is used to provide data transport facility to TCP/UDP client/server. In this case, only GPRS parameters become significant and there is no need to set the dialup parameters. ApnServ: This parameter represents the APN server name. ApnUn: This parameter represents the APN user name. ApnPw: This parameter represents the APN password. Note that APN is the acronym for Access Point Name Using GPRS Service for TCP/UDP sockets If the application is using GPRS connection for TCP/UDP sockets, it should first attach to the GPRS network. This can be done by using AT+CGATT=1 command. This command can be issued to the core software using adl_atcmdcreate () API. After the GPRS network is successfully attached, various GPRS parameters should be set. These parameters include the ApnServ, ApnUn, ApnPw, Cid and Mode. These parameters are available as members of ed_gprssetupparams_t structure. For GPRS connection, the Mode parameter should be set to 1. ApnServ, ApnUn and ApnPw parameters are dependent of the network service provider. ed_gprssetconfig () API can be used to configure the GPRS parameters for use in the TCP/UDP socket. This API requires an instance of ed_gprssetupparams_t structure (which contains the GPRS parameters like ApnServ, ApnUn and ApnPw). Now ed_dialupconnectionstart () API can be called to establish an IP connection and receive an IP address Using GSM Data Call for TCP/UDP sockets. If the application wants to use GSM data call for TCP/UDP socket then it should be indicated by setting Mode parameter of ed_gprssetupparams_t structure to 0. This parameter should be set using ed_gprssetconfig () API. However, there is no need to set other parameters of ed_gprssetupparams_t (excluding mode) as they will not be used here. After setting mode parameter using ed_gprssetconfig () API, GSM dialup parameters should be set. These parameters are members of ed_dialupsetupparams_t structure as follows : DialN1: This is the primary dialup phone number to connect with the local ISP. This is a string type parameter and can have a maximum length of 64 (excluding the terminating NULL character). DialN2: This is the secondary dialup phone number to connect with the local ISP. It s data type and maximum length is same as the DialN1 parameter. DialSelect: This parameter determine whether primary dialup phone number (DialN1) or secondary dialup phone number (DialN2) is used to establish a connection. IspUn: This is the user name of the ISP account in ASCII text string and can be up to 64 characters in length. By default, it is set to empty string All rights reserved Page: 2 / 11

4 IspPw: This is the password for the ISP account in ASCII text string and can be up to 64 characters in length. By default, it is also set to empty string. RedialCount: This parameter indicates how many unsuccessful connections (between 0 and 14 inclusive) attempts will be tried by the TCP/IP stack software before terminating the connection attempts. If the value is set to 0, the TCP/IP stack software will not make any call retry. This parameter is by default set to 5. RedialDelay: This parameter controls elapsed idle time (in seconds between 5 and 14 inclusive), if any, it will take between each call retry. PhyTimeout: This parameter is used by TCP/IP stack software in order to terminate connections to telephone line without activity. This period represents time in minutes between 1 and 255 and by default it is set to 15. Then ed_dialupsetconfig () API can be used to set these parameters for GSM data connection. This API expects an instance of ed_dialupsetupparams_t as its argument. Now ed_dialupconnectionstart () API can be used to establish an IP connection and receive an IP address from the network. The whole procedure (starting from +WIND: 4 wait to ed_dialupconnectionstart () is briefly described as under): 1. Attach to GPRS using AT+CGATT=1 command. (This operation can be done even before receiving +WIND :4 indication). However, if GSM is used to connect to the service provider, there is no need to perform this step. 2. Set up GPRS parameters (like ApnServ, ApnUn, mode, cid, etc) using ed_gprssetconfig () API. The mode parameter should be set to 0 if GSM data call is used to provide data transport to the TCP/UDP sockets. If GPRS is used to provide data transport to the TCP/UDP socket, the mode parameter should be set to 1. For GSM data connection, GSM parameters (DialSelect, DialN1 etc) should also be set using ed_dialupsetconfig () API. 3. Starting the connection using ed_dialupconnectionstart () API. ed_dialupconnectionstart () function will establish the connection depending on the mode parameter of ed_gprssetupparams_t. Even if the application is using GPRS to provide edlib services, it should wait for +WIND: 4 indication before calling ed_dialupconnectionstart () API. In case, this is not done, ED_ERR_WM_GPRS_OPEN (error code -28) is received by the response callback function of ed_dialupconnectionstart () API (ed_responsecbk_f). When GPRS is used to connect to ISP, ed_dialupconnectionstart () function should not be called immediately after receiving response for AT+CGATT command (i.e. connecting to GPRS). Some delay should be provided (using a timer) between calling ed_dialupconnectionstart () and receiving response in the command handler of AT+CGATT=1 command ( AT+CGATT=1 command can be sent to the core software using adl_atcmdcreate () API). When GSM is used to connect to ISP and provide edlib services, there is no need to connect to GPRS using AT+CGATT=1. In this case, the application should simply wait for +WIND: 4 indication, setup the dialup parameters (using ed_dialupsetconfig () API) and GPRS parameters (to set mode parameter using ed_gprssetconfig () API) and call ed_dialupconnectionstart () API. 2.3 TCP Sockets Required header file: ed_socket.h edlib provides TCP services which allow an application to open TCP client or TCP server sockets. When a TCP socket is opened in a server mode, it listens on the specified port for any connection request from a client. In case a connection request is received, data can be exchanged between the client and the TCP server Setting up TCP Socket Parameters Before starting TCP connection, parameters for the TCP socket should be set. These parameters are members of ed_socketsetupparams_t structure. Members of ed_socketsetupparams_t structure include: TcpPort: This parameter holds the peer TCP port if a client TCP socket is opened. OR If a server TCP socket is opened, then this parameter indicates the port on which the TCP server will listen for incoming connections. Default Value: 0 Type: u16 Range: 1 to TcpTxDelay: This parameter holds delay after which the socket will flush the characters to transmit to the remote entity. EDLib usually buffers the characters until it s transmit buffer is full or the TcpTxDelay time expires. Default Value: 100ms Type: u16 TcpServ: If a client TCP socket is opened: This parameter will hold the TCP server IP address to connect to. OR If a server TCP socket is opened: This parameter indicates the IP filtering which has to be done. A value of indicates no IP filtering. Default Value: Empty string ( ). Type: Array of ascii data type. A value of for TcpServ parameter in invalid for both client and server TCP socket. A TCP client socket cannot specify a value of as TcpServ parameter. (This is because, no server can have as its IP address). However, this value should be specified for a TCP server socket if no IP filtering is performed. After setting values in the members of ed_socketsetupparams_t structure, ed_socketsetconfig API should be used to set these values for the TCP socket. This API has the following prototype: s8 ed_socketsetconfig (TeDHandle id, ed_socketsetupparams_t * Params); id: This parameter specifies the socket id for which the parameters are to be set. It can have one of the following values: ED_ID_TCPSOCKET_1 ED_ID_TCPSOCKET_2 ED_ID_TCPSOCKET_3 ED_ID_TCPSOCKET_4 ED_ID_TCPSOCKET_5 ED_ID_TCPSOCKET_6 ED_ID_TCPSOCKET_ All rights reserved Page: 3 / 11

5 ED_ID_TCPSOCKET_8 ED_ID_TCPSOCKET_9 ED_ID_TCPSOCKET_10 Params: Structure containing the parameters to setup (of type ed_socketsetupparams_t). 0 is returned on success. activated in the WISMO product. ED_ERR_NOT_INIT is returned if the function cannot be used as ed_init () API is not called prior to calling ed_socketsetconfig API. ED_ERR_INVALID_ARG is returned if an argument is invalid or contains a NULL pointer. ED_ERR_PARAM_BAD_VALUE is returned if a parameter value is invalid. ED_ERR_PARAM_TOO_LONG is returned if a parameter string is too long. ED_ERR_PARAM_WRITE_E2P is returned if writing a parameter to E2P failed. ED_ERR_INVALID_ID is returned if the parameter id is invalid. ED_ERR_SERVICE_ALREADY_RUNNING is returned if the associated TCP service is already running and it is not possible to set the parameters. Important Note: The parameter TeDHandle id is provided only in IP library for Open AT TM version 3.xx. It is not available in Open AT TM version 2.xx. The edlib APIs for Open AT TM version 3.xx and version 2.xx differs because of this additional parameter only Starting up TCP Client/Server Socket. After setting parameters for the TCP socket, a client or a server TCP socket can be opened. A client TCP socket will try to establish a TCP connection with the TCP server specified in the TcpServ parameter of ed_socketsetupparams_t structure. A server TCP socket, on the other hand, will passively listen for any TCP connection destined for it. It must be noted that in case of a server TCP socket, connection will become active only after client connect to it on the correct port. Otherwise, the server socket will listen for any incoming connection requests on the specified port. In order to open a client or a server TCP connection the following API should be used. s8 ed_sockettcpstart (TeDHandle id, u8 Listen, ed_responsecbk_f pfresponsecbk, ed_datahandler_f pfdatahnd, ed_datarequest_f pfdatarequest); id: This parameter specifies the socket id. It can have one of the following values: o ED_ID_TCPSOCKET_1 o ED_ID_TCPSOCKET_2 o ED_ID_TCPSOCKET_3 o ED_ID_TCPSOCKET_4 o ED_ID_TCPSOCKET_5 o ED_ID_TCPSOCKET_6 o ED_ID_TCPSOCKET_7 o ED_ID_TCPSOCKET_8 o ED_ID_TCPSOCKET_9 o ED_ID_TCPSOCKET_10 Listen: This parameter determines whether a client or a server TCP socket is to be opened with parameter set to 1 for TCP socket server and 0 for TCP socket client. As a server TCP socket listens for any incoming connections whereas a client TCP socket attempts to connect to the server TCP socket. pfresponsecbk: This parameter is the callback function which is called on any event related to TCP connection. All the events related to TCP sockets (like successful opening of TCP socket, closing of TCP socket, occurrence of some error) lead to execution of this function. This callback function has the following prototype : typedef void (*ed_responsecbk_f) (s32 ResponseCode, TeDHandle id) ; ResponseCode : This parameter will contain the actual TCP socket event which has occurred. This parameter can have the following values (and consequently following TCP socket events): ED_INFO_LISTEN_SET: This event indicates that the listening TCP socket has been successfully created and now it is waiting for any remote entity (TCP client) to connect to it. This event is relevant only for a TCP server socket. ED TCP_CLOSED: This event indicates the TCP server/client socket has been successfully closed. ED_INFO_WAITING_FOR_DATA: This event indicates that IP library is waiting for data to be sent to it. This event occurs when a TCP client socket successfully establishes a TCP connection with the TCP server socket. If this event occurs on a TCP server socket, it indicates that some client socket has successfully made connection with it and the connection is now active. It indicates that data can now be send to the TCP server socket from the client socket or vice versa. ED_ERR_DISTANT_DNS: This error indicates that the Remote server name has not been mapped by DNS. TCP/IP stack is not able to reach the primary and secondary DNS servers or a wrong server address has been filled in. ED_ERR_DISTANT_OPEN: This error indicates that some error has occurred during IP connectivity library application session opening. ED_ERR_STACK_INTERNAL: This error indicates some internal IP stack error. ED_ERR_LISTEN_STOP: This event indicates that the listening TCP socket has been cancelled. This event is received when ed_socketltcpstop function is used to stop the listening TCP server socket. ED_ERR_DISTANT_NO_RESP: In case, a client TCP socket is opened, this event indicates that the distant TCP server did not responded despite of repeated attempts. ED_ERR_DISTANT_SEND: This event indicates that the data sending attempt from the TCP socket failed. ED_ERR_DISTANT_CLOSE: This event indicates error during IP library application closing. ED_ERR_DISTANT_TCP_CLOSED: This event indicates that the TCP session is closed by the IP connectivity library (edlib) All rights reserved Page: 4 / 11

6 ED_ERR_DISTANT_TCP_CLOSED_BY_PEER: This event indicates that the TCP session is closed by the remote TCP peer. ED_ERR_NETWORK_KO: This event indicates that the WISMO module is not connected to the network when an attempt was made to open a TCP socket. ED_ERR_GPRS_SESSION_LOST: This event indicates that the GPRS session has lost activation. This event occurs when GPRS connection is lost with a TCP socket opened in client or server mode. ED_ERR_LISTEN_STOP event is received when a listening TCP socket is closed using ed_socketltcpstop API. Once the listening server socket has made a connection with a client TCP socket, it becomes active and ed_socketltcpstop API cannot be used to close this socket. Only listening TCP server sockets can be closed with ed_socketltcpstop API. When a listening socket is closed, first ED TCP_CLOSED event will be received and after that ED_ERR_LISTEN_STOP event will be received. In case GSM network is used to establish connection with service provider (instead of GPRS), then due care should be given to the Physical Timeout parameter (PhyTimeout) of ed_dialupsetupparams_t structure. This is because, if the period of inactivity reaches up to the time specified in the PhyTimeout parameter, the GSM data call will be released (Physical connection will be released) and the TCP client/server socket will be closed. In this case ED_ERR_NETWORK_KO event will be received in the TCP Event Handler function. In case GPRS is used to establish connection with service provider, there is no Physical Timeout value. pfdatahnd: This function is called by edlib whenever data is received by the library from peer entity. This callback function has the following prototype : typedef u16 (*ed_datahandler_f) (u16 DataLen, u8* Data, TeDHandle id); DataLen: This parameter indicates the number of bytes (u8) received by the IP library. Data: This is a pointer to the actual data received by edlib. id: Specifies the socket id. Please refer section (2.3.2) for the values which can be assigned to this parameter. Return Value: The return value of this callback function indicates the number of bytes (u8) which are processed by the application. The application should return the number of bytes which has successfully processed. The data left will be handed over at the next call to this function, maybe with new data. pfdatarequest: This is the callback function which is called by IP library (edlib) to inform the application new data can be sent. Whenever a TCP client socket is opened, this function is called. Inside this function, data can be sent to the TCP server socket. This function has the following prototype : typedef void (* ed_datarequest_f) (u16 MaxLen, TeDHandle id) ; MaxLen: This parameter indicates the maximum number of bytes which can be sent by the application during this call to the function. id: This parameter specifies the socket id. Please refer section (2.3.2) for the values which can be assigned to this parameter. Return Value (of pfdatarequest callback function): None. ed_datarequest_f callback function is automatically called when a client TCP socket establishes a connection with a server TCP socket. In other words, in case of client TCP socket, this callback function is called immediately after receiving ED_INFO_WAITING_FOR_DATA event in the pfresponsecbk function. In case of TCP server socket, this function (ed_datarequest_f) is called when a client gets connected to it. Data send operation (using ed_senddataext () API) should be preferable performed in this function because, if data is sent without receiving a call to pfdatarequest API, error code -51 (ED_ERR_INVALID_CALL) will occur. Return Values (of ed_sockettcpstart () API): 0 is returned on success. ED_ERR_NO_TCPIP is returned if TCP/IP feature is not enabled on the product. ED_ERR_NOT_INIT is returned if ed_init () has not already been called. ED_ERR_INVALID_ARG is returned if an argument is invalid or NULL. ED_ERR_STACK_BAD_CONFIG is returned if IP connectivity library has incorrect configuration. ED_ERR_PHY_NOT_ACTIVATED is returned if IP connectivity library physical connection is not activated. This event occurs when physical connection (GPRS connection or GSM call) is not active at the time of data transfer. ED_ERR_STACK_BUSY is returned if another IP connectivity library application is already running. ED_ERR_INVALID_ID is returned if the id parameter is invalid. ED_ERR_MEMALLOC_FAILED is returned if there is not enough memory left to run the new socket. ED_ERR_SOCKET_CREATION_BUSY is returned if an attempt is made to open more than two sockets at the same time Sending Data and/or Closing TCP client/server socket. To send data and/or close the opened TCP client/server socket, ed_senddataext API should be used. This API is made explicitly for TCP socket services. This API should preferably be called from pfdatarequest callback function (This API can also be called outside pfdatarequest API, but there must be a call to pfdatarequest function before this API call). s8 ed_senddataext (u8 * Data, u16 DataLen, bool bend, TeDHandle id) ; 2004 All rights reserved Page: 5 / 11

7 Data: This parameter is the pointer to the data which has to be sent to the peer TCP entity. DataLen: This parameter is the length of data which is to be sent to the peer TCP entity. bend: This Boolean parameter specifies whether the block of data to be sent is the last one or not. bend = TRUE indicates that the current block is the last block of data to be sent and the TCP socket will be closed after sending this block. This is the ideal way to close any TCP client or server socket. bend = FALSE indicates that the current block being sent is not the last block of data. In this case, edlib will call pfdatarequest () API again. id: This parameter specifies the socket id which is sending the data. Please refer section (2.3.2) for the values which can be assigned to this parameter. A 0 is returned on success. ED_ERR_NO_TCPIP is returned if TCP/IP service is not supported by the product. ED_ERR_NOT_INIT is returned if ed_init () API has not been called yet. ED_ERR_INVALID_ARG is returned if Data parameter points to NULL value. ED_ERR_INVALID_CALL is returned if the API cannot be invoked now. This might happen if application calls this API without receiving ed_datarequest_f () function. This error can also arise if no edlib service is currently active. ED_ERR_INVALID_SIZE is returned if DataLen parameter is greater than expected. ED_ERR_INVALID_ID is returned if the id parameter is invalid. ED_ERR_ID_INACTIVE is returned if the service represented by the id is inactive. ed_senddataext () API should preferably be called inside ed_datarequest_f () callback function. ed_senddataext () API must not be called before receiving call to ed_datarequest_f () function. When ed_senddataext () function is called, the MaxLen parameter of ed_datarequest_f () function must be taken into account. (This parameter indicates the maximum size of block in bytes which can be sent now). The data block sent using ed_senddataext () function must have a size less than or equal to the MaxLen parameter of ed_datarequest_f () callback. The bend parameter should be set to TRUE to send the last block of data and to close the TCP client/ server socket. If it is set to FALSE, then edlib will call pfdatarequest () API again. ed_senddata () API can also be used to send data. But it can be used to send data and close connection for TCP server socket only. As ed_senddataext () is made explicitly for TCP sockets, it is recommended to use ed_senddataext () to send data and close the socket for both TCP client and TCP server sockets To close a listening TCP Server socket. A listening socket is listening for some incoming connection and has not received any connection request yet. In order to close a listening TCP server socket the following API should be used: s8 ed_socketltcpstop (TeDHandle id, ed_responsecbk_f pfresponsecbk); id: This parameter specifies the socket id which is sending the data. Please refer section (2.3.2) for the values which can be assigned to this parameter. pfresponsecbk: This is the callback function which is called by IP library to indicate various socket related events (like socket close, or some error condition). For more information on this callback, please refer section is returned on success. enabled on the product. ED_ERR_NOT_INIT is returned if ed_init () API is not called prior to calling ed_socketltcpstop () API. ED_ERR_INVALID_ARG is returned if one of the arguments is invalid or has NULL value. ED_ERR_NO_LISTEN is returned if ed_socketltcpstop () is called when no socket is opened in listening mode. ED_ERR_INVALID_ID is returned if the socket id is not correct. Once a listening socket makes a connection with a client, it becomes active and cannot be closed by ed_socketltcpstop () API. To stop the active socket, use ed_senddataext () (section2.3.3). 2.4 UDP Sockets Required Header file: ed_udpsocket.h edlib provides UDP socket services, which like TCP socket services, allow an application to send and receive UDP packets (called UDP datagrams). The difference between TCP and UDP is that, UDP is a connectionless protocol whereas TCP is connection oriented protocol. TCP provides reliable delivery of packets whereas UDP does not. In UDP, a packet (datagram) can be transmitted without establishing a connection with the peer (i.e. a client can send a datagram without establishing a connection with UDP server) Setting up UDP socket parameters. Before starting up a UDP client/server socket, some parameters have to be set, which determine the operation of UDP sockets. These parameters are in the ed_udpsocketsetupparams_t structure. Members of this structure include: UdpPort: If a UDP client socket is opened:- This parameter holds the peer UDP port used (Server UDP port) OR If a UDP server socket is opened:-this parameter indicates the port on which the UDP server will listen for incoming connections. Default Value: 0 Type: u16 Range: 1 to UdpTxDelay : This parameter holds the delay after which after which the socket will flush the characters to transmit to the remote entity. edlib usually buffers the characters until it s transmit buffer is full or the UdpTxDelay time expires. Default Value: 100ms Type: u16 UdpServ : This parameter will hold the UDP server IP address if a client UDP socket is opened. In case, a 2004 All rights reserved Page: 6 / 11

8 server UDP socket is opened, this parameter indicates the IP filtering which has to be done. (A value of indicates no IP filtering). Default Value: Empty string ( ). Type: array of ASCII data type. Length: 121 (including the NULL terminating string). A value of for UdpServ parameter in invalid for both client and server UDP socket. A UDP client socket cannot specify a value of as UdpServ parameter. (This is because, no server can have as its IP address). However, if a UDP server specifies this value for UdpServ Parameter, it indicates that no IP filtering should be performed. After setting the values of above parameters in an instance of ed_udpsocketsetupparams_t structure, these parameters should be set for the UDP socket to be started. The following API is used to set the parameters for the socket: s8 ed_udpsocketsetconfig (ed_udpsocketsetupparams_t *Params); Params: Structure containing the values to setup. This structure must be filled by the application prior to calling this API. 0 is returned on Success. activated in the WISMO product. ED_ERR_NOT_INIT is returned if the function cannot be used as ed_init () API is not called prior to calling ed_socketsetconfig API. ED_ERR_PARAM_BAD_VALUE is returned if a parameter value is invalid. ED_ERR_PARAM_TOO_LONG is returned if a parameter string is too long. ED_ERR_PARAM_WRITE_E2P is returned if writing a parameter to E2P failed. ED_ERR_INVALID_ARG is returned if an argument is invalid or contains a NULL pointer. ED_ERR_SERVICE_ALREADY_RUNNING is returned if the associated UDP service is already running and it is not possible to set the parameters Starting up UDP client/server socket edlib provides API which can be used to start UDP Client/Server socket. The parameters for socket must be configured before starting the socket using ed_udpsocketsetconfig () API. A client socket, after successful opening can immediately send data to the specified server on the specified port. There is no need to make a connection like TCP socket services. The UDP server socket, like its TCP counterpart, will passively listen for any connections destined for it. To open a UDP client/server socket, the following API should be used: s8 ed_socketudpstart (u8 Listen, ed_responsecbk_f pfresponsecbk, ed_datahandler_f pfdatahnd, ed_datarequest_f PfDataRequest); Listen: This parameter determines whether a client or a server UDP socket is opened. If a server UDP socket is opened, then this parameter is set to 1. On the other hand, If a client UDP socket is opened, then this parameter is set to 0 because, only server UDP sockets listens on a specified port, where client UDP socket will attempt to exchange data with the server on the listening port. pfresponsecbk: This parameter is a callback function which is automatically called by the edlib whenever any event related to UDP socket service occurs. This function has the following prototype : typedef void (*ed_responsecbk_f) (s32 ResponseCode, TeDHandle id); ResponseCode: This parameter contains the actual UDP socket event which has occurred. This parameter can have the following values : ED_INFO_LISTEN_SET: This event indicates that the listening UDP socket has been successfully created and now it is waiting for any remote entity (UDP client) to connect to it. This event is relevant only for a UDP server socket. ED UDP_CLOSED: This event indicates that the UDP client/server socket has been successfully closed. ED_INFO_WAITING_FOR_DATA: This event indicates that the UDP client has been successfully opened and is ready to send data to the server. If this event is received on the server side, it indicates that it has received a datagram from some client. ED_ERR_DISTANT_DNS: This error indicates that the Remote server name has not been mapped by DNS. TCP/IP stack is not able to reach the primary and secondary DNS servers or a wrong server address has been filled in. ED_ERR_STACK_INTERNAL: This error indicates some internal IP stack error. ED_ERR_LISTEN_STOP: This event indicates that a listening UDP socket has been cancelled using ed_socketludpstop () API. A listening socket is the one which is listening for incoming client requests and has not received any such request yet. ED_ERR_NETWORK_KO: This event indicates that the WISMO module is not connected to the network when an attempt was made to open a UDP socket. ED_ERR_GPRS_SESSION_LOST: This event indicates that the GPRS session has lost activation (The module is no longer connected to GPRS). This event occurs in case, GPRS connection is lost while a TCP socket was open in client or server mode. id: This parameter is always set to ED_ID_UDP_SOCKET. ED_ERR_LISTEN_STOP event is received when a listening UDP socket is closed using ed_socketludpstop () API. Once the listening server socket has made a connection with a client UDP guess UDP) socket, it becomes active and ed_socketludpstop API cannot be used to close this socket. When a listening socket is closed, first ED UDP_CLOSED event will be received and then ED_ERR_LISTEN_STOP event will be received All rights reserved Page: 7 / 11

9 pfdatahnd: This function is called by the IP library to forward the data received to the application. This callback function has the following prototype : typedef u16 (*ed_datahandler_f) (u16 DataLen, u8 *Data, TeDHandle id); DataLen: This parameter is the length of data which has been received in the data handler. Data: This parameter is the pointer to the actual data received. id: This parameter is always set to ED_ID_UDP_SOCKET. Return Value: The return value of this function indicates the number of bytes processed by the application. The application should return the appropriate number representing this value. The remaining bytes will be processed in the next call to this function. pfdatarequest: This function is called by IP library when a client UDP socket is opened. This function asks for the data to be sent by the user. Inside this function, calls to ed_senddata functions can be made with the following prototype : typedef void (* ed_datarequest_f) (u16 MaxLen, TeDHandle id) ; MaxLen: This parameter specifies the maximum data length which can be sent in this call to the pfdatarequest function. This length should be taken care of in any call to ed_senddata function to send data to the peer entity. id: This parameter is always set to ED_ID_UDPSOCKET. In case of UDP server socket, this function (pfdatarequest ()) is called when a UDP datagram is received by it (sent to it by some client). In case of UDP client socket, this function is called when the client socket is opened. Data should preferably be sent from this callback function because ed_senddata () API will be successful only when a prior call has been made to pfdatarequest () API. In case, no call was made to pfdatarequest and an attempt is made to send data using ed_senddata, error code -51 (ED_ERR_INVALID_CALL) will occur. Hence, it is preferable to call ed_senddata from within this function. However, the application is free to use it from outside (by subscribing to some commands) in case provision is made to take this factor into account. The length of data to be sent (using ed_senddata () API) should be less than or equal to the MaxLen parameter of pfdatarequest callback function. Return Values (of pfdatarequest Callback function): NONE 0 is returned on success. enabled on the product. ED_ERR_NOT_INIT is returned if ed_init () API is not called prior to calling this API. ED_ERR_INVALID_ARG is returned if one of the arguments has invalid or NULL value. ED_ERR_STACK_BAD_CONFIG is returned if IP connectivity library has incorrect configuration. ED_ERR_PHY_NOT_ACTIVATED is returned if IP connectivity library physical connection is not activated. This event occurs when physical connection (GPRS connection or GSM call) is not active at the time of data transfer. ED_ERR_STACK_BUSY is returned if another IP connectivity library application is already running Sending Data and Closing UDP Client/Server edlib provides APIs to exchange data from one peer to another peer. ed_senddata () API should be used to send data and/or to close the UDP Client/Server socket. This API has the following prototype: s8 ed_senddata (u8 *Data, u16 DataLen, bool bend); Data: Pointer to data to send. DataLen: Length of data to send. bend: Boolean variable which indicates whether end of data transmission has reached or not. If bend=true, it indicates that the IP connectivity library has received the last block of data to send for current session and it will not request data anymore (by calling pfdatarequest () API). However, if bend= FALSE, it is an indication that more data has to been sent by the application and pfdatarequest function will be called again which will ask user for more data to send. 0 is returned on success. enabled on the product. ED_ERR_NOT_INIT is returned if ed_init () API is not called prior to calling ed_senddata API. ED_ERR_INVALID_CALL is returned if ed_senddata API cannot be called now because pfdatarequest () function was not called by IP connectivity library. ED_ERR_INVALID_SIZE is returned if DataLen parameter of ed_senddata function is greater than expected. The flag bend provides a way to close the UDP client/server socket. This flag should be used to close any of these sockets. If this flag=true, it indicates that the last block of data has been sent and the socket will close. ed_senddata () can be called from pfdatarequest API and the MaxLen parameter of pfdatarequest API must be taken into account before sending data using ed_senddata API. edlib provides one more API which can be used to send UDP datagrams. Following is the prototype of this API: s8 ed_senddataext (u8 *Data, u16 DataLen, bool bend, TeDHandle id); This API is usually used for sending data associated with TCP socket services. If the id parameter is set to ED_ID_UDPSOCKET, then this API can also be used for UDP socket services. This API also performs the same task as is performed by ed_senddata () API. Please refer section for more details on this API To Close a listening UDP Server Socket In order to close a listening UDP server socket the following API should be used: 2004 All rights reserved Page: 8 / 11

10 s8 ed_socketludpstop (ed_responsecbk_f ResponseCbk); pfresponsecbk: This is the callback function which is called by IP library to indicate various socket related events (like socket close, or some error condition). For more information on this callback, please refer section (2.3.2). A 0 is returned on success. enabled on the product. ED_ERR_NOT_INIT is returned if ed_init () API is not called prior to calling ed_socketludpstop API. ED_ERR_INVALID_ARG is returned if one of the arguments has invalid or has NULL value. ED_ERR_NO_LISTEN if ed_socketludpstop is called when no socket is opened in listening mode. Reference: A listening socket is the one which is listening for some incoming datagrams and has not received any. Once a listening socket received a datagram from a client, it becomes active and cannot be closed by ed_socketludpstop () API. To stop the active socket, use ed_senddata (section ). Open AT TM IP Connectivity Library Guide (edlib v3.00) 3 CUSTOM AT COMMANDS 3.1 Commands for TCP Socket The following AT commands are included in the Open AT TM application for TCP client/server sockets. AT+APNPARAMS Command Description: This command is used to generate a menu which would display the commands that can be used to set the APN parameters (like APN server, APN User-name and APN password). Please note that the default value of all these parameters is empty string ( ). The APN parameters should be set only to override this default value ( ). AT+APNSERV = <server_string> <server_string > Any string valid This parameter stands for the APN server name. Command Description: This command is used to set the APN server string. The default value of this parameter (APN server string) is empty string ( ). The command (AT+APNSERV=<server_string>) can be used to override this default value. AT+APNUN = <user_name> <user_name> Any valid string This parameter stands for the APN user name. Command Description: This command is used to set the APN user name. The default value of this parameter is empty string ( ). This command should be used to override this default value. AT+APNPW = <password> <password> Any valid string This parameter represents the APN password Command Description: This command is used to set the APN password string. The default value of this parameter is empty string ( ). This command should be used only to override this default value. AT+START Command Description: This command is used to connect to the service provider and get an IP address. This command utilises the APN parameters set previously. So, correct APN parameters must be entered prior to executing this command. AT+LTCPSTART Command Description: This command is used to start the TCP server socket in listening. Before starting the server socket, this command prompts the user to enter the port (using AT+LPORT command) on which the TCP server will listen. AT+LPORT = <port> <port> Port on which TCP Server will listen client TCP connections. Command Description: This command is used to specify the port on which the TCP server socket will listen. AT+LTCPSTOP Command Description: This command is used to stop the listening TCP server socket. However, for this command to be effective, the TCP server socket must not have a connection with some TCP client socket. This is because, if some client connects to the TCP server socket, the TCP server socket becomes active (does not remain in listening state) and cannot be closed using AT+LTCPSTOP command. To stop this connection use AT+CTCP command (described later). AT+OTCP Command Description: This command will start a client TCP socket. After this command is executed, the customer will be prompted to enter port and IP address of TCP server (using AT+SPORT and AT+IP commands). AT+SPORT = <port> <port> The on which the TCP server socket is listening with whom the connection is to be made. Command Description: This command will set the destination TCP server port for a client TCP socket. For example, AT+SPORT = All rights reserved Page: 9 / 11

11 AT+IP = <ip_addr> <ip_addr> Valid string IP address of the server representing with whom TCP socket an IP connection is to be made. address Command Description: This command will set the destination TCP server socket IP address for a client TCP socket. This command should be used after AT+PORT command is used. For example, AT+IP = In case, some error occurs in starting TCP client socket, then AT+OTCP command should be given to start the whole process once again. AT+SENDDATA= <data> <data> Any valid string The data to be sent over the established TCP socket connection. Command Description: This command is used to send data to the remote peer. The length of data to be sent should be less than or equal to the MaxLen parameter of the ed_datarequest_f callback function (described later in this application note). For instance, AT+SENDDATA= test. AT+CTCP Command Description: This command is used to close the client/active server socket. 3.2 Commands for UDP Socket Unlike application for TCP socket, UDP socket application makes connection with the APN server and provides an IP address to the user. To change the APN parameters, some modifications in the UDP sample application code should be made (like changing APN server, APN user name and APN password). This exemplifies a different approach than TCP sockets. Following commands are subscribed in the UDP socket application. It should be noted that these commands should be issued only after receiving an IP address from the network service provider. AT+LUDPSTART Command Description: This command starts a UDP server socket on port 80. No IP filtering is specified. AT+LUDPSTOP Command Description: This command will stop the UDP server socket started on port 80. However, for this command to be effective, the UDP server socket must not have received any data from a client UDP socket. If UDP server receives data from some client socket, it becomes active (does not remain in listening state) and cannot be closed using AT+LUDPSTOP command. To stop this connection use AT+CUDP command (described later). AT+OUDP Command Description: This command will start a client UDP socket. After this command is executed, the customer will be prompted to enter port and IP address of UDP server (using AT+PORT and AT+IP commands which are described below). AT+PORT = <port> <port> Port on which server UDP socket is listening to which connection is to be made. Command Description: This command will set the destination UDP server port for a client UDP socket. For instance, AT+PORT = 240. AT+IP = <ip_addr> <ip_addr> A valid string representing an address IP This parameter represents the IP address of the UDP server socket with whom UDP socket connection is to be made. Command Description: This command will set the destination UDP server socket IP address for a client UDP socket. This command should be used after AT+PORT command is used. For instance, AT+IP = AT+CUDP Command Description: This command is used to close the UDP client/active UDP server socket. An active UDP server socket is the one which has successfully exchanged data with one of the client sockets and is not in listening state. AT+SENDDATA Command Description: This command is used to send data to the remote UDP peer. The data constitutes of the text string Hello. 4 EXAMPLES Example 1 TCP socket Action Response Action Power up Waiting for +WIND: 4. Module waiting for +WIND: 4 indication. Please wait.. Reception of +WIND: 4 +WIND: 4 received. Please wait.. Tries to attach to GPRS. After successful GPRS connection, main menu is shown on Terminal Emulator. AT+APNPARAMS Submenu is drawn on screen. AT+APNSERV= server_string New ApnServ Parameter is set. AT+APNUN= user_name New ApnUn parameter is set. AT+APNPW= password New ApnPw parameter is set AT+START AT+LTCPSTART AT+LPORT= <port> Trying to retrieve IP information. Please wait... Enter AT+LPORT to specify listening port Connecting with service provider using the APN parameters to receive an IP address. Prompts for port on which TCP server socket has to be started. Starts TCP server socket on the port 2004 All rights reserved Page: 10 / 11