SMO-SFO-0039 H PackIP ReferenceManual
-
Upload
danilo-almeida -
Category
Documents
-
view
218 -
download
0
Transcript of 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.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
2/45
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
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
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
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)
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
5/45
Rv. : Page : 2SMO/SFO-0039 H
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.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
6/45
Rv. : Page : 3SMO/SFO-0039 H
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 );
Include : < PPP_.h >
Return : Returns the connection handle (>=0) or a negative error code.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
7/45
Rv. : Page : 4SMO/SFO-0039 H
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 );
Include : < PPP_.h >
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 );
Include : < PPP_.h >
Return : Returns 0 or a negative error code.
Parameters :
nHandle : PPP connection handle.
Description : This function starts the connection (e.g. : . the PPP negotiation).
3.5 STOP A CONNECTION
Syntax : int PPP_Stop ( PPP_HANDLE handle );
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
8/45
Rv. : Page : 5SMO/SFO-0039 H
Include : < PPP_.h >
Return : Returns 0 or a negative error code.
Parameters :
nHandle : PPP connection handle.
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 );
Include : < PPP_.h >
Return : PPP connection state.
Parameters :
nHandle : PPP connection handle.
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 );
Include : < PPP_.h >
Return : Returns 0 or a negative error code.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
9/45
Rv. : Page : 6SMO/SFO-0039 H
Parameters :
nHandle : PPP connection handle.
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 );
Include : < PPP_.h >
Parameters :
nHandle : PPP connection handle.
szLogin : PPP user name
szPassword : PPP password.
nProfile : Connection profile.
Return : Returns 0 or a negative error code.
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.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
10/45
Rv. : Page : 7SMO/SFO-0039 H
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 );
Include : < PPP_.h >
Parameters :
nHandle : PPP connection handle.
nOption: Option to set.
pArg: Value.
Return : Returns 0 or a negative error code.
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 );
Include : < PPP_.h >
Parameters :
nHandle : PPP connection handle.
nOption: Option to get.
pArg: Value.
Return : Returns 0 or a negative error code.
Description : This function gets the current value of an option parameter of a
connection.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
11/45
Rv. : Page : 8SMO/SFO-0039 H
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.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
12/45
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
13/45
Rv. : Page : 10SMO/SFO-0039 H
pArg: Value.
Return : Returns 0 or a negative error code.
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.
Return : Returns 0 or a negative error code.
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).
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
14/45
Rv. : Page : 11SMO/SFO-0039 H
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.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
15/45
Rv. : Page : 12SMO/SFO-0039 H
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 :
nOption: Option to set.
pArg: Value.
Return : Returns 0 or a negative error code.
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 :
nOption: Option to set.
pArg: Value.
Return : Returns 0 or a negative error code.
Description : This function sets an option parameter of the Ethernet link.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
16/45
Rv. : Page : 13SMO/SFO-0039 H
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
17/45
Rv. : Page : 14SMO/SFO-0039 H
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 :
nOption: Option to set.
pArg: Value.
Return : Returns 0 or a negative error code.
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 :
nOption: Option to set.
pArg: Value.
Return : Returns 0 or a negative error code.
Description : This function sets an option parameter of the DNS resolver.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
18/45
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
19/45
Rv. : Page : 16SMO/SFO-0039 H
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").
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
20/45
Rv. : Page : 17SMO/SFO-0039 H
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).
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
21/45
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
22/45
Rv. : Page : 19SMO/SFO-0039 H
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 );
Include : < SMTP_.h >
Parameters :
handle: Handle on the connection to close.
Return : None.
Description : This function disconnects the terminal from the SMTP server.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
23/45
Rv. : Page : 20SMO/SFO-0039 H
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[] );
Include : < SMTP_.h >
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.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
24/45
Rv. : Page : 21SMO/SFO-0039 H
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 *szLogin,
const char *szPassword,
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[] );
Include : < SMTP_.h >
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.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
25/45
Rv. : Page : 22SMO/SFO-0039 H
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()
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
26/45
Rv. : Page : 23SMO/SFO-0039 H
10. POP3
10.1 CONNECTION TO THE SERVER
Syntax : POP3_HANDLE POP3_Connect (const char *szPop3Server,
int nPort,
const char *szLogin,
const char *szPassword,
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 );
Include : < POP3_.h >
Parameters :
handle: Handle on the connection to close.
Return : None.
Description : This function disconnects the terminal from the SMTP server.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
27/45
Rv. : Page : 24SMO/SFO-0039 H
10.3 REQUESTING THE NUMBER OF MESSAGES
Syntax : int POP3_GetNbMessages( POP3_HANDLE handle,int *nTotalSize );
Include : < POP3_.h >
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 );
Include : < POP3_.h >
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
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
28/45
Rv. : Page : 25SMO/SFO-0039 H
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 );
Include : < POP3_.h >
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.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
29/45
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
30/45
Rv. : Page : 27SMO/SFO-0039 H
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.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
31/45
Rv. : Page : 28SMO/SFO-0039 H
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 );
Include : < HTTP_.h >
Parameters :
hHandle: Handle on the HTTP/HTTPS server.
nTimeout: Duration to wait for a request.
pRequest : A pointer on the decoded HTTP request.
Return : Returns HTTP_SERVER_OK or a negative error code.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
32/45
Rv. : Page : 29SMO/SFO-0039 H
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
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
33/45
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
34/45
Rv. : Page : 31SMO/SFO-0039 H
- 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.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
35/45
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
36/45
Rv. : Page : 33SMO/SFO-0039 H
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 );
Include : < HTTP_.h >
Parameters :
hHandle: Handle on the HTTP server.
Return : Returns HTTP_SERVER_OK or a negative error code.
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 )
Include : < HTTP_.h >
Parameters :
hHandle: Handle on the HTTP server.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
37/45
Rv. : Page : 34SMO/SFO-0039 H
phSession: Handle on the current SSL connection.
phProfile: Handle on the server SSL profile.
Return : Returns HTTP_SERVER_OK or a negative error code.
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.
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
38/45
Rv. : Page : 35SMO/SFO-0039 H
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".
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
39/45
Rv. : Page : 36SMO/SFO-0039 H
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 );
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
40/45
Rv. : Page : 37SMO/SFO-0039 H
// 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] );
...
}
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
41/45
Rv. : Page : 38SMO/SFO-0039 H
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 !!!
};
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
42/45
Rv. : Page : 39SMO/SFO-0039 H
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 );
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
43/45
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
44/45
Rv. : Page : 41SMO/SFO-0039 H
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)
{
-
8/12/2019 SMO-SFO-0039 H PackIP ReferenceManual
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 );
}
}
}