IP Serial Server - LiveHelpNowsupportsystem.livehelpnow.net/resources/14629/Ethernet Serial... ·...
Transcript of IP Serial Server - LiveHelpNowsupportsystem.livehelpnow.net/resources/14629/Ethernet Serial... ·...
IP Serial Server, Programming Library Specification
Page 1 of 49
IP Serial Server
Programming Library Specification
V1.0.0
2009.8.6
IP Serial Server, Programming Library Specification
Page 2 of 49
Table of Contents 1. Introduction ................................................................................................................................. 4
1.1 TCP/UDP Port Numbers and Firewall ............................................................................. 4 1.2 Related Data Structures .................................................................................................... 4 1.3 Basic management to IP Serial Server ............................................................................. 7
1.3.1 Search the IP Serial Servers............................................................................................ 7 1.3.2 Reset the IP Serial Server ............................................................................................... 7 1.3.3 Configure the IP Serial Server settings .......................................................................... 7 1.3.4 Monitor function ............................................................................................................. 8
1.4 How to send the serial setting commands ........................................................................ 8 1.4.1 Related Data Structures .................................................................................................. 9 1.4.2 Major Steps with sample code ........................................................................................ 9
2. Programming library ................................................................................................................ 11 2.1 PP_Startup ...................................................................................................................... 11 2.2 PP_Search ....................................................................................................................... 11 2.3 PP_GetSrvHandle ........................................................................................................... 12 2.4 PP_Get_ServerName ...................................................................................................... 13 2.5 PP_Set_ServerName ...................................................................................................... 13 2.6 PP_Get_ServerSerialno .................................................................................................. 14 2.7 PP_Get_ServerPasswd ................................................................................................... 14 2.8 PP_Set_ServerPasswd .................................................................................................... 15 2.9 PP_Get_ServerDHCP ..................................................................................................... 15 2.10 PP_Set_ServerDHCP ..................................................................................................... 16 2.11 PP_Get_ServerIPAddr ................................................................................................... 16 2.12 PP_Set_ServerIPAddr .................................................................................................... 17 2.13 PP_Get_ServerNetMask ................................................................................................. 18 2.14 PP_Set_ServerNetMask ................................................................................................. 18 2.15 PP_Get_ServerGW ......................................................................................................... 19 2.16 PP_Set_ServerGW ......................................................................................................... 19 2.17 PP_Get_ServerConMode ............................................................................................... 20 2.18 PP_Set_ServerConMode ................................................................................................ 20 2.19 PP_Get_ServerCompany ................................................................................................ 21 2.20 PP_Get_ServerModelName ........................................................................................... 22 2.21 PP_Get_ServerMACAddr .............................................................................................. 22 2.22 PP_Get_ServerConfigVersion ....................................................................................... 23 2.23 PP_Get_ServerNumPorts ............................................................................................... 23 2.24 PP_Reset ......................................................................................................................... 24 2.25 PP_GetPortHandle .......................................................................................................... 24 2.26 PP_Get_PortConnectType ............................................................................................. 25 2.27 PP_Set_PortConnectType .............................................................................................. 25 2.28 PP_Get_PortBaudrate ..................................................................................................... 26 2.29 PP_Set_PortBaudrate ..................................................................................................... 26 2.30 PP_Get_PortDatabits ...................................................................................................... 27 2.31 PP_Set_PortDatabits ...................................................................................................... 28 2.32 PP_Get_PortStopbits ...................................................................................................... 28 2.33 PP_Set_PortStopbits ....................................................................................................... 29 2.34 PP_Get_PortParity .......................................................................................................... 29 2.35 PP_Set_PortParity .......................................................................................................... 30
IP Serial Server, Programming Library Specification
Page 3 of 49
2.36 PP_Get_PortFlowctrl...................................................................................................... 30 2.37 PP_Set_PortFlowctrl ...................................................................................................... 31 2.38 PP_Get_PortRemoteIP ................................................................................................... 31 2.39 PP_Set_PortRemoteIP .................................................................................................... 32 2.40 PP_Get_PortTimeout ..................................................................................................... 33 2.41 PP_Set_PortTimeout ...................................................................................................... 33 2.42 PP_Get_PortNum ........................................................................................................... 34 2.43 PP_Set_PortNum ............................................................................................................ 34 2.44 PP_Set_DTR_RTS ......................................................................................................... 35 2.45 PP_InitConnection .......................................................................................................... 35 2.46 PP_Connect .................................................................................................................... 36 2.47 PP_SetEventHandlers ..................................................................................................... 37 2.48 PP_EventHandler ........................................................................................................... 37 2.49 PP_Send .......................................................................................................................... 38 2.50 PP_Recv .......................................................................................................................... 38 2.51 PP_CloseConnection ...................................................................................................... 39 2.52 PP_FreeSrvHandle ......................................................................................................... 40 2.53 PP_FreePortHandle ........................................................................................................ 40 2.54 PP_Cleanup .................................................................................................................... 41 2.55 PP_Update ...................................................................................................................... 41 2.56 PP_Set_Break ................................................................................................................. 42 2.57 PP_Get_PortCircuitType ................................................................................................ 43 2.58 PP_Set_PortCircuitType ................................................................................................ 43 2.59 PP_EnumIPAddresses .................................................................................................... 44 2.60 PP_Get_PortDelimiter .................................................................................................... 45 2.61 PP_Set_PortDelimiter .................................................................................................... 45 2.62 PP_Get_PortInterByte .................................................................................................... 46 2.63 PP_Set_PortInterByte ..................................................................................................... 46 2.64 PP_Set_ServerDefault .................................................................................................... 47 2.65 PP_ Get_ServerWiredType ............................................................................................ 47
3. Programming Notes .................................................................................................................. 49
IP Serial Server, Programming Library Specification
Page 4 of 49
1. Introduction This document illustrates how IP Serial Server (IPS) communicates with remote manager. The main purpose is to assist users to develop programs to control IPS, especially configuration. Since IPS can function as a server or client for both TCP and UDP connection. The application scenarios are direct IP mode, virtual COM mode, and paired mode. In direct IP and virtual COM modes, IPS should only work as a server. When in the paired mode one IPS must set as a client and the other must set as a server in both TCP and UDP connection. IPS also provides a Probe connection for application or virtual COM to detect whether IPS is still online.
1.1 TCP/UDP Port Numbers and Firewall Please reserve the following port numbers for the IPS operation: 6400 (TCP probe/cmd), 6666(UDP search all), 6669(UDP cmd), and 6690 (UDP search specific). Your attached firewall device shall not block the reserved port numbers mentioned above, or the port numbers specified in TCP/UDP port in Configurations window.
1.2 Related Data Structures typedef unsigned char u8_t;
typedef signed char s8_t;
typedef unsigned short u16_t;
typedef signed short s16_t;
typedef unsigned long u32_t;
typedef signed long s32_t;
struct ip_addr {
u32_t addr;
} ;
struct uartparam_t { //size 112
u16_t portnum; //0
u8_t conntype;
u8_t baud;
u8_t databits;
u8_t stopbits;
u8_t parity;
u8_t flowctrl;
struct ip_addr remoteip; //8
u16_t hb_port;
u16_t c_timeout; //in seconds
u8_t TCP_alive; //0-99 minutes
u8_t circuit_type; //serial port mode
u8_t delimiter1; //HEX, ASCII code for the first delimiter
u8_t delimiter2; //HEX, ASCII code for the second delimiter
u16_t force_transmit; //1-65535 ms
u8_t cc_option; //client connection option, at power up or first character in
u8_t max_conn;
struct ip_addr udpdest_begin[UDPIPRANGE]; //serial to Ethernet //24
struct ip_addr udpdest_end[UDPIPRANGE]; //40
struct ip_addr udpsrc_begin[UDPIPRANGE]; //Ethernet to serial //56
struct ip_addr udpsrc_end[UDPIPRANGE]; //72
u16_t destportnum[UDPIPRANGE]; //88
IP Serial Server, Programming Library Specification
Page 5 of 49
u8_t reserved[13]; //96
u8_t wireless; //109
u8_t inter_p[2]; //110
};
struct config { //size 1974
u8_t config_version;
u8_t dhcp;
char servername[16]; // not used in v 6.0, but used newservername defined below instead.
char serialno[16];
char passwd[16];
struct ip_addr ipaddr, netmask, gw;
u8_t mac_addr[6];
u8_t numports;
u8_t console_mode; //not used in v1.7+
char company[48];
char modelname[16];
char hwID[16];
u8_t reserved4[16]; //for future use
struct uartparam_t uartparam[MAXUARTPORT]; //(size 1792)
char newservername[28];
u8_t reserved6[112-28];
u8_t Default;
u8_t reserved5[15]; //for future use
};
struct cmd_msg {
char pni[24];
char serialno[16];
unsigned char mac_addr[6];
char command[12];
};
struct update_msg {
char pni[22];
u8_t flag;
u8_t macflag;
u8_t macaddr[6];
u8_t seq;
};
struct snd_msg {
u8_t flag;
u8_t macaddr[6];
u8_t seq;
char msg[24];
};
struct pbuf {
struct pbuf *next;
IP Serial Server, Programming Library Specification
Page 6 of 49
/* high 4 bits, flags, low 4 bits reference count */
u8_t flags, ref;
void *payload;
/* Total length of buffer + additionally chained buffers. */
u16_t tot_len;
/* Length of this buffer. */
u16_t len;
void *payload_orig;
u16_t dummy;
};
struct finder_state {
struct udp_pcb *pcb;
struct pbuf *p;
struct pbuf *p_out;
u16_t portnum;
unsigned char *mac_addr;
u8_t sum;
u8_t seq;
u16_t recvlen;
};
struct uartstatus_t { //size 48
u32_t serial_tx;
u32_t serial_rx;
u8_t connstatus;
u8_t mcr;
u8_t msr;
u8_t connnum;
struct ip_addr connectedip[MAXCONN];
u8_t reserved[4]; //for future use
};
struct config_status { //size 836
char version[8];
char builtdate[16];
u32_t ethernet_tx;
u32_t ethernet_rx;
u8_t linkstatus;
u8_t unittype; //not used in v1.7+
u8_t reserved2; //for future use
u8_t reserved3; //for future use
u8_t reserved4[16]; //for future use
struct uartstatus_t uartstatus[MAXUARTPORT];
u8_t reserved5[16]; //for future use
};
IP Serial Server, Programming Library Specification
Page 7 of 49
1.3 Basic management to IP Serial Server
1.3.1 Search the IP Serial Servers To search the IP Serial Servers connected to the network, a user can searches all reachable servers or specify an IP address for searching. IP serial server accepts commands from UDP port 6666 for searching all and port 6690 for the specific address. The following is the command format for searching and illustration by running network monitor tool Ethereal:
Manager → IP Serial Server
pni ending
IPS Administrator '\0'
(format size: 23 bytes, “IPS Administrator ”+ '\0')
When IP serial server receives a string “IPS Administrator”, a data structure, named “config” and defined in 1.3, will be sent for response. But check the response format and sequence:
Step 1: IP Serial Server → Manager
flag mac_addr seq struct config
P Server’s mac 0 Size=1000 bytes
Step 2: IP Serial Server → Manager
flag mac_addr seq struct config
P Server’s mac 1 Size=974 bytes
Step 3: IP Serial Server → Manager
flag mac_addr seq config_status sum
P Server’s mac 2 Size=836 bytes finder_state.sum
1.3.2 Reset the IP Serial Server As to reset, similar to searching, create a socket and turn on broadcast mode for this socket with UDP port 6669 then send a command message in format like “cmd_msg” defined in 1.3.The following is an example to set cmd_msg.
Manager → IP Serial Server pni serialno mac_addr command ending
IPS Administrator Server’s serial number Server’s mac reset '\0'
(format size:59 bytes, cmd_msg+ '\0')
1.3.3 Configure the IP Serial Server settings Follow the following steps to update the IP serial server’s configuration: Step1: Managers should ask the servers to clear the configuration buffer first. Also, IP serial servers accept
commands from UDP port 6666 for searching all and port 6690 for the specific address. A command
IP Serial Server, Programming Library Specification
Page 8 of 49
message is like the following:
Manager → IP Serial Server pni serialno mac_addr command ending
IPS Administrator Server’s serial number Server’s mac clrCfgBuf '\0'
(format size:59 bytes, cmd_msg+ '\0')
Step2: After step1, send update message with configuration data concatenated, and set update message as the
following:
Manager → IP Serial Server
Pni flag macflag mac_addr seq Configuration data concatenated
IPS Administrator 0x7f 0 Server’s mac 1or2 Size<=1000 bytes
|-------------------------------------->format size:31 bytes<-----------------------------|
Note that since the size of “struct config” is 1974 bytes, we should send twice to finish this update job, and flag “seq” is used for sequence number.
Step3: If the IP serial server receives message stated above, server will respond a receive message: IP Serial Server -> Manager
flag mac_addr seq msg
P Server’s mac 0 Receive config
(size:32 bytes)
1.3.4 Monitor function If users try to monitor an IP serial server, it’s just like the same way of searching by the specific address.
1.4 How to send the serial setting commands IP serial server provides the Probe connection for the application or virtual COM with TCP port 6400. Normally this connection is used to detect whether IP serial server is still online, and it can be used to send the command to the IP serial server to change the server parameters as well. Please check the following notes first, 1) You have to use TCP connection if you want Probe, 2) The IP serial server runs as the server, and your application runs as the client, 3) Here we assume the given IP address has a real IP serial server, and don't try to verify the server /
version, 4) Currently we allow the end-user to send four kinds of commands below,
setbaud, setline, setflow, and setmcrlcr. 5) The structure vcm_msg is used for sending these commands. The structure mcrlcr_t is used to store
the parameters of setmcrlcr, and vcomparam_t is used to store the parameters for other 3 commands, 6) The sample code is based on WinSock, and it's easy to apply to other platforms. Also, instead of TCP, a connection with UDP port 6669 is allowed to send the serial setting commands by
IP Serial Server, Programming Library Specification
Page 9 of 49
the note above.
1.4.1 Related Data Structures
#define PROBE_PORT 6400
#define MCR_DTR 0x01
#define MCR_RTS 0x02
struct vcomparam_t {
UCHAR baud;
UCHAR databits;
UCHAR stopbits;
UCHAR parity;
UCHAR flowctrl;
};
struct mcrlcr_t {
UCHAR mcr_msr;
UCHAR lcr_lsr;
};
struct vcom_msg {
char pni[24];
char command[12];
unsigned short udp_port;
struct vcomparam_t vcomparam; //using command "setbaud", "setline", "setflow"
struct mcrlcr_t mcrlcrparam; //using command "setmcrlcr"
};
struct sockaddr_in serial_server_data_address;
struct sockaddr_in serial_server_probe_address;
1.4.2 Major Steps with sample code
1) Initialize use of the WinSock.
WORD wVersionRequested;
WSADATA wsaData;
wVersionRequested = MAKEWORD( 1, 1 );
WSAStartup( wVersionRequested, &wsaData );
2) Scanning out multiple network cards and individually bind the specific card to search the wired/wireless
serial servers.
3) Create the socket for the client.
data_sockfd = socket(AF_INET, SOCK_STREAM, 0);
probe_sockfd = socket(AF_INET, SOCK_STREAM, 0);
IP Serial Server, Programming Library Specification
Page 10 of 49
4) Name the socket as agreed with the server.
serial_server_data_address.sin_family = AF_INET;
serial_server_data_address.sin_port = serial_server_port;
serial_server_data_address.s_addr = serial_server_ipaddress;
serial_server_data_address_size = sizeof(serial_server_data_address);
serial_server_probe_address.sin_family = AF_INET;
serial_server_probe_address.sin_port = PROBE_PORT;
serial_server_probe_address.s_addr = serial_server_ipaddress;
serial_server_probe_address_size = sizeof(serial_server_probe_address);
5) Connect the socket to the IP serial server's socket.
connect(data_sockfd, (sockaddr *)&serial_server_data_address, serial_server_data_address_size);
connect(probe_sockfd, (sockaddr *)&serial_server_probe_address, serial_server_probe_address_size);
6) Send the command setmcrlcr via probe_sockfd.
struct vcom_msg SendParams;
memset(&SendParams,0,sizeof(struct vcom_msg));
strcpy(SendParams.pni, "IPS Administrator ");
strcpy(SendParams.command, "setmcrlcr");
SendParams.mcrlcrparam.mcr_msr = 0;
if (SET_DTR_ON)
SendParams.mcrlcrparam.mcr_msr |= MCR_DTR;
if (SET_RTS_ON)
SendParams.mcrlcrparam.mcr_msr |= MCR_RTS;
send(probe_sockfd, (const char *)&SendParams, sizeof(vcom_msg), 0);
7) Close the socket
closesocket(serial_server_data_address);
closesocket(serial_server_probe_address);
8) Terminate use of the WinSock.
WSACleanup();
IP Serial Server, Programming Library Specification
Page 11 of 49
2. Programming library This is about the programming interface to communicate with IP Serial Server. The application developers can follow the function prototypes and relevant data structures to program for accessing IP Serial Server services, especially configuration setting.
----------------------------------------------------------------------------------------------------------------------------------
2.1 PP_Startup Initiate use of Windows Sockets, allows an application or DLL to specify the version of Windows Sockets required and retrieve details of the specific Windows Sockets implementation.
int PP_Startup (
void
);
Parameters:
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Startup must be the first function called prior to other functions.
Example:
if(PP_Startup() == PP_ERROR)
{
//Startup failed.
}
2.2 PP_Search Search the IP Serial Servers connected to the network. User can search all reachable servers or specify a IP Address for searching.
serverhandle_t * PP_Search(
int *listnum,
BOOL bSearchAll = TRUE,
char *IPAddress = NULL
);
Parameters: listnum
[out] The number of found IP Serial Servers.
bSearchAll
[in] TRUE: Means search all reachable servers.
FALSE: Means search specific server. IPAddress must be assigned in such situation.
IPAddress
[in] The specific server’s IP Address. Ignored if bSearchAll is TRUE.
Return Values:
IP Serial Server, Programming Library Specification
Page 12 of 49
PP_Search return all found IP Serial Server list in the ipserver_t structure, NULL if no any server is found or
error occurs.
Remarks:
Example: serverhandle_t * serverlist;
int listnum;
//Search all reachable servers.
if( (serverlist = PP_Search(&listnum)) == NULL )
{
//PP_Search failed.
}
//Search a specific server.
char *IPAddress = “192.168.0.1”
if( (serverlist = PP_Search(&listnum, FALSE, IPAddress)) == NULL )
{
//PP_Search failed.
}
2.3 PP_GetSrvHandle Get the IP Serial Server’s handle pointing to the ipserver _t structure.
serverhandle_t * PP_GetSrvHandle (
char *IPAddress,
void *SERVERLIST
);
Parameters: IPAddress
[in] IP Serial Server IP address.
SERVERLIST [in] All IP Serial Server list in the ipserver_t structure.
Return Values: PP_GetSrvHandle return found IP Serial Server handle in the ipserver_t structure, NULL if the server is not
found or error occurs.
Remarks: PP_GetSrvHandle can get the handle from the serverlist returned from PP_Search call.
Example:
serverhandle_t *serverhandle;
char *temp_IPAddr = “192.168.0.1” //indicate the ip address of the server ;
if( (serverhandle = PP_GetSrvHandle(temp_IPAddr, serverhandle))
== NULL )
{
IP Serial Server, Programming Library Specification
Page 13 of 49
//PP_ GetSrvHandle failed.
}
2.4 PP_Get_ServerName Get the IP Serial Server’s name.
int PP_Get_ServerName ( serverhandle_t *ServerHandle,
char *ServerName
);
Parameters: ServerHandle
[in] IP Serial Server handle in the ipserver_t structure.
ServerName [out] IP Serial Server’s name.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
char servername[30];
if(PP_Get_ServerName(serverhandle, servername) == PP_ERROR)
{
//PP_Get_ServerName failed.
}
2.5 PP_Set_ServerName Set the IP Serial Server’s name.
int PP_Set_ServerName (
serverhandle_t *ServerHandle,
char *ServerName
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
ServerName [in] IP Serial Server’s new name.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
IP Serial Server, Programming Library Specification
Page 14 of 49
Example: char servername[30];
if(PP_Set_ServerName(serverhandle, servername) == PP_ERROR)
{
//PP_Set_ServerName failed.
}
2.6 PP_Get_ServerSerialno Get the IP Serial Server’s serial number.
int PP_Get_ServerSerialno ( serverhandle_t *ServerHandle,
char *Serialno
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
Serialno [out] IP Serial Server’s serial number.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example: char serialno [16];
if(PP_Get_ ServerSerialno (serverhandle, serialno) == PP_ERROR)
{
//PP_Get_ ServerSerialno failed.
}
2.7 PP_Get_ServerPasswd Get the IP Serial Server’s password.
int PP_Get_ServerPasswd ( serverhandle_t *ServerHandle,
char *Passwd
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
Passwd [out] IP Serial Server’s password.
IP Serial Server, Programming Library Specification
Page 15 of 49
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
char passwd [16];
if(PP_Get_ ServerPasswd (serverhandle, passwd) == PP_ERROR)
{
//PP_Get_ ServerPasswd failed.
}
2.8 PP_Set_ServerPasswd Set the IP Serial Server’s password.
int PP_Set_ServerPasswd ( serverhandle_t *ServerHandle,
char *Passwd
);
Parameters: ServerHandle
[in] IP Serial Server handle in the ipserver_t structure.
Passwd [in] IP Serial Server’s new password.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks: PP_Reset must be called to make the new setting take effect.
Example: char passwd[16];
if(PP_Set_ ServerPasswd (serverhandle, passwd) == PP_ERROR)
{
//PP_Set_ ServerPasswd failed.
}
2.9 PP_Get_ServerDHCP Get the IP Serial Server’s dhcp.
int PP_Get_ ServerDHCP ( serverhandle_t *ServerHandle,
UCHAR *dhcp
);
IP Serial Server, Programming Library Specification
Page 16 of 49
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
dhcp [out] IP Serial Server’s dhcp.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
UCHAR dhcp;
if(PP_Get_ ServerDHCP (serverhandle, &dhcp) == PP_ERROR)
{
//PP_Get_ ServerDHCP failed.
}
2.10 PP_Set_ServerDHCP Set the IP Serial Server’s dhcp.
int PP_Set_ServerDHCP ( serverhandle_t *ServerHandle,
UCHAR *dhcp
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
dhcp [in] IP Serial Server’s new dhcp
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
Example: UCHAR dhcp;
if(PP_Set_ ServerDHCP (serverhandle, &dhcp) == PP_ERROR)
{
//PP_Set_ ServerDHCP failed.
}
2.11 PP_Get_ServerIPAddr Get the IP Serial Server’s ip address.
IP Serial Server, Programming Library Specification
Page 17 of 49
int PP_Get_ ServerIPAddr ( serverhandle_t *ServerHandle,
char *IPAddr
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
IPAddr [out] IP Serial Server’s ip address.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
char ipaddr[20];
if(PP_Get_ ServerIPAddr (serverhandle, ipaddr) == PP_ERROR)
{
//PP_Get_ ServerIPAddr failed.
}
2.12 PP_Set_ServerIPAddr Set the IP Serial Server’s ip address.
int PP_Set_ServerDHCP ( serverhandle_t *ServerHandle,
char *IPAddr
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
IPAddr [in] IP Serial Server’s new ip address
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
Example: char ipaddr[20];
if(PP_Set_ ServerIPAddr (serverhandle, ipaddr) == PP_ERROR)
IP Serial Server, Programming Library Specification
Page 18 of 49
{
//PP_Set_ ServerIPAddr failed.
}
2.13 PP_Get_ServerNetMask Get the IP Serial Server’s netmask.
int PP_Get_ ServerNetMask ( serverhandle_t *ServerHandle,
char * NetMask
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
NetMask [out] IP Serial Server’s netmask.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
char NetMask [20];
if(PP_Get_ ServerNetMask (serverhandle, NetMask) == PP_ERROR)
{
//PP_Get_ ServerNetMaskfailed failed.
}
2.14 PP_Set_ServerNetMask Set the IP Serial Server’s netmask.
int PP_Set_ ServerNetMask ( serverhandle_t *ServerHandle,
char * NetMask
);
Parameters: ServerHandle
[in] IP Serial Server handle in the ipserver_t structure.
NetMask [in] IP Serial Server’s new netmask
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
IP Serial Server, Programming Library Specification
Page 19 of 49
PP_Reset must be called to make the new setting take effect.
Example:
char NetMask [20];
if(PP_Set_ ServerNetMask (serverhandle, NetMask) == PP_ERROR)
{
//PP_Set_ ServerNetMaskfailed failed.
}
2.15 PP_Get_ServerGW Get the IP Serial Server’s gateway.
int PP_Get_ ServerGW ( serverhandle_t *ServerHandle,
char * GW
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
GW [out] IP Serial Server’s gateway.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
char GW [20];
if(PP_Get_ ServerGW (serverhandle, GW) == PP_ERROR)
{
//PP_Get_ ServerGW failed.
}
2.16 PP_Set_ServerGW Set the IP Serial Server’s GW.
int PP_Set_ ServerGW ( serverhandle_t *ServerHandle,
char * GW
);
Parameters: ServerHandle
[in] IP Serial Server handle in the ipserver_t structure.
GW [in] IP Serial Server’s new gateway
IP Serial Server, Programming Library Specification
Page 20 of 49
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks: PP_Reset must be called to make the new setting take effect.
Example:
char GW [20];
if(PP_Set_ ServerGW (serverhandle, GW) == PP_ERROR)
{
//PP_Set_ ServerGW failed.
}
2.17 PP_Get_ServerConMode Get the IP Serial Server’s console mode (Only in new serial server).
int PP_Get_ ServerConMode ( serverhandle_t *ServerHandle,
UCHAR * ConMode
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
ConMode [out] IP Serial Server’s console mode.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
UCHAR ConMode;
if(PP_Get_ ServerConMode (serverhandle, &ConMode) == PP_ERROR)
{
//PP_Get_ ServerConMode failed.
}
2.18 PP_Set_ServerConMode Set the IP Serial Server’s console mode(only in new serial server).
int PP_Set_ ServerConMode ( serverhandle_t *ServerHandle,
UCHAR * ConMode
);
IP Serial Server, Programming Library Specification
Page 21 of 49
Parameters: ServerHandle
[in] IP Serial Server handle in the ipserver_t structure.
ConMode [in] IP Serial Server’s new console mode
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks: PP_Reset must be called to make the new setting take effect.
Example: UCHAR ConMode;
if(PP_Set_ ServerConMode (serverhandle, & ConMode) == PP_ERROR)
{
//PP_Set_ ServerConMode failed.
}
2.19 PP_Get_ServerCompany Get the IP Serial Server’s company name (Only in new serial server).
int PP_Get_ ServerCompany ( serverhandle_t *ServerHandle,
char * Company
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
Company [out] IP Serial Server’s company name.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
char company[48];
if(PP_Get_ ServerCompany (serverhandle, company) == PP_ERROR)
{
//PP_Get_ ServerCompany failed.
}
IP Serial Server, Programming Library Specification
Page 22 of 49
2.20 PP_Get_ServerModelName Get the IP Serial Server’s model name (Only in new serial server).
int PP_Get_ ServerModelName ( serverhandle_t *ServerHandle,
char * Modelname
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
Modelname [out] IP Serial Server’s model name.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example: char modelname [16];
if(PP_Get_ ServerModelName (serverhandle, modelname) == PP_ERROR)
{
//PP_Get_ ServerModelName failed.
}
2.21 PP_Get_ServerMACAddr Get the IP Serial Server’s MAC address.
int PP_Get_ ServerMACAddr ( serverhandle_t *ServerHandle,
char * MACAddr
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
MACAddr [out] IP Serial Server’s MAC address.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
char MACAddr [20];
IP Serial Server, Programming Library Specification
Page 23 of 49
if(PP_Get_ ServerMACAddr (serverhandle, MACAddr) == PP_ERROR)
{
//PP_Get_ ServerMACAddr failed.
}
2.22 PP_Get_ServerConfigVersion Get the IP Serial Server’s configuration version.
int PP_Get_ ServerConfigVersion ( serverhandle_t *ServerHandle,
UCHAR * cfgversion
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
cfgversion [out] IP Serial Server’s configuration version.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example: UCHAR cfgversion;
if(PP_Get_ ServerConfigVersion (serverhandle, &cfgversion) == PP_ERROR)
{
//PP_Get_ ServerConfigVersion failed.
}
2.23 PP_Get_ServerNumPorts Get the IP Serial Server’s number of uart ports.
int PP_Get_ ServerNumPorts ( serverhandle_t *ServerHandle,
UCHAR * numports
);
Parameters: ServerHandle
[in] IP Serial Server handle in the ipserver_t structure.
numports [out] IP Serial Server’s number of uart ports.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
IP Serial Server, Programming Library Specification
Page 24 of 49
Remarks:
Example:
UCHAR numports;
if(PP_Get_ ServerNumPorts (serverhandle, & numports) == PP_ERROR)
{
//PP_Get_ ServerNumPorts failed.
}
2.24 PP_Reset Reset the IP Serial Server.
int PP_Reset( serverhandle_t *ServerHandle
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
if(PP_Reset(serverhandle) == PP_ERROR)
{
//PP_ Reset failed.
}
2.25 PP_GetPortHandle Get the IP Serial Server’s port handle pointing to the uartport _t structure.
porthandle_t *PP_GetPortHandle (
void *ServerHandle,
int port
);
Parameters: ServerHandle
[in] IP Serial Server handle in the ipserver_t structure.
port
[in] The port position on the IP Serial Server.
Return Values: PP_GetPortHandle return the port handle in the uartport_t structure, NULL if the port is not found or error
occurs.
IP Serial Server, Programming Library Specification
Page 25 of 49
Remarks:
Example:
porthandle_t *porthandle = NULL;
int port = 0; //indicate the port position (from 0 to NumberOfPorts - 1)
if( (porthandle = PP_GetPortHandle(serverhandle, port)) == NULL )
{
//PP_ GetSrvHandle failed.
}
2.26 PP_Get_PortConnectType Get the port’s connect type.
int PP_Get_PortConnectType ( porthandle_t *PortHandle,
conntype_t *ConnectType
);
Parameters: PortHandle
[in] Port handle in the uartport_t structure.
ConnectType [out] Port’s connect type.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example: conntype_t ConnectType;
if(PP_Get_PortConnectType(PortHandle, &ConnectType ) == PP_ERROR)
{
//PP_ Get_ PortConnectType failed.
}
2.27 PP_Set_PortConnectType Set the port’s connect type.
int PP_Set_PortConnectType ( porthandle_t *PortHandle,
conntype_t *ConnectType
);
Parameters: PortHandle
[in] Port handle in the uartport_t structure.
ConnectType
IP Serial Server, Programming Library Specification
Page 26 of 49
[in] Port’s new connect type.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
Example:
conntype_t ConnectType;
if(PP_Set_PortConnectType(PortHandle, &ConnectType ) == PP_ERROR)
{
//PP_ Set_ PortConnectType failed.
}
2.28 PP_Get_PortBaudrate Get the port’s baud rate.
int PP_Get_PortBaudrate ( porthandle_t *PortHandle,
baudrate_t *Baudrate
);
Parameters: PortHandle
[in] Port handle in the uartport_t structure.
Baudrate [out] Port’s baud rate.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example: baudrate_t baudrate;
if(PP_Get_ PortBaudrate (PortHandle, & baudrate) == PP_ERROR)
{
//PP_ Get_ PortBaudrate failed.
}
2.29 PP_Set_PortBaudrate Set the port’s baud rate.
int PP_Set_PortBaudrate ( porthandle_t *PortHandle,
baudrate_t *Baudrate
IP Serial Server, Programming Library Specification
Page 27 of 49
);
Parameters:
PortHandle [in] Port handle in the uartport _t structure.
Baudrate [in] Port’s new baud rate.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
Example:
baudrate_t baudrate;
if(PP_Set_PortBaudrate (PortHandle, & baudrate) == PP_ERROR)
{
//PP_ Set_ PortBaudrate failed.
}
2.30 PP_Get_PortDatabits Get the port’s databits.
int PP_Get_ PortDatabits ( porthandle_t *PortHandle,
databits_t * Databits
);
Parameters: PortHandle
[in] Port handle in the uartport_t structure.
Databits [out] Port’s databits.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
databits_t databits;
if(PP_Get_PortDatabits (PortHandle, &databits ) == PP_ERROR)
{
//PP_ Get_ PortDatabits failed.
}
IP Serial Server, Programming Library Specification
Page 28 of 49
2.31 PP_Set_PortDatabits Set the port’s databits.
int PP_Set_ PortDatabits ( porthandle_t *PortHandle,
databits_t *Databits
);
Parameters:
PortHandle [in] Port handle in the uartport_t structure.
Databits [in] Port’s new databits.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
Example:
databits_t databits;
if(PP_Set_ PortDatabits (PortHandle, &databits ) == PP_ERROR)
{
//PP_ Set_ PortDatabits failed.
}
2.32 PP_Get_PortStopbits Get the port’s stopbits.
int PP_Get_PortStopbits ( porthandle_t *PortHandle,
stopbits_t * Stopbits
);
Parameters: PortHandle
[in] Port handle in the uartport_t structure.
Stopbits [out] Port’s stopbits.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
stopbits_t stopbits;
IP Serial Server, Programming Library Specification
Page 29 of 49
if(PP_Get_ PortStopbits (PortHandle, &stopbits ) == PP_ERROR)
{
//PP_ Get_ PortStopbits failed.
}
2.33 PP_Set_PortStopbits Set the port’s stopbits.
int PP_Set_PortStopbits ( porthandle_t *PortHandle,
stopbits_t *Stopbits
);
Parameters: PortHandle
[in] Port handle in the uartport_t structure.
Stopbits [in] Port’s new stopbits.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
Example:
stopbits_t stopbits;
if(PP_Set_ PortStopbits (PortHandle, &stopbits ) == PP_ERROR)
{
//PP_ Set_ PortStopbits failed.
}
2.34 PP_Get_PortParity Get the port’s parity.
int PP_Get_PortParity ( porthandle_t *PortHandle,
parity_t * Parity
);
Parameters:
PortHandle [in] Port handle in the uartport_t structure.
Parity [out] Port’s parity.
Return Values:
PP_SUCCESS OK
IP Serial Server, Programming Library Specification
Page 30 of 49
PP_ERROR FAIL
Remarks:
Example: parity_t parity;
if(PP_Get_PortParity (PortHandle, &parity ) == PP_ERROR)
{
//PP_ Get_ PortParity failed.
}
2.35 PP_Set_PortParity Set the port’s parity.
int PP_Set_PortParity ( porthandle_t *PortHandle,
parity_t *Parity
);
Parameters: PortHandle
[in] Port handle in the uartport_t structure.
Parity [in] Port’s new parity.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
Example:
parity_t parity;
if(PP_Set_PortParity (PortHandle, &parity ) == PP_ERROR)
{
//PP_ Set_ PortParity failed.
}
2.36 PP_Get_PortFlowctrl Get the port’s flow control.
int PP_Get_PortFlowctrl ( porthandle_t *PortHandle,
flowctrl_t * Flowctrl
);
Parameters:
PortHandle
IP Serial Server, Programming Library Specification
Page 31 of 49
[in] Port handle in the uartport_t structure.
Flowctrl [out] Port’s flow control.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example: flowctrl_t flowctrl;
if(PP_Get_PortFlowctrl (PortHandle, &flowctrl ) == PP_ERROR)
{
//PP_Get_PortFlowctrl failed.
}
2.37 PP_Set_PortFlowctrl Set the port’s flow control.
int PP_Set_PortFlowctrl ( porthandle_t *PortHandle,
flowctrl_t *Flowctrl
);
Parameters: PortHandle
[in] Port handle in the uartport_t structure.
Flowctrl [in] Port’s new flow control.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
Example:
flowctrl_t flowctrl;
if(PP_Set_PortFlowctrl (PortHandle, &flowctrl ) == PP_ERROR)
{
//PP_ Set_PortFlowctrl failed.
}
2.38 PP_Get_PortRemoteIP Get the port’s remote ip address.
int PP_Get_PortRemoteIP (
IP Serial Server, Programming Library Specification
Page 32 of 49
porthandle_t *PortHandle,
char *RemoteIP
);
Parameters: PortHandle
[in] Port handle in the uartport_t structure.
RemoteIP [out] Port’s remote ip address.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example: char remoteip[20];
if(PP_Get_PortRemoteIP (PortHandle, remoteip) == PP_ERROR)
{
//PP_ Get_ PortRemoteIP failed.
}
2.39 PP_Set_PortRemoteIP Set the port’s remote ip address.
int PP_Set_PortRemoteIP ( porthandle_t *PortHandle,
char *RemoteIP
);
Parameters: PortHandle
[in] Port handle in the uartport_t structure.
RemoteIP [in] Port’s new remote ip address.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
Example:
char remoteip[20];
if(PP_Set_PortRemoteIP (PortHandle, remoteip) == PP_ERROR)
{
//PP_ Set_PortRemoteIP failed.
IP Serial Server, Programming Library Specification
Page 33 of 49
}
2.40 PP_Get_PortTimeout Get the port’s timeout value.
int PP_Get_PortTimeout ( porthandle_t *PortHandle,
UCHAR *Timeout
);
Parameters: PortHandle
[in] Port handle in the uartport_t structure.
Timeout [out] Port’s timeout value.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example: UCHAR Timeout;
if(PP_Get_PortTimeout (PortHandle, &Timeout) == PP_ERROR)
{
//PP_ Get_ PortTimeout failed.
}
2.41 PP_Set_PortTimeout Set the port’s timeout value.
int PP_Set_PortTimeout ( porthandle_t *PortHandle,
UCHAR *Timeout
);
Parameters:
PortHandle [in] Port handle in the uartport_t structure.
Timeout [in] Port’s new timeout value.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
IP Serial Server, Programming Library Specification
Page 34 of 49
Example:
UCHAR Timeout;
if(PP_Set_PortTimeout (PortHandle, &Timeout) == PP_ERROR)
{
//PP_ Set_PortTimeout failed.
}
2.42 PP_Get_PortNum Get the port’s port number.
int PP_Get_PortNum ( porthandle_t *PortHandle,
int *PortNum
);
Parameters:
PortHandle [in] Port handle in the uartport_t structure.
PortNum [out] Port’s port number.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example: long portnum;
if(PP_Get_PortNum (PortHandle, &portnum) == PP_ERROR)
{
//PP_Get_PortNum failed.
}
2.43 PP_Set_PortNum Set the port’s port number.
int PP_Set_PortNum ( porthandle_t *PortHandle,
int *PortNum
);
Parameters:
PortHandle [in] Port handle in the uartport_t structure.
PortNum [in] Port’s new port number.
IP Serial Server, Programming Library Specification
Page 35 of 49
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks: PP_Reset must be called to make the new setting take effect.
Example:
Long portnum;
if(PP_Set_PortNum (PortHandle, &portnum) == PP_ERROR)
{
//PP_Set_PortNum failed.
}
2.44 PP_Set_DTR_RTS Set the port’s DTR/RTS.
int PP_Set_DTR_RTS ( porthandle_t *PortHandle,
BOOL DTR_ON,
BOOL RTS_ON
);
Remarks:
PP_Reset must be called to make the new setting take effect.
Parameters:
PortHandle [in] Port handle in the uartport_t structure.
DTR_ON [in] TRUE: DTR ON; FALSE: DTR OFF.
RTS_ON [in] TRUE: RTS ON; FALSE: RTS OFF.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Example:
BOOL DTR_ON = TRUE, RTS_ON = TRUE;
if(PP_Set_DTR_RTS(PortHandle, DTR_ON, RTS_ON) == PP_ERROR)
{
//PP_Set_DTR_RTS failed.
}
2.45 PP_InitConnection Initialize the sockaddr_in structure and create the socket in the port handle, and save the useprobe flag, it will decide the TCP/UDP protocol according to the port’s connect type.
IP Serial Server, Programming Library Specification
Page 36 of 49
int PP_InitConnection( porthandle_t *PortHandle,
BOOL useprobe
);
Parameters: PortHandle
[in/out] The port handle in the uartport_t structure.
useprobe
[in] useprobe or not, use if TRUE, not use if FALSE.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_ InitConnection should be executed prior to PP_Connect, if useprobe is TRUE, probe socket , which is
transparent to users, is created too.
Example: BOOL useprobe = TRUE;
if(PP_InitConnection(porthandle, useprobe) == PP_ERROR)
{
//PP_ InitConnection failed.
}
2.46 PP_Connect Establish a connection to a specified port.
int PP_Connect( porthandle_t *PortHandle
);
Parameters:
PortHandle [in] The port handle in the uartport_t structure.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
If useprobe is TRUE, and probe connection (which is transparent to users) is established, and then a thread
(which will automatically do the probe testing) will start running. If the connection is lost, the thread will
automatically reconnect it.
Example: if(PP_ Connect (porthandle) == PP_ERROR)
{
//PP_ Connect failed.
IP Serial Server, Programming Library Specification
Page 37 of 49
}
2.47 PP_SetEventHandlers Specify the function that should be called when connection is created and down.
int PP_SetEventHandlers ( porthandle_t *PortHandle,
int (* ConnectedEventHandler)( void *context),
int (* ReconnectingEventHandler)( void *context),
int (* DisconnectedEventHandler)( void *context),
void *context
);
Parameters:
PortHandle [in] The port handle in the uartport_t structure.
ConnectedEventHandler [in] The callback function when connection is created.
ReconnectingEventHandler [in] The callback function when reconnecting is being tried.
DisconnecedtEventHandler [in] The callback function when connection is down.
context [in] Callback context.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example: int connected(void *context){}
int reconnecting(void *context){}
int disconnected(void *context){}
void *context;
if(PP_SetEventHandlers(porthandle, connected, reconnecting, disconnected, context) == PP_ERROR)
{
//PP_ SetEventHandlers failed.
}
2.48 PP_EventHandler The prototype for the callback function. Users can decide their own actions inside these callback functions, the simplest one is just print a message.
int PP_EventHandler ( void *context
);
Parameters:
IP Serial Server, Programming Library Specification
Page 38 of 49
context [in] callback_context, originally specified by the user in the PP_SetEventHandlers().
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
Sample code.
2.49 PP_Send Send data to a specified port, it will decide the TCP/UDP protocol according to the port’s connect type.
int PP_Send( porthandle_t *PortHandle,
char *buf,
int length
);
Parameters:
PortHandle [in] The port handle in the uartport_t structure.
buf [in] Buffer containing the data to be transmitted.
length [in] Length of the data in buf, in bytes.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example: char *buf = “Testing the function PP_Send!”;
int length = strlen(buf);
if(PP_Send(porthandle, buf, length) == PP_ERROR)
{
//PP_ Send failed.
}
2.50 PP_Recv Receive data from a specified port, it will decide the TCP/UDP protocol according to the port’s connect type. User can specify whether to run this routine in block mode or in non-block mode by setting bBlock with different values.
int PP_Recv( porthandle_t *PortHandle,
IP Serial Server, Programming Library Specification
Page 39 of 49
char *buf,
int *length,
BOOL bBlock = TRUE
);
Parameters: PortHandle
[in] The port handle in the uartport_t structure.
buf [in/out] Buffer for the incoming data.
length [in/out] Length of the data in buf, in bytes.
bBlock
[in] TRUE: Means run this routine in block mode.
FALSE: Means run this routine in non-block mode.
If the socket is not readable in non-block mode, return value will be PP_ERRWILLBLOCK.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
PP_ERRWILLBLOCK Error, will block in non-block mode
Remarks:
Example:
char buf[MAX_RECV_BUFFER];
int length = MAX_RECV_BUFFER;
//Receive in block mode
if(PP_Recv(porthandle, buf, &length) == PP_ERROR)
{
//PP_ Recv failed.
}
//Receive in non-block mode
int ret = PP_Recv(porthandle, buf, &length);
if(ret == PP_ERROR)
{
//PP_ Recv failed.
}
else if(ret == PP_ERRWILLBLOCK)
{
//No data is available now.
}
2.51 PP_CloseConnection Close existing sockets of a port.
int PP_CloseConnection( porthandle_t *PortHandle
);
IP Serial Server, Programming Library Specification
Page 40 of 49
Parameters:
PortHandle [in] The port handle in the uartport_t structure.
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_CloseConnection will also close the probe socket associated with the data socket if the probe socket is
created.
Example:
if(PP_CloseConnection(porthandle) == PP_ERROR)
{
//PP_ CloseConnection failed.
}
2.52 PP_FreeSrvHandle Free the memory resources allocated for the server handle, should be called if a server handle will not be used again.
void PP_FreeSrvHandle ( serverhandle_t **pServerHandle
);
Parameters: pServerHandle
[in/out] pointer to IP Serial Server handle in the ipserver_t structure.
Return Values:
Remarks: PP_ FreeSrvHandle should be executed prior to PP_Cleanup, after execution, the server handle is set to NULL.
Example:
PP_ FreeSrvHandle (pServerHandle)
2.53 PP_FreePortHandle Free the memory resources allocated for the port handle, should be called if a port handle will not be used again.
void PP_FreePortHandle ( porthandle_t **pPortHandle
);
Parameters: pPortHandle
[in/out] pointer to uart port handle in the uartport_t structure.
IP Serial Server, Programming Library Specification
Page 41 of 49
Return Values:
Remarks:
PP_ FreePortHandle should be executed prior to PP_Cleanup, after execution, the port handle is set to NULL.
Example:
PP_ FreePortHandle (pPortHandle)
2.54 PP_Cleanup Terminate use of the Windows Sockets, free any resources allocated on behalf of the application or DLL.
int PP_Cleanup (
void
);
Parameters:
Return Values: PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Cleanup is the last function to call by the application or DLL.
Example: //should call PP_FreeSrvHandle and PP_FreePortHandle first.
PP_FreeSrvHandle(&serverhandle);
PP_FreePortHandle(&porthandle);
if(PP_Cleanup() == PP_ERROR)
{
//PP_ Cleanup failed.
}
2.55 PP_Update Upgrade the ip serial server according to the ipserver_t stucture parameter.
serverhandle_t * PP_Search(
const struct ipserver_t *pServer,
BOOL BroadCast,
char *IPAddress
);
Parameters:
pServer [in] The configuration of IP Serial Server to update.
bSearchAll
[in] TRUE: Means BroadCast mode.
FALSE: Means for specific server. IPAddress must be assigned in such situation.
IP Serial Server, Programming Library Specification
Page 42 of 49
IPAddress
[in] The specific server’s IP Address. Ignored if bSearchAll is TRUE.
Return Values:
SUCCESS or ERROR (FAIL).
Remarks:
Example:
const struct ipserver_t *pServer ;
int listnum;
char *IPAddress = “192.168.0.1”
if( !PP_Update(pServer) )
{
// failed.
}
// a specific server.
char *IPAddress = “192.168.0.1”
if( (!PP_Update (pServer, FALSE, IPAddress) )
{
// failed.
}
2.56 PP_Set_Break Set the port’s Break.
int PP_Set_Break ( porthandle_t *PortHandle,
BOOL BREAK_ON,
);
Remarks:
PP_Reset must be called to make the new setting take effect.
Parameters:
PortHandle [in] Port handle in the uartport_t structure.
BREAK_ON [in] TRUE: BREAK ON; FALSE: BREAK OFF.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Example: BOOL BREAK_ON = TRUE;
if(PP_Set_Break(PortHandle, BREAK_ON) == PP_ERROR)
{
IP Serial Server, Programming Library Specification
Page 43 of 49
// PP_Set_Break failed.
} 2.57 PP_Get_PortCircuitType Get the port’s circuit type.
int PP_Get_PortConnectType ( porthandle_t *PortHandle,
circuit_t *CircuitType);
Parameters:
PortHandle [in] Port handle in the uartport_t structure.
CircuitType [out] Port’s circuit type.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
circuit_t CircuitType;
if(PP_Get_PortCircuitType(PortHandle, &CircuitType ) == PP_ERROR)
{
//PP_ Get_ PortCircuitType failed.
}
2.58 PP_Set_PortCircuitType Set the port’s circuit type.
int PP_Set_PortCircuittType ( porthandle_t *PortHandle,
circuit_t *CircuitType
);
Parameters:
PortHandle [in] Port handle in the uartport_t structure.
CircuitType [in] Port’s new circuit type.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
IP Serial Server, Programming Library Specification
Page 44 of 49
Example:
circuit_t CircuitType;
if(PP_Set_PortCircuitType(PortHandle, &CircuitType ) == PP_ERROR)
{
//PP_ Set_ PortCircuitType failed.
}
2.59 PP_EnumIPAddresses
Enumerate IP Addresses from the serverhandle list
int PP_EnumIPAddresses(
serverhandle_t* ServerHdlList,
int iID,
char * szKey,
int * pSizeOfKey)
Parameters:
ServerHdlList
[in] a pointer to the list of Serverhandle
ID
[in] The index of the value to be retrieved.
This parameter should be zero for the first call to the PP_EnumIPAddress function
and then be incremented for subsequent calls.
szKey
[in/out] a pointer to a buffer that receives the IP Address of the server as a null-terminated string. This
buffer created by application and the size is at least PP_MAX_IPADDR_VALUE.
pSizeOfKey [in/out] a pointer to a variable that specifies the size of the buffer pointed to by the
szKey parameter, in characters. When the function returns, the variable receives
the number of characters stored in the buffer, not including the terminating null
character.
Return Values: PP_SUCCESS. OK
PP_ERROR FAIL
PP_ERROR_NO_MORE_ITEMS NO MORE VALUE AVAIABLE
PP_ERROR_MORE_DATA. SZKEY BUFFER IS NOT LARGE ENOUGH
IP Serial Server, Programming Library Specification
Page 45 of 49
2.60 PP_Get_PortDelimiter Get the port’s delimiters.
int PP_Get_PortConnectType ( porthandle_t *PortHandle,
UCHAR *delimiter1,
UCHAR *delimiter2);
Parameters:
PortHandle [in] Port handle in the uartport_t structure.
Delimiter1 [out] Port’s delimiter1.
Delimiter2 [out] Port’s delimiter2.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
UCHAR Delimiter1, Delimiter2;
if(PP_Get_PortDelimiter (PortHandle, &Delimiter1, &Delimiter2 ) == PP_ERROR)
{
//PP_ Get_ PortDelimiter failed.
}
2.61 PP_Set_PortDelimiter Set the port’s delimiter.
int PP_Set_PortDelimiter ( porthandle_t *PortHandle,
UCHAR *delimiter1,
UCHAR *delimiter2);
Parameters:
PortHandle [in] Port handle in the uartport_t structure.
Delimiter1 [in] Port’s new delimiter1.
Delimiter2 [in] Port’s new delimiter2.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
IP Serial Server, Programming Library Specification
Page 46 of 49
Remarks: PP_Reset must be called to make the new setting take effect.
Example: UCHAR; delimiter1, delimiter2;
if(PP_Set_PortDelimiter(PortHandle, &Delimiter1, &Delimiter2 ) == PP_ERROR)
{
//PP_ Set_ PortDelimiter failed.
}
2.62 PP_Get_PortInterByte Get the port’s InterByte.
int PP_Get_PortInterByte ( porthandle_t *PortHandle,
WORD *InterByte)
Parameters:
PortHandle [in] Port handle in the uartport_t structure.
InterByte [out] Port’s InterByte.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
WORD InterByte;
if(PP_Get_PortInterByte(PortHandle, &InterByte ) == PP_ERROR)
{
//PP_ Get_ PortInterByte failed
}
2.63 PP_Set_PortInterByte Set the port’s InterByte.
int PP_Set_PortInterByte ( porthandle_t *PortHandle,
WORD *InterByte
);
Parameters: PortHandle
[in] Port handle in the uartport_t structure.
WORD
IP Serial Server, Programming Library Specification
Page 47 of 49
[in] Port’s new InterByte.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
PP_Reset must be called to make the new setting take effect.
Example:
WORD InterByte;
if(PP_Set_PortInterByte(PortHandle, &InterByte ) == PP_ERROR)
{
//PP_ Set_ PortInterByte failed.
}
2.64 PP_Set_ServerDefault Set the server’s default setting.
int PP_Set_ServerDefault (
serverhandle_t *ServerHandle
);
Parameters:
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks: PP_Reset must be called to make the new setting take effect.
Example:
if( PP_Set_ServerDefault (ServerHandle ) == PP_ERROR)
{
//PP_ Set_ ServerDefault failed.
}
2.65 PP_ Get_ServerWiredType Get the server’s wired/wireless type.
int PP_Get_ServerWiredType(
serverhandle_t *ServerHandle,
UCHAR *WireType);
Parameters:
IP Serial Server, Programming Library Specification
Page 48 of 49
ServerHandle [in] IP Serial Server handle in the ipserver_t structure.
WiredType
[out] Server wired/wireless type wired: 0, wireless : 1
Return Values:
PP_SUCCESS OK
PP_ERROR FAIL
Remarks:
Example:
UCHAR WiredType;
If (PP_Get_ServerWiredType (ServerHandle, &WiredType) == PP_ERROR)
{
//PP_ Get_ServerWiredType failed.
}
IP Serial Server, Programming Library Specification
Page 49 of 49
3. Programming Notes
When developing a program IP Serial Server Programming Library with Visual C/C++, you must do the following:
During programming, include header file "ipssp.h" into your source files. When linking, add file "ipserial.lib" into your library list. Copy file "ipserial.dll" to the directory where your application execution file exists Make sure the ipssp.h and ipserial.lib are in searching path.
The sample program illustrates codes for IP Serial Server Programming Library calls in C language.