SMO-SFO-0039 H PackIP ReferenceManual

8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual

1/45

TRES IMPORTANT : la validit du prsent document, soumis signature lectronique Page : M1doit tre vrifie, avant usage, dans le rpertoire Docs Applicables de PRISMA Programmes.

Rfrence / Reference :SMO/SFO-0039 Rvision /Revision:H

Titre /Title : Package IP Reference Manual

Programme/ Subject: TELIUM

Approbation de la rvision /Revision Approval: H

NomName

FonctionFunction

Etabli par :

Written by:Vincent Gomes Software Engineer

Vrifi ou Approuv par :

Checked or approved by:Jean-Luc Menez SDK Project Manager

Autoris par :Authorized by:

Christophe Barthelemy SDK Product leader

Rvision

Issue

Date de validit /dapplication

Validity/application date

Nb depages

Nb of

pages

Nb de pagesannexes

Nb of

appendices

Objet et description de la modification

Object and description of modification

A September 2005 Initial version (PackIP 1.2).

B November 2005 Add sample "ExternalGPRS" (PackIP 2.1)

C August 2006 Add PING facility and default routesettings (PackIP 2.2)

D January 2007 Add SMTP and POP3 interfaces (PackIP3.0)

E April 2007 Add HTTP server and attached files forSMTP (PackIP 3.1)

F February 2008 Add details on HTTP server functions.

G April 2008 Add HTTPS server facility.

H October 2008 Add details on Ethernet options.


2/45


3/45

Rv. : Page : S2SMO/SFO-0039 H

10.6 RESET THE SESSION ...................................................................................................................................................26

11. HTTP/HTTPS SERVER ....................................................... ........................................................... ...........................27

11.1 LAUNCH THE SERVER .................................................................................................................................................27 11.2 WAIT FOR A REQUEST ................................................................................................................................................2811.3 SEND A RESPONSE ......................................................................................................................................................32 11.4 STOP THE SERVER ......................................................................................................................................................3311.5 GET INFORMATION ABOUT SSL SESSION (HTTPS ONLY) ..................................................... .....................................33

12. COMPATIBILITY ...................................................... ........................................................... .....................................35

13. SAMPLE PROGRAMS...............................................................................................................................................36

13.1 PPP SAMPLE ..............................................................................................................................................................3613.2 ETHERNET SAMPLE ....................................................................................................................................................37 13.3 ENABLE/DISABLE THE ICMP REPLY FACILITY ...........................................................................................................38

13.4 MAIL SAMPLE ............................................................................................................................................................38 13.5 HTTP SAMPLE ...........................................................................................................................................................41


4/45

Rv. : Page : 1SMO/SFO-0039 H

1. INTRODUCTION

The package IP is a static library (named IP_.lib) which makes easier the development ofInternet programs for EFT POS terminals. This library is static (it must be linked with the

application). It is compiled with the three compilers (GCC, RVD and SDT) supported by theTelium SDK. Its interface is composed of several API header files : , ,, .and .

The package provides all the services to perform Internet communications. Its main facilitiesare :

IP communications. BSD interface. Client and server. TCP/IP. UDP.

PPP Management.

Ethernet Management.

DNS Resolver.

SMTP and POP3 email services.

HTTP server facility

...

Developers shall read the [SMO-SFO-0075_PackIP_SecurityGuidance.pdf] which describesbest practises for implementing IP enabled applications, according to the requirements of thePOS Terminal Security Program.(PTS)


5/45


2. OVERVIEW

Folder Content DescriptionSDK/inc IP_.h

PPP_.h

SMTP_.hPOP3_.hHTTP_.h

The library header files for respectively IP,PPP, SMTP, POP3 and HTTP.

SDK/lib_gnu IP_.lib Static IP library for GNUSDK/lib_rvd IP_.lib Static IP library for RVDSDK/lib_sdt IP_.lib Static IP library for SDTSDK/Samples/ExternalGPRS Source of a sample application which

manages an external GPRS modem. It showshow to perform a PPP connection.

SDK/Samples/TCPIP * Source of a sample application which shows:1. how to implement a TCP client

2. how to implement a TCP server3. how to retrieve the Ethernet parameters4. how to send and receive emails

SDK/Sample/FTP Source of a FTP sample (please refer theFTP documentation)

SDK/Sample/SSL Source of an SSL sample (please refer theSSL documentation)

The header file regroups mainly the standard BSD definitions. This document does notexplain these functions. It describes the specific functions, particularly the ones of the interfaceof the integrated protocols PPP, HTTP, POP3 and SMTP.


6/45


3. PPP INTERFACE

3.1 CONNECTION

Syntax : PPP_HANDLE PPP_Connect( const char *szComPort,const char *szLogin,const char *szPassword,int nProfile,unsigned int nDelay,unsigned int nTimeout );

Include : < PPP_.h >

Parameters :

szComPort: Communication port name (for example : "COM1", "COM6" ...).

szLogin : PPP user name

szPassword : PPP password.

nProfile : Connection profile.

nDelay: Polling delay (in 10 ms)

nTimeout Maximum waiting delay (in 10 ms)

Return : Returns the connection handle (>=0) or a negative error code.

Description : This function establishes a PPP connection through a communication

port. It performs all the process of the connection.

Nota : Several common connection modes are possible. Please refer to the

function "PPP_Setup" to know the different profiles.

The polling delay must be lower than the timeout delay. It indicates the

delay to verify periodically the state of the connection.

3.2 OPEN A CONNECTION

Syntax : PPP_HANDLE PPP_Open ( const char *szComPort );


Return : Returns the connection handle (>=0) or a negative error code.


7/45


Parameters :

szComPort: Communication port name (for example : "COM1", "COM6" ...).

Description : This function opens a connection through a communication port

(physical link). The communication port must be previously opened.

The function returns only an handle on the connection.

3.3 CLOSE A CONNECTION

Syntax : int PPP_Close ( PPP_HANDLE handle );


Return : Returns 0 or a negative error code.

Parameters :

nHandle : PPP connection handle.

Description : This function closes a connection. It releases all its allocated

resources.

3.4 START A CONNECTION

Syntax : int PPP_Start ( PPP_HANDLE handle );



Parameters :


Description : This function starts the connection (e.g. : . the PPP negotiation).

3.5 STOP A CONNECTION

Syntax : int PPP_Stop ( PPP_HANDLE handle );


8/45




Parameters :


Description : This function stops the connection (e.g. : it disconnect it), but it do not

close the connection.

3.6 GET THE CONNECTION STATE

Syntax : int PPP_GetState ( PPP_HANDLE handle );


Return : PPP connection state.

Parameters :


Description : This function returns the state of the connection.

State CommentPPP_STATE_DEAD The physical link is not ready.PPP_STATE_ESTABLISH Physical connection in progressPPP_STATE_NETWORK Network connection in progressPPP_STATE_AUTH Authentication in progressPPP_STATE_TERMINATE DisconnectedPPP_STATE_IFUP Connection successful.

3.7 WAIT FOR A CONNECTION STATE

Syntax : int PPP_WaitState( PPP_HANDLE nHandle,int nWaitState, int nStateExit,unsigned long nTimeout );




9/45


Parameters :


nWaitState : Waited state

nStateExit : Exit State

nTimeout : Maximum timeout for waiting.

Description : This function waits until the connection has reached the given state.

It exits also, with an error, when the 'nStateExit' has been reached or

when the waiting timeout expires.

3.8 CONFIGURE A CONNECTION

Syntax : int PPP_Setup( PPP_HANDLE handle,const char *szLogin,const char *szPassword,int nProfile );


Parameters :


szLogin : PPP user name

szPassword : PPP password.

nProfile : Connection profile.


Description : This function configures the parameters of a connection..

Nota : Several common connection modes are possible. They are defined by a

specific profile

Profile DescriptionPPP_PERSONAL_PROFILE Minimal configuration (login and password). The user must

complete this configuration himself by calling the function"PPP_Set" (described below).PPP_PSTN_PROFILE Configuration dedicated to the PSTN communications.


10/45


PPP_GPRS _PROFILE Configuration dedicated to the GPRS communications.

3.9 SET AN OPTION OF THE CONNECTION

Syntax : int PPP_SetOption( PPP_HANDLE handle, int nOption, void *pArg );


Parameters :


nOption: Option to set.

pArg: Value.


Description : This function sets an option parameter of a connection..

3.10 GET AN OPTION OF THE CONNECTION

Syntax : int PPP_GetOption( PPP_HANDLE handle, int nOption, void *pArg );


Parameters :


nOption: Option to get.

pArg: Value.


Description : This function gets the current value of an option parameter of a

connection.


11/45


4. IP CONFIGURATION MANAGEMENT

The IP package provides functions to monitor the configuration of the IP facility. The differentoptions are listed in the table below. They can be read, written and saved persistently (to

become the default configuration). A sample is given in the section : 13.3 Enable/disable theICMP reply facility (page 38)

Option Value Access Comments__DFL_MAC_ADDRESS 6 bytes Read MAC Address__DFL_ETH_LINK_SPEED Integer.

10 or100

Read/Write Ethernet link speed__DFL_ETH_LINK_SPEED_10MB__DFL_ETH_LINK_SPEED_100MB

__DFL_ETH_BOOT_PROTOCOL DHCPor

Static

Read/Write Ethernet boot protocol (Static or DHCP)__DFL_ETH_BOOT_PROTOCOL_NONE

__DFL_ETH_BOOT_PROTOCOL_DHCP__DFL_ETH_ADDR 4 bytes Read/Write Ethernet local Address__DFL_ETH_GATEWAY 4 bytes Read/Write Ethernet gateway address__DFL_ETH_NETMASK 4 bytes Read/Write Ethernet network mask__DFL_ETH_DNS1 4 bytes Read/Write Ethernet DNS1 address__DFL_ETH_DNS2 4 bytes Read/Write Ethernet DNS2 address__DFL_ICMP_REDIRECT Bool

ON orOFF

Read/Write Activate ICMP redirection__DFL_ON__DFL_OFF

__DFL_ICMP_ECHO_REPLY Bool

ON orOFF

Read/Write Activate ICMP reply

__DFL_ON__DFL_OFF

4.1 LOAD THE DEFAULT CONFIGURATION

Syntax : ETHCONF_HANDLE__LoadDefaultOptions( int *pnError );

Include : < IP_.h >

Parameters :

pnError : Output parameter which returns the error code of the loading operation.

Error Code Comment__DLF_OK The IP configuration parameters have been

successfully loaded.__DFL_ERROR_HW_ADDR_FOUND The hardware address (MAC) is missing. It is

a mandatory parameter.__DFL_ERROR_OPEN_FAILED The default parameter file can not be opened.

__DFL_ERROR_LOADING Error when reading the default parameter file.


12/45


13/45


pArg: Value.


Error Code Comment__DLF_OK The option has been successfully retrieved.

__DFL_ERROR_INVALID_HANDLE Invalid handle parameter

__DFL_ERROR_INVALID_OPTION Invalid option parameter

Description : This function gets an option parameter of IP configuration.

4.4 SET AN OPTION OF THE DEFAULT CONFIGURATION

Syntax : int__SetDefaultOption( ETHCONF_HANDLE handle,

int nOption, void *pArg );

Include : < IP_.h >

Parameters :

handle : Handle on the configuration

nOption: Option to set. The list of options is given in table above.

pArg: Value.


Error Code Comment__DLF_OK The option has been successfully set.__DFL_ERROR_FIXED_OPTION The option is fixed. It can not be changed__DFL_ERROR_INVALID_VALUE The option value is invalid.

__DFL_ERROR_INVALID_HANDLE Invalid handle parameter

__DFL_ERROR_INVALID_OPTION Invalid option parameter

Description : This function sets an option parameter in the IP configuration. To make

this change persistent, the configuration must be saved using the

function __SaveDefaultOptions (described below).


14/45


4.5 SAVE THE DEFAULT CONFIGURATION

Syntax : int__SaveDefaultOptions( ETHCONF_HANDLE handle );

Include : < IP_.h >

Parameters :

handle : Handle on the configuration to save.

Return : Returns the negative error code __DFL_ERROR_INVALID_HANDLE

(the handle parameter is invalid ) or never returns.

Description : This function saves the configuration as the default one. The terminal is

automatically rebooted and the new saved configuration is used.


15/45


5. ETHERNET MANAGEMENT

The IP package provides two functions to monitor the Ethernet configuration. They allow to readand to write the parameters of the Ethernet interface. The parameters are listed in the following

table below. Some of them can not be written, they can be read-only.

Option CommentETH_IFO_ADDR Local address.ETH_IFO_NETMASK Network mask.ETH_IFO_BRDADDR Broadcast address.ETH_IFO_GATEWAY Gateway address (read-only).

ETH_IFO_DNS1 DNS address 1 (read-only).

ETH_IFO_DNS2 DNS address 2 (read-only).

5.1 GET AN OPTION OF THE ETHERNET LINK

Syntax : int EthernetGetOption( int nOption, void *pArg );

Include : < IP_.h >

Parameters :


pArg: Value.


Description : This function gets an option parameter of the Ethernet link..

5.2 SET AN OPTION OF THE ETHERNET LINK

Syntax : int EthernetSetOption( int nOption, void *pArg );

Include : < IP_.h >

Parameters :


pArg: Value.


Description : This function sets an option parameter of the Ethernet link.


16/45



17/45


6. DNS RESOLVER SETTINGS

The Domain Name Server (DNS) resolver settings can be monitored using the the two following

functions.

6.1 GET AN OPTION OF THE DNS RESOLVER

Syntax : int ResolverGetOption( int nOption, void *pArg );

Include : < IP_.h >

Parameters :


pArg: Value.


Description : This function gets an option parameter of the DNS resolver.

6.2 SET AN OPTION OF THE DNS RESOLVER

Syntax : int ResolverSetOption( int nOption, void *pArg );

Include : < IP_.h >

Parameters :


pArg: Value.


Description : This function sets an option parameter of the DNS resolver.


18/45


19/45


8. UTILITIES FUNCTIONS

The package TCP/IP provides other utility functions described in this section.

8.1 ACCESS THE INTERNAL ERROR (ERRNO)

The two following functions allow to access the internal error code (ERRNO).

Syntax : int GetErrno(void );

Include : < IP_.h >

Parameters : None.

Return : The internal error code value (ERRNO).

Description : This function returns the current value of the internal error code

(ERRNO).

Syntax : void SetErrno(int nError );

Include : < IP_.h >

Parameters :

nError : Error code.

Return : None.

Description : This function sets the value of the internal error code (ERRNO).

8.2 FORMAT A TCP/IP ADDRESS

The following functions are provided to convert and format a TCP/IP address.

Syntax : unsigned long__inet_addr( const char *szAddress );

Include : < IP_.h >

Parameters :

szAddress: .TCP/IP address - ASCII format ("www.xxx.yyy.zzz").


20/45


Return : Returns the converted address (4 bytes format) or 0 when the ASCII

address is not rightly formatted.

Description : This function converts an ASCII TCP/IP address to its 4 bytes format

(struct in_addr).

Syntax : char *__inet_ntoa( struct in_addr nAddress);

Include : < IP_.h >

Parameters :

nAddress: . TCP/IP address - 4 bytes format.

Return : Converted address - ASCII format ("www.xxx.yyy.zzz").

Description : Inverse of the function "__inet_addr". This function converts a 4 bytes

address in its ASCII format.

Nota : The returned character string is NULL terminated. It is allocated by the

function "__inet_ntoa" and belongs to this one. It must copied by the

calling function and must not be freed.

Syntax : int__inet_aton( const char *szAddress, struct in_addr *pnAddress );

Include : < IP_.h >

Parameters :

szAddress: .TCP/IP address - ASCII format ("www.xxx.yyy.zzz").

pnAddress: Converted address - 4 bytes format.

Return : Returns 1 if the address has been rightly converted, and 0 otherwise.

Description : This function converts an ASCII TCP/IP address to its 4 bytes format

(struct in_addr).


21/45


22/45


9. SMTP

9.1 CONNECTION TO THE SERVER

Syntax : SMTP_HANDLE SMTP_Connect( const char *szSMTPServer,

int nPort,

const char *szLogin,

const char *szPassword,

const char *szSMTPClient );

Include : < SMTP_.h >

Parameters :

szSMTPServer: TCP/IP address of the SMTP server.

nPort: SMTP port (usually 25).

szLogin User name. May be set to NULL (or ""), if no authentication

required by the remote SMTP server.

szPassword Password associated to the user name. Is NULL when the

user name is NULL.

szSMTPClient Network name of the terminal.

Return : Returns the connection handle (>=0), or a negative error code.

Description : This function connects the terminal to the SMTP server. This

connection can request an identification, or be anonymous (no user, nor

password).

9.2 DISCONNECTION FROM THE SERVER

Syntax : void SMTP_Disconnect ( SMTP_HANDLE handle );


Parameters :

handle: Handle on the connection to close.

Return : None.

Description : This function disconnects the terminal from the SMTP server.


23/45


9.3 SEND A MESSAGE

Syntax : int SMTP_Send ( SMTP_HANDLE handle,

const char *szMessage,

int nMessageSize,

const char *szSubject,

const char *szFrom,

const char *szTo,

const char *szCC,

const char *szBCC,

const char *pAttachedFilesList[] );


Parameters :

handle: Handle on an existing connection.

szMessage: Message to send. Please note that the global raw message's

size (header and content) is limited to 8 kilobytes.

nMessageSize: Size, in bytes, of the message to send.

szSubject: Subject of the message. May be NULL.

szFrom: E-mail address of the sender. This address cannot be NULL.

Use a valid address to be able to be informed about

distribution failures.

szTo: List of recipients. This list can be NULL. In case of multiple

recipients, put a comma (,) between each address.

szCC: List of recipients put in copy. This list can be NULL. In case ofmultiple recipients, put a comma (,) between each address.

szBCC: List of recipients put in blind copy. This list can be NULL. In

case of multiple recipients, put a comma (,) between each

address.

pAttachedFilesList: Array of attachement files' names. These files must be stored

in the FFMS before being sent. The complete path to these

files (directory and file name) must be put in this array. This list

can be NULL (no attached files). In any case, the last item ofthis list must be NULL.


24/45


Note: At least of one list of recipients (To, CC, or BCC) must not be NULL.

Return : Number of attachement files sent (0 if none), or a negative error code.

Description : Send an US-ASCII text message to the lists of specified recipients. This

message has an header formatted according to the standard RFC 822,

as long as this header is not greater than 1024 bytes. Otherwise no

header is added.

9.4 SEND A SINGLE MESSAGE

Syntax : int SMTP_SendUniqueMessage ( const char *szSMTPServer,

int nPort,



const char *szSMTPClient,

const char *szMessage,

int nMessageSize,

const char *szSubject,

const char *szFrom,

const char *szTo,const char *szCC,

const char *szBCC,

const char *pAttachedFilesList[] );


Parameters :

szSMTPServer: TCP/IP address of the SMTP server.

nPort: SMTP server port (usually 25).

szLogin: User name. May be set to NULL (or ""), if no authentication

required by the remote SMTP server.

szPassword Password associated to the user name. Is NULL when the

user name is NULL.

szSMTPClient Network name of the terminal.


25/45


szMessage: Message to send. Please note that the global raw message's

size (header and content) is limited to 8 kilobytes.

nMessageSize: Size, in bytes, of the message to send.

szSubject: Subject of the message. May be NULL.

szFrom: E-mail address of the sender. This address cannot be NULL.

Use a valid address to be able to be informed about

distribution failures,

szTo: List of recipients. This list can be NULL. In case of multiple

recipients, put a comma (,) between each address.

szCC: List of recipients put in copy. This list can be NULL. In case of

multiple recipients, put a comma (,) between each address.

szBCC: List of recipients put in blind copy. This list can be NULL. In

case of multiple recipients, put a comma (,) between each

address.

pAttachedFilesList: Array of attachement files' names. These files must be stored

in the FFMS before being sent. The complete path to these

files (directory and file name) must be put in this array. This list

can be NULL (no attached files). In any case, the last item ofthis list must be NULL.

Note: At least of one list of recipients (To, CC, or BCC) must not be NULL.

Return : Number of attachement files sent (0 if none), or an negative error code.

Description : This function can be used to send an unique message. It automatically

performs the sequence:

SMTP_Connect(),

SMTP_Send()

SMTP_Disconnect()


26/45


10. POP3

10.1 CONNECTION TO THE SERVER

Syntax : POP3_HANDLE POP3_Connect (const char *szPop3Server,

int nPort,



char bSecuredConnection );

Include : < POP3_.h >

Parameters :

szSMTPServer: TCP/IP address of the POP3 server.

nPort: POP3 server port (usually 110).

szLogin: User name.

szPassword: Password associated to the user name.

bSecuredConnection: Reserved for future use.

Return : Returns the connection handle (>=0), or a negative error code.

Description : This function connects the terminal to the POP3 server. This connection

requires an authentication.

10.2 DISCONNECTION FROM THE SERVER

Syntax : void POP3_Disconnect( POP3_HANDLE handle );


Parameters :

handle: Handle on the connection to close.

Return : None.

Description : This function disconnects the terminal from the SMTP server.


27/45


10.3 REQUESTING THE NUMBER OF MESSAGES

Syntax : int POP3_GetNbMessages( POP3_HANDLE handle,int *nTotalSize );


Parameters :

handle: Handle on the connection,

nTotalSize: Pointer to an integer to fill with the global size of the messages

currently into the open mail account. This pointer may be NULL if thisvalue is not needed.

Return : The number of messages currently into the mail account. This number

includes all the messages (new messages and those already read).

Description : This function returns the number of message present on the mail

account, and, if required, the total size occupied by the messages.

10.4 REQUESTING A GIVEN MESSAGE

Syntax : int POP3_GetMessage( POP3_HANDLE handle,

int nMessageIndex,

POP3_INFO *pPop3Info,

char *szBufferBody,

int nBufferSize );


Parameters :

handle: Handle on the connection,

nMessageIndex: Number of the message to retrieve from the POP3 server. The

index of the first message (oldest one) is 1.

pPop3Info: A pointer to the structure that will be filled with data extracted

from the header, and important message characteristics.

Please note that the buffers (see POP3_INFO descriptionbelow) containing these data are 128 bytes long. If the content


28/45


in the message's header is longer than 128 bytes, the data will

be truncated to fit with buffer size.

szBufferBody: Buffer to fill with the body of the message. This parameter can

be NULL, whether only the info structure is requested.

Note: The content of the body is US-ASCII text only. Thus, any mail containing other

elements, like MIME encoding parts, has to be processed by the user.

nBufferSize: Maximum size of the buffer allocated to receive the body of

the message.

Return : 0, or a negative error code.

Description : This function returns the given message, with, the header on the info

structure, and the body in a separate buffer.

typedef struct

{

charszSubject [_POP3_HEADER_LINE_SIZE]; // Subject of the message

charszFrom [_POP3_HEADER_LINE_SIZE]; // Sender of the message

charszDate [_POP3_HEADER_LINE_SIZE]; // Date

charszTo [_POP3_HEADER_LINE_SIZE]; // Recipicient(s)

char szCC [_POP3_HEADER_LINE_SIZE]; // Recipicient(s) in copy

charszUIDL [_POP3_HEADER_LINE_SIZE]; // Unique identifier for the message

int nSize; // Size of the message (in bytes)

} POP3_INFO;

Note: this function does not delete the message on the POP3 server. Hence, a new

request to this same message is valid.

10.5 DELETING A GIVEN MESSAGE

Syntax : int POP3_DeleteMessage( POP3_HANDLE handle,

int nMessageIndex );


Parameters :

handle: Handle on the connection.

nMessageIndex: Index of the message to delete from the POP3 server. The

index of the first message (oldest one) is 1.


29/45


30/45


11. HTTP/HTTPS SERVER

The package TCP/IP provides functions to easily manage the HTTP/HTTPS server facility. Itenables to launch a simple HTTP/HTTPS server and to process the incoming requests (GET,

POST and PUT). An HTTP sample is given in the section : 13.5. HTTP sample (page 41).

Note: to use the HTTPS facility, the SSL DLL must be loaded in the terminal and the applicationmust be linked with SSL_.lib library.

11.1 LAUNCH THE SERVER

Syntax : int HTTP_Server_Open( HTTP_SERVER_HANDLE *hHandle,

unsigned int nPort,

const char *szDestDisk );

int HTTPS_Server_Open( HTTP_SERVER_HANDLE *hHandle,

unsigned int nPort,

const char *szDestDisk,

const char* szSslProfile,

int bUseCache,

int bCheckPeer );

Include : < HTTP_.h >

Parameters :

hHandle: Handle on the HTTP(S) server.

nPort: Listening port (usually 80 for HTTP and 443 for HTTPS).

szDestDisk: Disk name where the server stores the downloaded files.

This parameter can be set to NULL: in that case, the server won't

store any files.

szSslProfile: Name of the SSL profile - HTTPS server only.

bUseCache: Set to TRUE to use SSL session cache, FALSE otherwise -

HTTPS server only.

bCheckPeer: Set to TRUE to check peer certificate (mutual authentication),

FALSE otherwise (simple authentication) HTTPS server only.

With simple authentication, the server does not authenticate the

client (but the client does authenticate the server).

Return : Returns HTTP_SERVER_OK or a negative error code.


31/45


Error Code Comment

HTTP_SERVER_OKThe function succeeds.The server is launched.

HTTP_SERVER_ERROR_MEMORY

Memory error for the handle

allocation.

HTTP_SERVER_ERROR_SOCKETCannot create or activate thelistening socket.

HTTP_SERVER_ERROR_DISKCannot mount the destinationdisk.

HTTP_SERVER_ERROR_INVALID_PROFILE Cannot load the SSL profile.

HTTP_SERVER_ERROR_SSL_DLL_NOT_FOUNDCannot open the SSL DLL : is itloaded in the terminal ?

Description : This function starts the HTTP server on the given port. A handle is

allocated and returned.

Note: The function mounts the destination disk. This disk is unmounted when

the server is stopped (see function HTTP_Server_Close() described

below).

11.2 WAIT FOR A REQUEST

Syntax : int HTTP_Server_WaitRequest ( HTTP_SERVER_HANDLE hHandle,

unsigned int nTimeout

HTTP_SERVER_DATA **pRequest );

int HTTPS_Server_WaitRequest ( HTTP_SERVER_HANDLE hHandle,

unsigned int nTimeout

HTTP_SERVER_DATA **pRequest );


Parameters :

hHandle: Handle on the HTTP/HTTPS server.

nTimeout: Duration to wait for a request.

pRequest : A pointer on the decoded HTTP request.



32/45


Error Code Comment

HTTP_SERVER_OKThe function succeeds. Arequest has been received,decoded and returned.

HTTP_SERVER_ERROR_TIMEOUT Timeout expired. No requestreceived.

HTTP_SERVER_ERROR_HANDLE Invalid handle parameter.

HTTP_SERVER_ERROR_SOCKETRequest refused. Thededicated socket can not becreated.

HTTP_SERVER_ERROR_CLIENT_TIMEOUTNothing received from theclient in the last 10 seconds.

HTTP_SERVER_ERROR_CLIENT_SOCKET Error on client socket.

HTTP_SERVER_ERROR_MALFORMED_REQUESTUnable to parse the requestproperly.

Description : This function waits for the reception of an HTTP request. The request is

decoded and returned in the parameter of type HTTP_SERVER_DATA

(described below).

Note: The function creates a connection dedicated to the treatment of the

request. The pointer on the request is internally allocated, it must not be

released by the application.

If the call to HTTP_Server-WaitRequest() function is successful (return

code equal to HTTP_SERVER_OK), a call to HTTP_SendResponse() is

mandatory to terminate the dedicated connection properly. For any

other return codes, the connection with the client, if established, is

automatically closed.

The requests sent to the server are automatically decoded and stored in a structure of typeHTTP_SERVER_DATA described below.

typedefstruct{

// Request

char m_nCommand; // HTTP Command

char m_szHttpVersion[4]; // HTTP Version (0.9, 1.0 or 1.1)

char m_szURI[HTTP_SERVER_MAX_URI]; // Address of the requested page

// Header parameters

shortm_nHeaderParamNb; // Number of elements in the header

char m_szHeaderParamName [][]; // Name of the parameter

char m_szHeaderParamValue[][]; // Value of the parameter

shortm_nBoundaryPos; // Internal use only

// Data

shortm_nDataNumber; // Number of data


33/45


34/45


- m_szDataValue[nIndex]: a string storing the value of the nIndexth data element. Themaximum length for this value is 64 bytes.

File parameters (for POST and PUT only):

- m_nFileNumber: number of files retrieved. A maximum of 6 files can be loaded using onerequest.

- m_szFilename[nIndex]: the name of the nIndexth downloaded file directly taken from therequest. The real name of the file saved in flash is put m_szFlashFileName[nIndex] (seebelow). The maximum length of this string is 32 bytes. If the request is sent with a name thatincludes '/' or '\' (full path to a file), only the string after the separator is read and stored inthe buffer.

- m_szFileType[nIndex]: a string describing the type of the nIndexth downloaded file. Themaximum length of this string is 32 bytes.

- m_szFsFileName[nIndex]: the name of the file stored in the server disk. The name isadapted from m_szFileName[nIndex] to be compliant with Telium File System requirements(length of the name and characters supported).

- m_szFileLength[nIndex]: length of the file (in bytes).

Note: the files received through POST and PUT methods are automatically stored in the diskspecified when calling HTTP_Server_Open() function.

If the file name already exists in the disk, the new file is not downloaded to the disk,and is not added to the data structure.

In a request containing raw data after the header (not separated by boundaries), the datareceived by the server is stored in a file named "HTTP_R.BIN" when is the file

index coded in 4 hexadecimal digits format

Other parameters

- m_nContentLength: value of the parameter "Content-Length" of the request.

- m_szBoundary: HTTP boundary found in the request.

- m_szClientAddress: address of the client (aaa.bbb.ccc.ddd).

- m_nClientPort: port of the client.

Example

The client sends a post request through the HTML form below.

File selection

The data structure is filled with the content of the request: the selected file is "test.txt", the request is sentusing a web browser. The file "test.txt" is automatically stored in the disk specified in theHTTP_Server_Open() function.


35/45


36/45


HTTP_SERVER_ERROR_NO_REQUEST No request is currently in progress.HTTP_SERVER_ERROR_SERVER_CLOSED The server is not running.HTTP_SERVER_ERROR_SOCKET Error on server listening socket.

Description : This function sends an HTTP response and then close the dedicated

connection. It must be called after the success of the call to the functionHTTP_Server_WaitRequest().

11.4 STOP THE SERVER

Syntax : int HTTP_Server_Close ( HTTP_SERVER_HANDLE hHandle );

int HTTPS_Server_Close ( HTTP_SERVER_HANDLE hHandle );


Parameters :

hHandle: Handle on the HTTP server.


Error Code Comment

HTTP_SERVER_OK The function succeeds. The server hasbeen stopped.

HTTP_SERVER_ERROR_HANDLE Invalid handle parameter

Description : This function stops the HTTP server and releases the handle and all the

resources used by the server.

Note : The destination folder is unmounted.

11.5 GET INFORMATION ABOUT SSL SESSION (HTTPS ONLY)

Syntax : int HTTPS_Server_GetHandles ( HTTP_SERVER_HANDLE hHandle,

SSL_HANDLE* phSession,

SSL_PROFILE_HANDLE* phProfile )


Parameters :

hHandle: Handle on the HTTP server.


37/45


phSession: Handle on the current SSL connection.

phProfile: Handle on the server SSL profile.


Error Code Comment

HTTP_SERVER_OK The function succeeds.HTTP_SERVER_ERROR_HANDLE Invalid handle parameter

Description : This function retrieves the handles on the SSL connection and on the

server SSL profile.

Note : phSessionwill only return a non NULL value while a connection with a

client is established (between a successful call to HTTPS_Server_

WaitRequest() and HTTPS_Server_SendResponse()).

phProfilewill return a non-NULL value ever since the HTTPS server is

successfully launched.


38/45


12. COMPATIBILITY

The package TCP/IP is compatible with BSD interface. However, it exists some differences,listed below.

The "shutdown" function is renamed "shutdownsocket".

The "select" function is renamed "selectsocket".

The functions "gethostbyname" and "gethostbyaddr" are deprecated and replacedrespectively by the functions : "gethostbyname_r" and "gethostbyaddr_r".

The functions "inet_addr", "inet_aton" and "inet_ntoa" are deprecatated and replacedrespectively by the functions :"__inet_addr", "__inet_aton" and "__inet_ntoa".


39/45


13. SAMPLE PROGRAMS

13.1 PPP SAMPLE

This section provides a simply sample to show how to perform a PPP connection through theGSM link.

After connecting the PSTN provider in GSM, just call the following function.

intPPP_Connect( char*szLogin, char*szPassword )

{

intnState = 0;

PPP_HANDLE nHandle = 0;

inti = 0;

nHandle = PPP_Open( "DGPRS" );

if( nHandle != 0 )

{

PPP_Setup( nHandle, szLogin, szPassword, PPP_PSTN_PROFILE );

PPP_Start( nHandle );

do

{

nState = PPP_GetState( nHandle );

ttestall( 0, 100 );

}

while(( i < 60 ) &&

( nState != PPP_STATE_IFUP) &&

( nState != PPP_STATE_DEAD));

if( nState == PPP_STATE_IFUP)

{

// Connection success.

return0;

}

}

return -1;

}

The PPP configuration can be made accurately by the user.

...

void*arg = 0;

// The minimal configuration :

// Just the login and the password are set.PPP_Setup( nHandle, szLogin, szPassword, PPP_PERSONAL_PROFILE );


40/45


// Set several options.

//------------------------------

// Ask for peer authentication.

arg = PPP_TRUE;

PPP_SetOption( nHandle, PPP_INFO_LCP_AUTH, &arg );

// Negociate DNS1 address, but not DNS2

arg = PPP_TRUE;

PPP_SetOption( nHandle, PPP_INFO_IPCP_DNS1, &arg );

arg = PPP_INT(0);

PPP_SetOption( nHandle, PPP_INFO_IPCP_DNS1_ADDR, &arg);

arg = PPP_FALSE;

PPP_SetOption( nHandle,PPP_INFO_IPCP_DNS2, &arg );

...

13.2 ETHERNET SAMPLE

The following code shows how to get the information of the Ethernet link (local IP address andthe network mask).

voidPrintNetworkInfos()

{

charszTemp[BUFFER_SIZE];

unsignedchar*p;

unsignedintlocal_addr = 0;

unsignedintnetmask_addr = 0;

EthernetGetOption( ETH_IFO_ADDR, &local_addr );EthernetGetOption( ETH_IFO_NETMASK, &netmask_addr );

p = (char*) &local_addr;

sprintf( szTemp, "Local Addr: %d.%d.%d.%d\n",

p[0], p[1], p[2], p[3] );

...

p = (char*) &netmask_addr;

sprintf( szTemp, "Netmask: %d.%d.%d.%d\n",

p[0], p[1], p[2], p[3] );

...

}


41/45


13.3 ENABLE/DISABLE THE ICMP REPLY FACILITY

This sample code below shows how to enable or disable the ICMP reply facility. It demonstrateshow to modify the default parameters.

voidActivateReplyICMP( intbOn )

{

ETHCONF_HANDLE hConf = __LoadDefaultOptions( NULL );

if( hConf != NULL )

{

intbEchoReply;

if(__GetDefaultOption( hConf,__DFL_ICMP_ECHO_REPLY, &bEchoReply )

== __DLF_OK )

{

if( bEchoReply != bOn )

{// Modify the option.

__SetDefaultOption( hConf,__DFL_ICMP_ECHO_REPLY, &bOn );

// Save the configuration. The terminal reboots automatically.

__SaveDefaultOptions( hConf );

}

}

__UnloadDefaultOptions( hConf );

}

}

13.4 MAIL SAMPLE

The sample code below shows how to send and receive an email using the dedicated interface.

voidSendMail( const char* szSubject, const char* szMessage )

{int nReturn;

int nPort = 25;

charszSmtpAddress[] = "123.123.123.123";

charszLogin[] = "myaccount";

charszPassword[] = "mypassword";

charszSmtpClient[] = "TELIUM_CLIENT";

charszFrom[] = "[email protected]";

charszTo[] = "[email protected],[email protected]";

charszCC[] = "[email protected]";

const char*pList[] = {

"/HOST/FILE1.TXT",

"/TEMP/FILE2.BIN",

NULL // Last item must be NULL !!!

};


42/45


nReturn = SMTP_SendUniqueMessage( szSmtpAddress,

nPort,

szLogin,

szPassword,

szSmtpClient,

szMessage,

strlen( szMessage ),

szSubject,

szFrom,

szTo,

szCC,

NULL, // No recipient in blind copy

pList );

if( nReturn == 2 )

{

// Both attached files where successfully sent

}

else

{

if( nReturn >= 0)

{

// At least one attached file was not sent

// The message is sent without this (these) file(s)

}

else

{

// The mail was not sent

}

}

}

voidReceiveMail( void)

{

POP3_HANDLE hPop;

POP3_INFO Info;

int nMessages;

int nTotalSize;

int bDeleteFromServer = FALSE;

int nPort = 110;

int nIndex;

int nReturn;

char szPopAddress[] = "123.123.123.123";

char szLogin[] = "mylogin";

char szPassword[] = "mypassword";

char* pcBuffer;

...

hPop = POP3_Connect( szPopAddress, nPort, szLogin, szPassword, FALSE );

if( hPop >= 0 ){

// Retrieve the number of message on the account

nMessages = POP3_GetNbMessages( hPop, &nTotalSize );


43/45


44/45


13.5 HTTP SAMPLE

The following code shows how to launch an HTTP server and how to process the GETrequests.

static voidServerHTTP()

{

int nError;

HTTP_SERVER_HANDLE hServerHTTP;

HTTP_SERVER_DATA *pRequest;

unsigned int nMode;

char szFullURI[200];

char szDataToSend[4096];

unsigned int nDataSize;

S_FS_FILE *hFile;

// Launch the HTTP server.

// The folder which the folder HOST for destination directory.

if( HTTP_Server_Open( &hServerHTTP, 80, "/HOST" ) != HTTP_SERVER_OK )

{

// Error.

return;

}

// Mount the disk with the HTTP Files.

FS_mount( "/HOST", &nMode );

while(1){

// Wait for a request.

nError = HTTP_Server_WaitRequest( hServerHTTP, 80, &pRequest );

if( nError == HTTP_SERVER_OK )

{

strcpy( szFullURI, "/HOST" );

if( pRequest->m_nCommand == HTTP_SERVER_GET )

{// GET Command

if( strcmp( pRequest->m_szURI, "/" ) == 0 )

{

// Request the default web page.

strcat( szFullURI, "/INDEX.HTML" );

}

else

{

// Request a given page.

strcat(szFullURI, pRequest->m_szURI);

}

// Open the page file.hFile = FS_open(szFullURI, "r");

if(hFile == NULL)

{


45/45

// Problem to open the file.

// Return the default error page.

strcpy(szDataToSend, HTTP_SERVER_PAGE_404);

nDataSize = strlen(HTTP_SERVER_PAGE_404);

}

else

{ // Read the page file.

strcpy(szDataToSend, HTTP_SERVER_HTTP_200);

nDataSize = strlen(HTTP_SERVER_HTTP_200);

nDataSize += FS_read( szDataToSend + nDataSize,

1, 4096, hFile);

FS_close(hFile);

}

// Send the page response

HTTP_Server_SendResponse( hServerHTTP, szDataToSend, nDataSize );

}

}

}

Documents

SMO-SFO-0039 H PackIP ReferenceManual