TCP/IP Application Programmer's Interface - SC12 @CHIP-RTOS V1.10
IPC@CHIP Documentation Index
TCP/IP API News
TCP/IP API
This interface provides access to the IPC@CHIP TCP/IP stack's socket interface
for programming TCP/IP applications. The TCP/IP API are all
reached though software interrupt 0xAC. The desired service is selected with
the high order byte of the AX register (AH).
Please note, that we cannot explain the entire functionality of the TCP/IP protocol and
the working of the socket interface in this document. Good books for understanding
TCP/IP and the socket interface are:
1. Internetworking with TCP/IP, Volume 1-3 from Douglas E.Comer
2. TCP/IP Illustrated, Volume 1 from W. Richard Stevens
For some useful comments see Programming notes.
All needed constants (e.g. API_OPENSOCKET) and data structures are defined in the header
file tcpipapi.h.
TCP/IP API News
TCP/IP API Error Codes Listing
TCP/IP API Developer Notes
TCP/IP API Data Structures
TCP/IP API Client/Server applications
Notes
:
- "Network byte order" is big endian (like Motorola machines, unlike Intel),
where most significant byte appears at the lowest address byte of a multibyte
integer.
- At return of most API the DX-Register is used for error checking:
DX: = 0 =API_ENOERROR ==> success
DX: = -1 =API_ERROR ==> error, AX contains error code
API Functions
:
Interrupt 0xAC service 0x01: API_OPENSOCKET, open a socket
- Creates an end-point for communication
and returns a socket descriptor (i.e. a handle).
Parameters
- AH
- 0x01 (= API_OPENSOCKET)
- AL
- type of socket :
AL = 1 (= SOCK_STREAM) ==> TCP
AL = 2 (= SOCK_DGRAM) ==> UDP
Return Value
- DX = 0 success AX: socket descriptor
DX != 0 AX: contains
error code
Comments
- This function provides the BSD socket() functionality.
Related Topics
-
- Close socket API_CLOSESOCKET
Top of list Index page
Interrupt 0xAC service 0x02: API_CLOSESOCKET, close a socket
- Closes the socket indicated by BX and releases all of its
associated resources.
Parameters
- AH
- 0x02 (= API_CLOSESOCKET)
- BX
- Socket descriptor
Return Value
- DX = 0 success AX: 0
DX = -1 = API_ERROR AX: contains
error code
Related Topics
-
- Open socket API_OPENSOCKET
Top of list Index page
Interrupt 0xAC service 0x03: API_BIND, bind TCP or UDP server socket
- Bind a unnamed socket with an IP address and port number.
Parameters
- AH
- 0x03 (= API_BIND)
- BX
- Socket descriptor
- DX:SI
- Pointer to a sockaddr_in
structure, the first three
elements of which must be filled in by caller prior to calling.
Return Value
- DX = 0 success AX: 0
DX != 0 AX: contains
error code
Comments
- The bind call sets a specific port number as an application's source port number.
Otherwise a random 16-bit source port number will be used when no bind call is made.
The bind call is necessary for server applications in order that clients
can connect to them at the agreed upon ("well known") port number.
The older TCP and UDP echo client examples also used a bind call, but this was not necessary.
If you use the bind call in a client application, the client uses the given port number as its
own source port number.
Related Topics
-
- Get IP address of the Ethernet interface
-
- Convert ASCII IP address to binary
-
- For proper port number byte order: htons function
Top of list Index page
Interrupt 0xAC service 0x04: API_CONNECT, Connect to another socket
- For TCP only. The connect call attempts to make a connection to another
socket (either local or remote). This call is used by a TCP client.
Parameters
- AH
- 0x04 (= API_CONNECT)
- BX
- Socket descriptor
- DX:SI
- Pointer to a sockaddr_in
structure containing host's IP address and port number.
Return Value
- DX = 0 success AX: 0
DX != 0 AX: contains
error code
Comments
- The caller must fill in the first three elements of
the sockaddr_in data
structure
at [DX:SI] prior to calling here.
Top of list Index page
Interrupt 0xAC service 0x05: API_RECVFROM, Receive UDP message
- For UDP only, receives message from another socket.
Parameters
- AH
- 0x05 (= API_RECVFROM)
- BX
- Socket descriptor
- DX:SI
- Pointer to a recv_params data
structure which
caller must fill in prior to call.
Return Value
- DX = 0 success AX: number of received bytes where
0 bytes indicates a timeout
DX != 0 AX: contains
error code
Comments
- This function will output the received data to the
buffer referenced by recv_params.bufferPtr pointer.
Up to recv_params.bufferLength bytes will be accepted.
The AX return value indicates the number of bytes put into the buffer.
The sender can be identified by the IP address and port number reported
in the sockaddr_in structure
API_RECVFROM can only return complete UDP datagrams at the user provided buffer.
If the next waiting datagram at the internal socket receive queue has a higher
size than the specified recv_param.bufferlength, API_RECVFROM returns errorcode 240
(Message too long) without writing the datagram into the user buffer.
You can use API_GETRCV_BYTES
to detect the size of the next waiting datagram at the internal receive queue of this socket.
Related Topics
-
- API_SENDTO - Send UDP datagram
-
- API_RECV - Receive TCP data
-
- API_GETRCV_BYTES - Get waiting bytes on a socket
Top of list Index page
Interrupt 0xAC service 0x06: API_SENDTO, Transmit a UDP datagram
- For UDP only, transmits message to another transport end-point.
Parameters
- AH
- 0x06 (= API_SENDTO)
- BX
- Socket descriptor
- DX:SI
- Pointer to a send_params
structure which
caller must fill in prior to call.
Return Value
- DX = 0 success AX: number of bytes sent
DX != 0 AX: contains
error code
Comments
- This function will output up to send_params.bufferLength bytes from the buffer
at send_params.bufferPtr to the IP address specified by the
sockaddr_in structure
referenced by the send_params.toPtr pointer.
The return value indicates the actual number of bytes sent.
Related Topics
-
- API_RECVFROM - Receive UDP datagram
-
- API_SEND - Send TCP data
Top of list Index page
Interrupt 0xAC service 0x07: API_HTONS, Convert byte order
- Converts a short (16 bit) value from host byte order to
network byte order.
Parameters
- AH
- 0x07 (= API_HTONS)
- BX
- short value
Return Value
- DX = 0, AX contains converted value
Comments
- This is used to convert port numbers; e.g. htons(7).
Top of list Index page
Interrupt 0xAC service 0x08: API_INETADDR, Convert an IP-String to binary
- Converts a dotted decimal IP address string to an unsigned long
in network byte order.
Parameters
- AH
- 0x08 (= API_INETADDR)
- BX:SI
- Pointer to the IP dotted decimal string
set by caller. This ASCII string must be zero terminated.
- ES:DI
- Pointer to a 32 bit unsigned long variable,
where this function outputs the converted IP address value.
Return Value
- DX = 0 AX = 0, [ES:DI] contains converted 32 bit binary value
DX != 0 AX =
error code, syntax error
Related Topics
-
- Get IP address of the Ethernet interface
-
- Convert binary IP address to ASCII dotted decimal
Top of list Index page
Interrupt 0xAC service 0x09: API_SLEEP, Sleep
- The application sleeps for a specified number of milliseconds.
Parameters
- AH
- 0x09 (= API_SLEEP)
- BX
- milliseconds
Return Value
- DX = 0, AX = 0
Comments
- This call has been superceded by the similar RTOS API call
RTX_SLEEP_TIME.
This call here is maintained in the TCP/IP API for compatibility
with earlier @CHIP-RTOS version.
For new applications, the RTX function with more meaningful
return values is recommended.
Top of list Index page
Interrupt 0xAC service 0x0A: API_MALLOC, Allocate memory
- This function allocates memory direct from the @CHIP-RTOS heap.
Parameters
- AH
- 0x0A (= API_MALLOC)
- BX
- size in bytes
Return Value
- DX = 0 , AX = 0, ES:DI points to the allocated buffer
DX != 0 allocation error, ES:DI is a NULL-Pointer
Comments
- This function has been replaced by the DOS
Int21h 0x48 API and
is maintained here in the TCP/IP API only for compatibility with
earlier @CHIP-RTOS versions (prior to version 1.00).
For new applications, the DOS interrupt 0x21 function is recommended.
Top of list Index page
Interrupt 0xAC service 0x0B: API_FREE, Free an allocated buffer
- Releases a block of allocated memory.
Parameters
- AH
- 0x0B (= API_FREE)
- DX:SI
- Pointer to the buffer
Return Value
- DX = 0 , AX = 0 success
DX != 0 , AX = 0 free failed
Comments
- This out dated function releases memory allocated with
API_MALLOC. It is maintained
here only for compatibility with earlier @CHIP-RTOS versions (before version 1.00).
For new applications, the DOS interrupt 0x21 memory allocate
service 0x48 and release
service 0x49 are recommended.
Top of list Index page
Interrupt 0xAC service 0x0C: API_GETRCV_BYTES, Get waiting bytes count
- Get the number of bytes on a socket, waiting for read.
Parameters
- AH
- 0x0C (= API_GETRCV_BYTES)
- BX
- socket descriptor
Return Value
- DX = 0 success, AX contains the number of bytes ready
DX != 0 failed, AX contains
error code
Comments
- If the specified socket is an UDP socket, API_GETRCV_BYTES will return the
size (in bytes) of the next waiting datagram at the internal socket receive queue.
Related Topics
-
- API_RECVFROM - UDP Receive
-
- API_RECV - TCP Receive
Top of list Index page
Interrupt 0xAC service 0x0D: API_ACCEPT, Accept the next incoming connection
- This API extracts the first connection on the queue of pending connections
(from API_LISTEN)
and creates a new socket for this connection.
Parameters
- AH
- 0x0D (= API_ACCEPT)
- BX
- Socket descriptor (must be switched into
listen mode using API_LISTEN)
- DX:SI
- Output Parameter: Pointer to a
sockaddr_in
structure (see tcpipapi.h)
Return Value
- DX = 0 success, AX: contains new socket descriptor for the connection
DX != 0 failure, AX: contains
error code
Comments
- This call is used by a TCP server.
On success, this function fills in the sockaddr_in
structure at [DX:SI]
with the IP address and port number of the accepted connection.
The new socket will have the same socket options as the listening socket (BX).
Related Topics
-
- API_SETSOCKOPT - Set socket options
Top of list Index page
Interrupt 0xAC service 0x0E: API_LISTEN, Listen for incoming connections
- Places the socket into passive mode and sets the number of incoming TCP
connections that the system will queue.
Parameters
- AH
- 0x0E (= API_LISTEN)
- BX
- Socket descriptor
- CX
- The maximum number (limited to 5) of allowed outstanding connections
Return Value
- DX = 0 success, AX: 0
DX != 0 failure, AX: contains
error code
Comments
- This call is used by a TCP server.
Related Topics
-
- API_ACCEPT - Accept the next incoming connection
Top of list Index page
Interrupt 0xAC service 0x0F: API_SEND, Transmit TCP message
- For TCP only, this API transmits a message to another transport end-point.
Parameters
- AH
- 0x0F (= API_SEND)
- BX
- Socket descriptor
- DX:SI
- Pointer to a send_params
structure which must be
filled in by caller.
Return Value
- DX = 0 success, AX: number of bytes sent
DX != 0 failure, AX: contains
error code
Comments
- API_SEND may be used only if the socket is in a connected state.
On success, the return value in AX contains the number of bytes
which were successfully inserted into the socket's send queue.
Related Topics
-
- API_RECV - Receive TCP data
-
- API_SENDTO - Send UDP datagram
Developer Notes Since @CHIP-RTOS 1.00 the MSG_DONTWAIT option is available in the flag
member of send_params structure for the API_SEND function (or
recv_params structure for API_RECV function). If flag
is set to MSG_DONTWAIT the send call returns immediately.
As much data as fits into the internal TCP buffer is accepted for transmission
and the transmit byte count is returned in AX. If none of the data fits then -1
is returned in DX and error code 235 in AX.
If flag is set to MSG_BLOCKING, the send call blocks until enough internal buffer space
is available or a socket error occurs. By default the blocking mode is
set for all sockets at the open call.
If a socket has been set to non-blocking with the
API_SETBLOCKINGMODE function, the
MSG_BLOCKING flag is ignored and the call will be non-blocking.
Top of list Index page
Interrupt 0xAC service 0x10: API_RECV, Receive TCP message
- For TCP only, this API receives a message from another socket.
Parameters
- AH
- 0x10 (= API_RECV)
- BX
- Socket Descriptor
- DX:SI
- Pointer to recv_params
structure which must
be filled in by user.
Return Value
- DX = 0 success, AX: number of received bytes; 0 bytes implies timeout
DX != 0 failure, AX: contains
error code
Comments
- API_RECV may only be used when the socket is in a connected state.
On success, the return value in AX contains the number of bytes which were
successfully inserted into the caller's receive buffer at
recv_params.bufferPtr. The length of the message returned could
also be smaller than the parameter bufferlength of the
recv_param structure. This is not an error.
If flag member of recv_params structure
is set to MSG_DONTWAIT, the API_RECV call returns immediately.
If no data is available -1 is returned in DX with error code 235 in AX. If flag is set
to MSG_BLOCKING, the API_RECV call waits for a message to arrive.
By default the blocking mode is set for all sockets at the open call. If a socket was set to
non-blocking with the API_SETBLOCKINGMODE
function, the MSG_BLOCKING flag is ignored and the call will be non-blocking.
Related Topics
-
- API_SEND - Send TCP data
-
- API_RECVFROM - Receive UDP datagram
Top of list Index page
Interrupt 0xAC service 0x11: API_INETTOASCII, Convert IP address to IP string
- Converts an unsigned long IP address to an ASCII dotted decimal IP string.
Parameters
- AH
- 0x11 (= API_INETTOASCII)
- BX:SI
- Input Parameter:
Pointer to the 32 bit IP address in
network byte order
- ES:DI
- Output Parameter:
Pointer to the string buffer, where this function
outputs the converted dotted decimal IP string.
This buffer must have space for 17 Bytes!
Return Value
- DX = 0, AX = 0, [ES:DI] buffer contains converted string value
Comments
- The dotted decimal IP address ASCII string output to [ES:DI]
buffer is zero terminated.
Related Topics
-
- Convert ASCII dotted decimal IP address to binary
Top of list Index page
Interrupt 0xAC service 0x12: API_RESETCONNECTION, Abort a connection on a socket
- Applies only to TCP sockets.
Parameters
- AH
- 0x12 (= API_RESETCONNECTION)
- BX
- Socket descriptor
Return Value
- DX = 0 success AX: 0
DX != 0 failure, AX: contains
error code
Comments
- This API_RESETCONNECTION API does not close the socket, which must be done with API_CLOSESOCKET.
The reset socket can not be used for a new connection. You must close the socket and open
a new one to get a new connection.
Related Topics
-
- Close socket API_CLOSESOCKET
Top of list Index page
Interrupt 0xAC service 0x13: API_SETLINGER, Set linger time on close
- Applies only to TCP sockets.
Parameters
- AH
- 0x13 (= API_SETLINGER)
- BX
- Socket descriptor
- CX
- Linger time in seconds, default: 60 seconds,
0 means linger turned off.
Return Value
- DX = 0 success
DX != 0 failure, AX: contains
error code
Top of list Index page
Interrupt 0xAC service 0x14: API_SETREUSE, Set reuse option on a listening socket
- Sets SO_REUSEADDR
socket option to '1'.
Parameters
- AH
- 0x14 (= API_SETREUSE)
- BX
- Socket descriptor
Return Value
- DX =0 success
DX!=0 failure, AX: contains
error code
Comments
- This API applies only to TCP sockets. The reuse option is necessary
if a listening socket is closed and then a new socket is opened
and bound to the same port as the earlier socket.
Developer Notes Since @CHIP-RTOS version 071, the
API_OPENSOCKET call sets the SO_REUSEADDR
option to '1' as default for all TCP sockets. So calling this API is no
longer necessary.
Top of list Index page
Interrupt 0xAC service 0x15: API_SETIPTOS, Set IP Type-Of-Service
- Sets socket's default Type-Of-Service
placed in the IP datagram header's
TOS field.
Parameters
- AH
- 0x15 (= API_SETIPTOS)
- AL
- Type-Of-Service
for IP datagrams
- BX
- Socket descriptor
Return Value
- DX = 0 success
DX != 0 failure, AX: contains
error code
Comments
- The 8 bits in the IP datagram Type-Of-Service
field
are defined as follows:
Bits 0: unused bit (must be 0)
Bits 1-4: Type of Service, see TCP/IP documentation e.g.
Section 3.2 of "TCP/IP Illustrated, Volume 1
" by W. Richard Stevens.
At most one of these four bits is set.
Bits 5-7: "Precedence field" (unused today)
Note: Many routers ignore this IP datagram header field.
Top of list Index page
Interrupt 0xAC service 0x16: API_SETSOCKOPT, Set options on socket
- Controls option settings for specfied socket.
Parameters
- AH
- 0x16 (= API_SETSOCKOPT)
- BX
- Socket descriptor
- ES:DI
- Pointer to SetSocketOption
type
that specifies the socket options (see tcpipapi.h)
Return Value
- DX=0 success
DX!=0 AX: contains
error code
Comments
- This API function makes it possible to manipulate options associated with a socket.
Prior to calling this function the caller must fill in a SetSocketOption
type data structure.
The socket options of an incoming connection (using
accept) will be the same as the
socket options from its listening socket.
See SetSocketOption
type definition for example
usage of this API function.
Related Topics
-
- GetSocketOption typedef with option names
-
- API_GETSOCKOPT - Get socket options
Top of list Index page
Interrupt 0xAC service 0x17: API_GETSOCKOPT, Get options on socket
- Reads out an option setting for a specified socket.
Parameters
- AH
- 0x17 (= API_GETSOCKOPT)
- BX
- Socket descriptor
- ES:DI
- Pointer to GetSocketOption
structure
Return Value
- DX = 0 success, Buffer pointed to by the optionValue member
of the GetSocketOption
structure at [ES:DI] contains the requested socket option value.
DX != 0 failure, AX: contains
error code
Comments
- This API function makes it possible to read options associated with a socket.
Prior to calling this function, the caller must fill in a GetSocketOption
type data structure.
The user must set the protocol_level and optionName members.
Also the pointer optionValue must point to a valid buffer in the user application's
memory.
The optionLength member is both an input and an output parameter.
The length of the buffer must be specified at the location referenced by optionLength
and this length must be sufficient for the size of the requested option data.
On success, this API writes to the optionLength location the number of bytes output
to the optionValue buffer.
The socket options of an incoming connection (using
accept) will be the same as the
socket options from its listening socket.
Related Topics
-
- GetSocketOption typedef with option names
-
- API_SETSOCKOPT - Set socket options
Top of list Index page
Interrupt 0xAC service 0x18: API_SETBLOCKINGMODE, Set socket mode
- Sets a socket in blocking or non-blocking mode
Parameters
- AH
- 0x18 (= API_SETBLOCKINGMODE)
- AL
- 0: switch blocking off, 1: switch blocking on
- BX
- Socket descriptor
Return Value
- DX = 0 success
DX != 0 failure, AX: contains
error code
Comments
- By default all sockets are in blocking mode. If a socket is set to non-blocking mode,
socket calls like CONNECT, ACCEPT, ... do not wait until full completion.
They will instead return immediately.
Example usage of non-blocking mode:
The connect call returns for a non-blocking socket with -1 in DX
and error code 236 if the connection was not completed.
The user can call connect within a loop, periodically polling
for connection completion condition while performing some other activity.
Top of list Index page
Interrupt 0xAC service 0x19: API_REGISTERCALLBACK, Register a user callback function
- Register a user callback function for events occurring on a TCP socket.
Parameters
- AH
- 0x19 (= API_REGISTERCALLBACK)
- BX
- Socket descriptor
- CX
- Event flag mask (see below)
- ES:DI
- Pointer to callback function (see below)
Return Value
- DX = 0 success
DX != 0 AX: contains
error code
Comments
- The TCP/IP stack of the IPC@CHIP is able to execute a registered user callback function,
if one or more some specified events happens on a TCP socket connection.
The callback function must be of the following type (Borland C):
void huge socketCallBackFunc(int socketdescriptor,
int eventFlags)
Before closing a socket, you should remove the callback function.
This is done by calling this API function with a null pointer in ES:DI
and value 0 in register CX.
The input parameter eventFlags to the callback is a bit field
indicating the event(s) that have occurred.
The set of events for either the CX event mask argument to this API
or the eventFlags callback parameter are defined in TCPIPAPI.H
as follows:
| #define CB_CONNECT_COMPLT 0x0001 // Connection complete
#define CB_ACCEPT 0x0002 // Remote client has established
// a connection to our listening server.
#define CB_RECV 0x0004 // Incoming data arrived
#define CB_SEND_COMPLT 0x0010 // Sending of data has been acked by the peer
#define CB_REMOTE_CLOSE 0x0020 // Peer has shutdown the connection
#define CB_SOCKET_ERROR 0x0040 // An error occurred on the connection
#define CB_RESET 0x0080 // Peer has sent a rest on the connection
#define CB_CLOSE_COMPLT 0x0100 // close has been completed |
Related Topics
-
- API_REGISTERCALLBACK_PASCAL For Pascal callback functions
Top of list Index page
Interrupt 0xAC service 0x20: API_REGISTERCALLBACK_PASCAL, Pascal user callback
- Registers a user callback function written in Pascal for events occurring on a TCP socket.
Parameters
- AH
- 0x20 (= API_REGISTERCALLBACK_PASCAL)
- BX
- Socket descriptor
- CX
- Event flag mask (see below)
- ES:DI
- Pointer to callback function (see below)
Return Value
- DX = 0 success
DX != 0 AX: contains
error code
Comments
- The number of Pascal TCP callback functions is limited to 10.
The first action required in your callback function is to read the pointer to the
PacCallBack record passed in
registers ES:DI.
This can be accomplished by implementing the callback function as follows (Borland Pascal):
procedure socketCallBackFunc; interrupt;
var
ESReg : Integer;
DIReg : Integer;
CBParamPtr : CallBackParamPtr;
begin
(*********************************)
(* Required to get the Parameter *)
asm
mov ax, es
mov ESReg, ax
mov ax, di
mov DIReg, ax
end;
(*********************************)
[... your code ...]
end;
Before closing a socket, you should remove the callback function.
This is done by calling this API function with a null pointer in ES:DI
and value 0 in register CX.
The event flags are defined as follows:
const
CB_CONNECT_COMPLT = $0001;
CB_ACCEPT = $0002;
CB_RECV = $0004;
CB_SEND_COMPLT = $0010;
CB_REMOTE_CLOSE = $0020;
CB_SOCKET_ERROR = $0040;
CB_RESET = $0080;
CB_CLOSE_COMPLT = $0100;
Related Topics
-
- API_REGISTERCALLBACK For C language callback functions
Top of list Index page
Interrupt 0xAC service 0x21: API_GET_SOCKET_ERROR, Get last socket error.
- Returns the last error which occurred on the
specified socket.
Parameters
- AH
- 0x21 (= API_GET_SOCKET_ERROR)
- BX
- Socket descriptor
Return Value
- DX =0: success AX: contains last socket
error code
Top of list Index page
Interrupt 0xAC service 0x22: API_GET_TCP_STATE, Find TCP socket and return state.
- Search for a TCP socket at a given local port number,
returning the socket state, IP address and port number of the remote peer (if any).
Parameters
- AH
- 0x22 (= API_GET_TCP_STATE)
- BX
- Local port (e.g. htons(23) for telnet)
- ES:DI
- Pointer to storage 32 Bit remote IP address
Return Value
- AL: contains last TCP socket state (see below)
If AL!=20 and AL bigger or equal 2 (a TCP connection is established),
the storage at ES:DI holds the 32 bit IP address of the connected remote peer
CX contains remote peer port number
Comments
- This function is only available in @CHIP-RTOS version which contain the SNMP MIB feature.
Possible TCP socket states:
- 0: CLOSED
1: LISTEN
2: SYN_SENT
3: SYN_RECEIVED
4: ESTABLISHED
5: CLOSE_WAIT
6: FIN_WAIT_1
7: CLOSING
8: LAST_ACK
9: FIN_WAIT_2
10: TIME_WAIT
20: INVALID
Top of list Index page
Interrupt 0xAC service 0x23: API_FINDALL_SOCKETS, Get information about all open sockets.
- Find/return information about all open sockets at the internal socket table.
Parameters
- AH
- 0x23 (= API_FINDALL_SOCKETS)
- ES:DI
- Output Parameter: Pointer to an array of CX
SocketInfo structures
in the user's memory space into which this API will report the socket information.
- CX
- Size of the array (maximum number of table entries reported).
Return Value
- AX holds the number of all open sockets.
The user provided array at [ES:DI] holds the socket information
for up to CX sockets (the lesser of two register counts: AX, CX).
Comments
- This function is only available in @CHIP-RTOS versions which contain the SNMP MIB feature.
If CX >= AX then all sockets in the socket table have been reported.
Below is an example of using API_FINDALL_SOCKETS with the FindAllOpenSockets
C library wrapper function. This example lists up to 64 current entries in the
TCP/IP socket table:
| SocketInfo s[64];
int avail, i;
avail = FindAllOpenSockets(s, 64);
if (avail > 64) avail = 64;
for (i = 0; i < avail; i++)
{
printf("\r\nSocket index %d Protocol %d, LocalPort %d",
s[i].socIndex, s[i].protocol, s[i].localport);
} |
Related Topics
-
- SocketInfo data structure
Top of list Index page
Interrupt 0xAC service 0x40: PPPCLIENT_INSTALLED, Check if PPP client installed.
- Tests if PPP client services are available in this @CHIP-RTOS version
and not disabled via CHIP.INI
configuration.
Parameters
- AH
- 0x40 (= PPPCLIENT_INSTALLED)
Return Value
- AX = 0: PPP client is not installed
AX != 0: PPP client is installed
Related Topics
-
- PPPCLIENT_GET_STATUS API - PPP client status
Top of list Index page
Interrupt 0xAC service 0x41: PPPCLIENT_OPEN, Open a PPP connection
- Opens a PPP client connection.
Parameters
- AH
- 0x41 (= PPPCLIENT_OPEN)
- ES:DI
- Pointer to a PPPClient_Init
type data structure (declared at tcpipapi.h)
Return Value
- DX: 0 AX: 0, success [ES:DI] contains the needed IP data for
further TCP/IP socket communication
DX: -1 AX: contains
error code, open failed
Comments
- Refer to the PPPCLIE.C example for how to use this API. Also see the
PPPClient_Init data
structure documentation.
Note: Only one PPP client connection can be open at a time!!
Related Topics
-
- PPPCLIENT_CLOSE - Closes PPP client connection
Top of list Index page
Interrupt 0xAC service 0x42: PPPCLIENT_CLOSE, Close a PPP client connection
- Closes a PPP client connection.
Parameters
- AH
- 0x42 (= PPPCLIENT_CLOSE)
Return Value
- DX: 0, AX =0: PPP client connection is closed
DX: -1, AX contains
error code,
Connection close timed out
Comments
- At the close call the PPP client also executes after closing the PPP session
the modem hang-up commands specified in the PPPClient_Init
structure referenced
at the PPPCLIENT_OPEN call.
Therefore we recommend waiting approximately 10 seconds before opening a
subsequent PPP connection.
Top of list Index page
Interrupt 0xAC service 0x43: PPPCLIENT_GET_STATUS, Get PPP client status
- Gets PPP client's current status.
Parameters
- AH
- 0x43 (= PPPCLIENT_GET_STATUS)
Return Value
- AX = -2 (=API_NOT_SUPPORTED), DX =- 2: PPP client
task is not running
AX = -1 (=API_ERROR), DX = PPP client
status
AX >= 0, then AX = PPP client status, DX unchanged
Comments
- If the PPP client is not supported in this @CHIP-RTOS version, then the value
returned in AX is zero and DX is set to -1 (=API_ERROR). In this case an
error message is issued to the console.
Related Topics
-
- PPPCLIENT_INSTALLED API - @CHIP-RTOS feature check
Top of list Index page
Interrupt 0xAC service 0x44: PPPCLIENT_GET_DNSIP, Get DNS IP address
- Returns the Domain Name System
(DNS) addresses as
negotiated by the remote PPP server.
Parameters
- AH
- 0x44 (= PPPCLIENT_GET_DNSIP)
- BX
- 1: Get primary DNS address, 2: Get secondary address
- ES:DI
- Output Parameter: Pointer to an unsigned long
variable where the requested DNS IP address will be stored by this API.
Return Value
- AX = -2 (=API_NOT_SUPPORTED), DX = -2: PPP client is not
installed.
AX = -1 (=API_ERROR) DX contains
error code.
AX = 0, then unsigned long at [ES:DI] holds the DNS IP address.
Comments
- The IP address output to [ES:DI] is in
network byte order.
Top of list Index page
Interrupt 0xAC service 0x45: PPPCLIENT_SET_OPTIONS, Set options for the PPP client
- Sets the PPP options for the PPP client.
Parameters
- AH
- 0x45 (= PPPCLIENT_SET_OPTIONS)
- ES:DI
- Pointer to an array of PPP_Option
data structures.
This array is terminated by first PPP_Option structure
with a null optionValuePtr member
(see example below).
Return Value
- AX = -3 PPP Connection already established
AX = -2 PPP client is not
installed.
AX = -1 Invalid Option(s)
AX = 0 Success
Comments
- If you want to use this function, you have to call it before opening
a connection (see related links below). Settings options during an
established connection will not work!
The settings are only valid for the next established connection.
The data structures referenced here with ES:DI must persist until after
the subsequent PPP client open
function completes.
A C-Library function is available in the CLIB file TCPIP.C.
Here is an example which sets three PPP options using the C-Library
wrapper functions:
| // Allow remote peer to set primary DNS IP.
unsigned long DNS_Pri_IP = 0L;
// Allow remote peer to set secondary DNS IP.
unsigned long DNS_Sec_IP = 0L;
// Allow remote peer to use VJ TCPIP header compression.
unsigned int ipcp_comp = 1;
PPP_Option My_Options[] = {
{ PPP_IPCP_PROTOCOL, PPP_OPTION_ALLOW, PPP_IPCP_COMP_PROTOCOL,
(const char *)&ipcp_comp, sizeof(ipcp_comp)},
{ PPP_IPCP_PROTOCOL, PPP_OPTION_WANT, PPP_IPCP_DNS_PRI,
(const char *)&DNS_Pri_IP, sizeof(DNS_Pri_IP)},
{ PPP_IPCP_PROTOCOL, PPP_OPTION_WANT, PPP_IPCP_DNS_SEC,
(const char *)&DNS_Sec_IP, sizeof(DNS_Sec_IP)},
// This last PPP_Option is used to terminate array.
{ 0, 0, 0, NULL, 0}
} ;
//***** Call the C-Library functions as follows ****
// Install options with CLIB function
PPP_Client_SetOptions(&My_Options[0]); // Point to first member of array
PPP_Client_Open(&pppclient); // Open the connection |
Related Topics
-
- PPPCLIENT_OPEN open a PPP connection
-
- PPPCLIENT_CLOSE close a PPP connection
Top of list Index page
Interrupt 0xAC service 0x50: PPPSERVER_INSTALLED, Check if PPP server installed
- Tests if PPP server is available in this @CHIP-RTOS version
and not disabled via CHIP.INI
configuration.
Parameters
- AH
- 0x50 (= PPPSERVER_INSTALLED)
Return Value
- AX = 0: PPP server is not installed
AX != 0: PPP server is installed
Top of list Index page
Interrupt 0xAC service 0x51: PPPSERVER_SUSPEND, Suspend PPP server task
- Suspends the PPP server task, "PPPS".
Parameters
- AH
- 0x51 (= PPPSERVER_SUSPEND)
- BX
- Timeout seconds
Return Value
- AX = 0, DX= 0 PPP server is suspended
AX != 0, DX != 0 Suspending PPP server failed, PPP server is
not installed or timeout
Comments
- Note that the timeout value in BX depends on your timeout
entries for the modem commands
specified in CHIP.INI. If this call returns with -1 in AX and DX,
the most likely reason for this is that the modem commands were not finished
within the timeout period the timeout specified in BX.
Related Topics
-
- PPPSERVER_ACTIVATE API - Reactivate PPP server
-
- PPPSERVER HANGUPTIMEOUTx - CHIP.INI timeout for wait on answer from modem
Top of list Index page
Interrupt 0xAC service 0x52: PPPSERVER_ACTIVATE, Activate PPP server
- Re-activate suspended PPP server.
Parameters
- AH
- 0x52 (= PPPSERVER_ACTIVATE)
- BX
- Timeout seconds
Return Value
- AX = 0, DX = 0 PPP server is activated
AX != 0, DX != 0 Activating PPP server failed, PPP server
is not installed or timeout
Comments
- This API will not activate the PPP server disabled from start up
by the CHIP.INI
configuration entry.
On success, the PPP server is now able to serve a connection.
Note that the timeout value in BX depends on your timeout
entries for the modem commands
specified in CHIP.INI. If this call returns with -1 in AX and DX,
the most likely reason for this is that the modem commands were not finished
within the timeout period specified in BX.
Related Topics
-
- PPPSERVER_SUSPEND API - Suspend PPP server
-
- PPPSERVER HANGUPTIMEOUTx - CHIP.INI timeout for wait on answer from modem
Top of list Index page
Interrupt 0xAC service 0x53: PPPSERVER_GET_STATUS, Get server state
- Gets the current state of the PPP server.
Parameters
- AH
- 0x53 (= PPPSERVER_GET_STATUS)
Return Value
- DX != 0: PPP server is not
installed
DX = 0: AX contains the current PPP server state
listed below
Comments
- PPP server states:
-1 Error state, should not happen
1 Server disabled
2 Server enabled, waiting for connection
3 PPP connection is established
4 Server tries to hang up modem
5 Server tries to initialize modem
Top of list Index page
Interrupt 0xAC service 0x54: PPPSERVER_GET_CFG, Get PPP server configuration
- Gets the current main configuration data of the PPP server.
Parameters
- AH
- 0x54 (= PPPSERVER_GET_CFG)
- ES:DI
- Output Parameter:
Pointer to PPP_IPCfg_Data data
structure
where this function will report the configuration data.
Return Value
- DX != 0 AX != 0: PPP server is not installed
DX = 0 The user PPP_IPCfg_Data structure at [ES:DI] is filled with
the PPP server configuration data
Related Topics
-
- PPP_IPCfg_Data structure definition
Top of list Index page
Interrupt 0xAC service 0x55: PPPSERVER_SET_OPTIONS, Set options for PPP server
- Sets the PPP options for the PPP server.
Parameters
- AH
- 0x55 (= PPPSERVER_SET_OPTIONS)
- ES:DI
- Pointer to an array of PPP_Option
data structures.
This array is terminated by first PPP_Option structure
with a null optionValuePtr member.
(see example below).
Return Value
- AX = -3: PPP Connection already established
AX = -2: PPP server is not installed
AX = -1: Invalid Option(s)
AX = 0: Success
Comments
- It is only possible to set PPP options when the PPP server is
suspended.
PPP server must be at status 1.
Setting options while the PPP server is active (state 2,3,4,5) has no effect.
The installed options will be applied as the PPP server is
re-activated. The data
structures referenced by ES:DI must persists until that time.
If you want to reset the options, call this function with a null pointer in ES:DI.
A C-Library function for this API is available in the CLIB file TCPIP.C.
Here is an example which sets three PPP options using the C-Library wrapper functions:
| // Allow remote peer to set primary DNS IP.
unsigned long DNS_Pri_IP = 0L;
// Allow remote peer to set secondary DNS IP.
unsigned long DNS_Sec_IP = 0L;
// Allow remote peer to use VJ TCPIP header compression.
unsigned int ipcp_comp = 1;
PPP_Option My_Options[] = {
{ PPP_IPCP_PROTOCOL, PPP_OPTION_ALLOW, PPP_IPCP_COMP_PROTOCOL,
(const char *)&ipcp_comp, sizeof(ipcp_comp)},
{ PPP_IPCP_PROTOCOL, PPP_OPTION_WANT, PPP_IPCP_DNS_PRI,
(const char *)&DNS_Pri_IP, sizeof(DNS_Pri_IP)},
{ PPP_IPCP_PROTOCOL, PPP_OPTION_WANT, PPP_IPCP_DNS_SEC,
(const char *)&DNS_Sec_IP, sizeof(DNS_Sec_IP)},
// This last PPP_Option is used to terminate array.
{ 0, 0, 0, NULL, 0}
} ;
//***** Call the C-Library functions as follows ****
// Suspend the PPP server
PPP_Server_Suspend(20, &error);
// Install options with CLIB function
PPP_Server_SetOptions(&My_Options[0]); // Point to first member of array
// Re-activate the server
PPP_Server_Activate(20, &error); |
Related Topics
-
- PPPSERVER_SUSPEND suspend PPP server task
-
- PPPSERVER_ACTIVATE activate PPP server
-
- PPPSERVER_GET_STATUS Get status of the PPP server
Top of list Index page
Interrupt 0xAC service 0x60: API_SNMP_GET, Get internal TCP/IP SNMP variables
- Accesses Management Information Base
(MIB) data structures
residing inside the @CHIP-RTOS TCP/IP stack.
Parameters
- AH
- 0x60 (= API_SNMP_GET)
- AL
- 1 Get pointer to IfMib data structure
(only for the internal Ethernet device interface)
2 Get pointer to IpMib data structure
3 Get pointer to IcmpMib data structure
4 Get pointer to TcpMib data structure
5 Get pointer to UdpMib data structure
6 Get pointer to AtEntry data structure
(only of the internal Ethernet device interface)
7 Get array of far pointers to IfMib
entries of all current open TCP/IP device interfaces.
(Local Loopback, Ethernet, PPP server, PPP client)
8 Get far pointer to unsigned long sysuptime variable (10 Hz counter).
- DS:SI
- If parameter AL==7, ES:DI must contain the address of a buffer
into which up to CX far pointers to IpMib
data structures can be reported by this API.
- CX
- If parameter AL==7, CX specifies the number of far pointers (capacity)
which the user buffer at [DS:SI] can hold.
Return Value
- DX != 0 AX != 0 : @CHIP-RTOS without internal SNMP MIB variables
DX = AX = 0 ES:DI contains a pointer to the structure unless input
parameter AH was 7,
in which case the user provided array (still addressed by DS:SI)
contains the far pointers to the IfMib entries of the currently
installed device interfaces.
CX is set to indicate the total number of currently installed devices. If CX is
less than it was on entry, then the reported list of pointers is not complete due
to lack of user buffer space.
Comments
- If this API call is used with AL==1-6, or 8, the pointers are granting direct
access to the internal TCP/IP stack counters. It's recommended to execute
these calls only one time at the start of your application.
For AL=7, the API call returns the pointers to the interface variables for the
currently installed device interfaces.
To maintain an up to date array of pointers for all currently opened device interfaces,
it is necessary to periodically request (e.g. every 10 seconds) the array of pointers.
Note: These structures are only available in @CHIP-RTOS versions which contain the
SNMP option. A SNMP agent is not part of the @CHIP-RTOS. But if a user is able to implement
an agent based on the TCP/IP API, they need access to the internal TCP/IP SNMP variables.
The SNMP MIB variables are not a part of our current official 6 @CHIP-RTOS versions.
It is necessary to order directly a @CHIP-RTOS version which includes this feature.
Top of list Index page
Interrupt 0xAC service 0x65: API_FTP_GET_LOGIN, Get FTP server login counters
- Accesses the FTP server login counters.
Parameters
- AH
- 0x65 (= API_FTP_GET_LOGIN)
Return Value
- DX != 0 AX != 0 : @CHIP-RTOS doesn't support FTP server
DX = AX = 0
ES:DI contains the address of the 32 Bit (unsigned long) login counter
DS:SI contains the address of the 32 Bit (unsigned long) login fail counter
Top of list Index page
Interrupt 0xAC service 0x66: API_TELNET_GET_LOGIN, Get Telnet server login counters
- Accesses the Telnet server login counters.
Parameters
- AH
- 0x66 (= API_TELNET_GET_LOGIN)
Return Value
- DX != 0 AX != 0 : @CHIP-RTOS doesn't support Telnet server
DX = AX = 0
ES:DI contains the address of the 32 Bit (unsigned long) login counter
DS:SI contains the address of the 32 Bit (unsigned long) login fail counter
Top of list Index page
Interrupt 0xAC service 0x67: API_GET_TELNET_STATE, Test Telnet session active
- Check if the Telnet server is currently handling an active Telnet session.
Parameters
- AH
- 0x67 (= API_GET_TELNET_STATE)
Return Value
- DX = -1 AX = -1 : @CHIP-RTOS doesn't support Telnet server
DX = 0 AX = 1: Telnet session is active
DX = 0 AX = 0: No Telnet session
Top of list Index page
Interrupt 0xAC service 0x70: GET_INSTALLED_SERVERS and interfaces
- Get information about running servers and interfaces of the IPC@CHIP TCP/IP Stack
Parameters
- AH
- 0x70 (= GET_INSTALLED_SERVERS)
Return Value
- Bits of AX and DX contains the requested information
Bit=0 service or device is not available.
Bit=1 service or device is available.
AX:
Bit 0: Ethernet device
Bit 1: PPP server
Bit 2: PPP client
Bit 3: Web server
Bit 4: Telnet server
Bit 5: FTP server
Bit 6: TFTP server
Bit 7: DHCP client
DX:
Bit 0: SNMP MIB variables support
Bit 1: UDP Config server
Bit 2: Ping client
Top of list Index page
Interrupt 0xAC service 0x71: RECONFIG_ETHERNET, Reconfigure Ethernet interface
- Reconfigures Ethernet interface, e.g. after changing the IP configuration
Parameters
- AH
- 0x71 (= RECONFIG_ETHERNET)
Return Value
- AX:0 success
else restart failed (should not happen). Error code 237 indicates
that an Ethernet interface configuration was already in progress.
Comments
- A new IP configuration set with the prompt
commands
ip, netmask and gateway
(or the corresponding @CHIP-RTOS API calls)
becomes valid after a successful call to this function.
If DHCP is changed from 1 to 0 then a new IP address, subnet mask and gateway should be set
with the prompt commands
ip, netmask and gateway
or with the @CHIP-RTOS API interrupt 0xA0 services
0x02,
0x04,
0x06 before using this function.
Top of list Index page
Interrupt 0xAC service 0x72: DHCP_USE, Enable/Disable DHCP usage
- Set/Reset DHCP usage by the Ethernet interface.
Parameters
- AH
- 0x72 (= DHCP_USE)
- AL
- 0: DHCP not used, 1:DHCP_USE
Return Value
- -- none --
Comments
- This entry becomes valid only after rebooting the system or after calling function
0x71.
If DHCP is changed from 1 to 0 then a new IP address, subnet mask and gateway should be set
with the prompt commands
ip, netmask and gateway
or with the @CHIP-RTOS API interrupt 0xA0 services
0x02,
0x04,
0x06.
Top of list Index page
Interrupt 0xAC service 0x73: DHCP_STAT, Get DHCP status of the Ethernet interface
- Gets the DHCP status of the Ethernet interface.
Parameters
- AH
- 0x73 (= DHCP_STAT)
Return Value
- AX: 1 System uses DHCP, AX:0 DHCP is not used
DX: 0 System is not configured (is in progress)
DX: 1 System is configured by a DHCP Server
DX: 2 System configure retry failed (or no retry started before)
If DX == 1 ES:DI points to a
UserEthDhcp_Entry
data structure which contains the received DHCP configuration data.
Comments
- The returned DHCP configuration data must be treated by the user as
read-only information. Do not write to this data structure!
Top of list Index page
Interrupt 0xAC service 0x74: TCPIP_STATISTICS, Access packet counters
- This function returns the address of a structure which contains pointers
to network packet counters.
Parameters
- AH
- 0x74 (= TCPIP_STATISTICS)
Return Value
- AX: 0, DX:0
ES:DI contains a pointer to the Packet_Count
structure
Comments
- The counters count_all_packets and count_all_sended packets
count only Ethernet packets.
Other counters also count the packets from and to other devices, e.g. local loopback packets
and PPP packets.
The user is free to read and/or reset these counters.
Related Topics
-
- Packet_Count structure type definition
Top of list Index page
Interrupt 0xAC service 0x75: PING_OPEN, Open and start ICMP echo requests
- This function opens and starts periodic
Internet Control Message Protocol
(ICMP) echo request (ping)
to a specified remote host.
Parameters
- AH
- 0x75 (= PING_OPEN)
- ES:DI
- Pointer to user's Ping
structure, four
members of which must be set by caller prior to call.
Return Value
- DX: -1, AX contains
error code, Ping open failed
else
DX: socket descriptor, AX: 0
Comments
- Important:
If structure member count (set by user) is non-zero, the
PING_STATISTICS call closes the ping socket automatically if structure
member transmitted has reached the count value.
If structure member count is zero, ping process
runs until PING_CLOSE is called.
Related Topics
-
- PING_CLOSE API
-
- PING_STATISTICS API
-
- Console PING command
Top of list Index page
Interrupt 0xAC service 0x76: PING_CLOSE, Finish ICMP echo requests
- This function stops cyclic ICMP echo request (ping).
Parameters
- AH
- 0x76 (= PING_CLOSE)
- BX
- Socket descriptor from inside
Ping structure
from PING_OPEN call.
Return Value
- DX: -1, AX -1, Ping close failed, should not happen, only if
socket descriptor is invalid
else
DX: 0, AX: 0: success
Comments
- The ping socket is closed here.
Related Topics
-
- PING_OPEN API
Top of list Index page
Interrupt 0xAC service 0x77: PING_STATISTICS, Retrieve ping information
- The user can retrieve ping information by calling PING_STATISTICS.
Parameters
- AH
- 0x77 (= PING_STATISTICS)
- ES:DI
- Pointer to user's Ping
structure from PING_OPEN call
Return Value
- DX = 0, AX = 0: Success
DX = -1, AX = -1: Failure
Comments
- Structure at [ES:DI] is filled with the ping statistics on success.
Important:
If structure member count (set by user) is non-zero, the
PING_STATISTICS call closes the ping socket automatically if structure
member transmitted has reached the count value.
If structure member count is zero, ping process
runs until PING_CLOSE is called.
Related Topics
-
- PING_OPEN API
-
- PING_CLOSE API
Top of list Index page
Interrupt 0xAC service 0x78: GETMEMORY_INFO, Report TCP/IP memory usage
- This function reports the maximum available and the currently
used memory of the TCP/IP stack.
Parameters
- AH
- 0x78 (= GETMEMORY_INFO)
- ES:DI
- Output Parameter: Pointer to user's unsigned long
where this API will report the maximum available TCP/IP memory byte count.
- DS:SI
- Output Parameter: Pointer to user's unsigned long
where this API will report the currently used TCP/IP memory byte count.
Return Value
- DX: 0, AX 0 (The described memory sizes are stored at [ES:DI] and [DS:SI])
Comments
- The maximum available memory for the TCP/IP stack can be configured in
chip.ini (see TCPIPMEM).
The amount of memory required by the TCP/IP stack depends on the number of open sockets and
the size and number of transported data packets. For memory blocks equal or smaller
than 4096 bytes, the TCP/IP stack allocates memory from this pre-allocated block.
Once allocated, the TCP/IP stack does not release this memory back to the system.
It will be internally recycled for further usage.
The default size of this memory block is 90 kBytes in the IPC@CHIP Large version and 98 kBytes in
the @CHIP-RTOS version including PPP.
Memory blocks larger than 4096 bytes are allocated directly from the @CHIP-RTOS memory.
The TCP/IP stack releases these blocks back to the IPC@CHIP memory management.
If your application requires a lot of memory you should avoid sending and receiving
frames larger than 2048 bytes. Larger packets should be split into some smaller
ones prior to sending.
With BIOS interrupt 0xA0 it is possible
to install a user error handler function, which will be called if the memory limit is reached.
Related Topics
-
- BIOSINT API Install a user fatal error handler
-
- IPC@CHIP TCP/IP memory chip.ini Configuration
Top of list Index page
Interrupt 0xAC service 0x79: SET_SERVER_IDLE_TIMEOUT, Control FTP/Telnet timeout
- Set/Get the Idle timeout for either the FTP or Telnet server.
Parameters
- AH
- 0x79 (= SET_SERVER_IDLE_TIMEOUT)
- AL
- 0: Set Timeout, Non-zero: Get Timeout
- BX
- 0: FTP Server, 1: Telnet Server
- DX
- Timeout value in seconds (If AL = 0 for set)
Return Value
- Set idle timeout -
DX = AX = 0: Success
AX = DX = -1: Server not provided
Get idle timeout -
AX = 0: DX contains timeout value
AX = DX = -1: Server not provided
Comments
- If input parameter AL is zero, this API inserts the new timeout value in DX into
the CHIP.INI. A reboot is not necessary for the new value to take affect.
If AL is non-zero, this API returns the existing timeout for the specified
server.
Related Topics
-
- FTP Timeout in chip.ini Configuration
-
- Telnet Timeout in chip.ini Configuration
Top of list Index page
Interrupt 0xAC service 0x7A: IP_USER_CB, Install IP callback function
- This function allows the application programmer to install an IP callback function.
Parameters
- AH
- 0x7A (= IP_USER_CB)
- ES:DI
- Pointer to IP callback function (or set to null to remove
a previously installed callback)
Return Value
- DX: 0, AX 0 success
Comments
- The application programmer can implement a function of the type (Borland C):
typedef int (huge *MyIpCallbackFuncPtr)(
IpUserCallbackInfo_t
far *ipInfo );
If a function of this type is installed by the user, the TCP/IP stack will
call this function for any incoming IP packet. Inside of this function
the user is able to check the given IP parameters (which are available through
the IpUserCallbackInfo_t
parameter) and decide whether the TCP/IP stack should process this packet or ignore it.
If the callback function returns -1 the incoming packet will be ignored by the
TCP/IP stack.
To remove the callback function, this API call must be called with
a null pointer in ES:DI.
Do not forget to uninstall the callback, if your application exits!
Top of list Index page
Interrupt 0xAC service 0x7B: ARP_USER_CB, Install ARP callback function
- This function allows the application programmer to install an ARP callback function.
Parameters
- AH
- 0x7B (= ARP_USER_CB)
- ES:DI
- Pointer to ARP callback function (or set to null to remove
a previously installed callback)
Return Value
- DX: 0, AX 0 Success
Comments
- The application programmer can implement a function from the type described below:
typedef int (huge *MyArpCallbackFuncPtr)(
ArpUserCallbackInfo_t
far *arpInfo );
If a function of this type is installed by the user, the TCP/IP stack will call this
function for any incoming ARP packet. The input parameter to the callback function
allows access to the ARP packet. Inside of this function the user is able to check the content
of the incoming ARP packet and decide whether the TCP/IP stack should process this packet
or ignore it. If the callback function returns -1, the incoming packet will be ignored
by the TCP/IP stack.
For structure of an ARP packet see ArpHeader.
To remove the callback function, this API call must be called with
a null pointer in ES:DI.
Do not forget to uninstall the callback, if your application exits!
Top of list Index page
Interrupt 0xAC service 0x80: ADD_DEFAULT_GATEWAY, Add the default gateway
- This function is used to add the default gateway for all interfaces.
Parameters
- AH
- 0x80 (= ADD_DEFAULT_GATEWAY)
- BX
- Device entry of the gateway,
0: Ethernet, 1: PPP server, 2: PPP client, 3: User device driver
- ES:DI
- Pointer to an unsigned long containing the gateway IP
in network byte order.
- DX:SI
- If BX == 3 DX:SI must contain
User device handle pointer.
Return Value
- DX: 0, AX 0 success
DX: -1, AX contains error code
Comments
- If this function is used, the gateway entry in the chip.ini becomes
invalidated, but unchanged.
If the PPP server or PPP client is specified in BX, the gateway is set to the remote
peer IP address.
Related Topics
-
- DEL_DEFAULT_GATEWAY API function
-
- DEV_OPEN_IFACE API function
-
- IP Gateway chip.ini Configuration
-
- PPP server Gateway chip.ini Configuration
Top of list Index page
Interrupt 0xAC service 0x81: DEL_DEFAULT_GATEWAY, Delete the default gateway
- This function is used to delete the default gateway.
Parameters
- AH
- 0x81 (= DEL_DEFAULT_GATEWAY)
- ES:DI
- Pointer to an unsigned long containing the gateway IP
to be deleted in network byte order.
Return Value
- DX: 0, AX 0 success
DX:-1, AX contains error code
Comments
- If this function is used, the gateway entry in the chip.ini becomes
invalidated, but unchanged.
Related Topics
-
- ADD_DEFAULT_GATEWAY API function
-
- IP Gateway chip.ini Configuration
-
- PPP server Gateway chip.ini Configuration
Top of list Index page
Interrupt 0xAC service 0x82: GET_DEFAULT_GATEWAY, Get the current default gateway
- This function is used to get the default gateway for all interfaces.
Parameters
- AH
- 0x82 (= GET_DEFAULT_GATEWAY)
- ES:DI
- Output Parameter: Pointer to user's unsigned
long variable where the gateway IP will be written.
Return Value
- DX = 0, AX = 0: Success. Location at [ES:DI] contains the
gateway IP in network byte order.
DX = -1: AX contains error code
Top of list Index page
Interrupt 0xAC service 0x83: ADD_STATIC_ROUTE, Add a route for an interface
- This function is used to add a route for an interface. It allows packets for
a different network to be routed by the interface.
Parameters
- AH
- 0x83 (= ADD_STATIC_ROUTE)
- BX
- Device entry of the gateway, 0: Ethernet, 1: PPP server,
2: PPP client, 3: User device driver
- DX:SI
- If BX = 3, DX:SI must contain
User device handle pointer.
- ES:DI
- Pointer to user Route_Entry
structure
Return Value
- DX = 0, AX = 0: Success
DX = -1: AX contains error code
Comments
- The Route_Entry structure is defined in tcpipapi.h:
Related Topics
-
- DEL_STATIC_ROUTE API function
Top of list Index page
Interrupt 0xAC service 0x84: DEL_STATIC_ROUTE, Delete a route for an interface
- This function is used to delete a route from an interface.
Parameters
- AH
- 0x84 (= DEL_STATIC_ROUTE)
- ES:DI
- Pointer to user Route_Entry
structure
Return Value
- DX: 0, AX 0 success
DX:-1, AX contains error code
Comments
- Only structure members destIPAddress and destNetmask
must be valid at the function's call.
Related Topics
-
- ADD_STATIC_ROUTE API function
Top of list Index page
Interrupt 0xAC service 0x88: DEL_ARP_ENTRY_BY_PHYS, Delete by physical address
- This function deletes the entry from the ARP table by the given physical address.
Parameters
- AH
- 0x88 (= DEL_ARP_ENTRY_BY_PHYS)
- ES:DI
- Pointer to physical address buffer (6 Byte)
Return Value
- DX: 0, AX 0 success
DX: -1, AX contains error code
Related Topics
-
- ADD_ARP_ENTRY Add ARP entry
-
- GET_ARPROUTE_CACHE Get ARP cache
Top of list Index page
Interrupt 0xAC service 0x89: ADD_ARP_ENTRY, Add an entry to the ARP table
- This function adds an entry into the Address Resolution Protocol
(ARP) table.
Parameters
- AH
- 0x89 (= ADD_ARP_ENTRY)
- BX:SI
- Pointer to IP address (unsigned long)
- ES:DI
- Pointer to physical address (6 Byte)
Return Value
- DX = 0, AX = 0: Success
DX = -1: Failure, AX contains error code
Related Topics
-
- DEL_ARP_ENTRY_BY_PHYS Delete ARP entry by physical address
-
- GET_ARPROUTE_CACHE Get ARP/ROUTE cache
Top of list Index page
Interrupt 0xAC service 0x8A: GET_ARPROUTE_CACHE, Read ARP/Route cache table
- This function returns all valid entries in the internal ARP/Route cache table.
Parameters
- AH
- 0x89 (= GET_ARPROUTE_CACHE)
- BX:SI
- Output Parameter: Pointer to a user provided array of 64 of
ArpRouteCacheEntry data
structures
for storing ARP/Route cache table.
Return Value
- DX = 0, AX = 0, the user provided array at [BX:SI] contains the
current ARP/Route cache table.
CX holds the number of valid entries in table.
Comments
- The array must provide 64 entries. The API call returns only a copy of
the current device interface variables. In order to always have the current table status,
it is necessary to cyclically (e.g. every 10 seconds) request the table with this API.
Related Topics
-
- DEL_ARP_ENTRY_BY_PHYS Delete ARP entry by physical address
-
- ADD_ARP_ENTRY Add ARP entry
Top of list Index page
Interrupt 0xAC service 0x8D: GET_IFACE_ENTRIES, Read table of TCP/IP device interfaces
- This function returns information about all installed TCP/IP device interfaces.
Parameters
- AH
- 0x8D (= GET_IFACE_ENTRIES)
- BX:SI
- Pointer to a user provided array of
Iface_Entry data structures
for storing the information.
- CX
- Number of data structures in array at [BX:SI]. Up to this number of
device interfaces will be reported.
Return Value
- DX = 0, the user provided array at [BX:SI] contains the current device interface information
AX = Number of entries reported in array at [BX:SI].
Top of list Index page
Interrupt 0xAC service 0x90: ADD_IGMP_MEMBERSHIP, Install an IP multicast address entry
- Install an IP multicast address entry to become a member of an IP multicast group.
Parameters
- AH
- 0x90 (= ADD_IGMP_MEMBERSHIP)
- ES:DI
- Pointer to multicast IP address of type unsigned long
- DS:SI
- Pointer to a 6 byte array that contains the corresponded Ethernet address
Return Value
- DX = 0, AX = 0: Success
DX = -1: AX contains error code,
invalid class D address, or no free entry in IGMP table available
Comments
- IP Multicasting is the Internet abstraction of hardware multicasting. It allows transmission of
IP datagrams to a group of hosts that form a single multicast group. Membership in a multicast group
is dynamic. Hosts may join or leave the group at any time. Each multicast group
has unique IP multicast address (Class D address). The first four bits of an IP multicast
address must match to binary 1110. IP multicast addresses range from 224.0.0.0 through
239.255.255.255.
For the usage of IP multicasting on an Ethernet interface, IP multicast addresses must be mapped to
Ethernet hardware addresses. The Ethernet device of the IPC@CHIP will be switched into the Ethernet
multicast mode. In this mode it receives any incoming IP packet with the mapped Ethernet multicast
address and forwards it to the TCP/IP layer.
Each IP multicast packet will be sent with the mapped Ethernet multicast address.
Because of the feature, that a multicast IP packet will be received by any member of a multicast group,
sending and receiving of IP multicast packets is only usable with UDP sockets (datagram sockets).
After installing a IP multicast address with this API, the application programmer is able use this
address as a destination address when sending datagrams. A UDP socket is able to receive datagrams
at the specified multicast address.
The maximum number of supported IP multicast addresses in the IPC@CHIP is limited to 15.
Before installing an IP multicast address, you can find out the corresponding Ethernet multicast address
with Map IP multicast address to Ethernet address API.
Using multicast addresses is only possible on the Ethernet interface.
Related Topics
-
- API function DROP_IGMP_MEMBERSHIP - Delete an IP multicast address entry
-
- API function MCASTIP_TO_MACADDR - Map IP multicast address to Ethernet address
Developer Notes This implementation does not support multicast routing.
Sending and receiving multicast datagrams works only at local network.
Top of list Index page
Interrupt 0xAC service 0x91: DROP_IGMP_MEMBERSHIP, Delete an IP multicast address entry
- Delete an IP multicast address entry, leaving a multicast host group.
Parameters
- AH
- 0x91 (= ADD_IGMP_MEMBERSHIP)
- ES:DI
- Pointer to multicast IP address of type unsigned long.
Return Value
- DX = 0, AX = 0: Success
DX = -1, AX = -1: IP address entry not found
Related Topics
-
- API function ADD_IGMP_MEMBERSHIP - Install an IP multicast address entry
-
- API function MCASTIP_TO_MACADDR - Map IP multicast address to Ethernet address
Top of list Index page
Interrupt 0xAC service 0x92: MCASTIP_TO_MACADDR, Map IP multicast address to Ethernet
- Maps an IP multicast address to the corresponding Ethernet address.
Parameters
- AH
- 0x92 (= MCASTIP_TO_MACADDR)
- ES:DI
- Pointer to multicast IP address of type unsigned long
- DS:SI
- Output Parameter: Pointer to a 6 byte array where
the generated Ethernet multicast address will be written.
Return Value
- DX = 0, AX = 0: Success, storage at DS:SI contains the generated Ethernet address
DX = -1, AX = -1: Invalid IP address
Comments
- This API function computes the MAC address in the following manner:
To map an IP multicast address to a corresponding Ethernet multicast address
place the low-order 23 bits of the IP multicast address into the low order
23 bits of the special Ethernet multicast address 01 00 5E 00 00 00
e.g. IP multicast address 224.0.0.1 becomes Ethernet address 01 00 5E 00 00 01
Related Topics
-
- API function ADD_IGMP_MEMBERSHIP - Install an IP multicast address entry
-
- API function DROP_IGMP_MEMBERSHIP - Delete an IP multicast address entry
Top of list Index page
Interrupt 0xAC service 0xA0: DEV_OPEN_IFACE, Install user device driver
- Open and install a user TCP device driver/interface at the internal TCP/IP stack of the @CHIP-RTOS.
Add a new link layer for TCP/IP communication.
Parameters
- AH
- 0xA0 (=DEV_OPEN_IFACE)
- ES:DI
- Pointer to user filled DevUserDriver
structure, which contains all needed information (device driver functions, etc.) for
the user's driver implementation.
Return Value
- DX = 0, AX = 0 (or =236): Success
The IfaceHandle member of
DevUserDriver structure at [ES:DI]
contains the valid Device Handle, which
will be required as a parameter for most of the other device interface API for this device.
If member variables iface_type and use_dhcp were set to 1, AX should
contain code 236. In this case, the user must make the additional call to
DEV_WAIT_DHCP_COMPLETE API
to wait for completion of the IP configuration by DHCP.
DX = -1: AX contains error code. Installation failed
Comments
- This is the first function to use when adding your own interface to the TCP/IP stack of the @CHIP-RTOS.
The TCP/IP API calls 0xA0 - 0xA7 allow the application developer to implement an additional TCP/IP driver
interface for a connected hardware device (e.g. connected UART or an Ethernet controller).
This new interface has its own IP configuration and is used by the TCP/IP stack for IP communication
in the same way as the pre-installed internal devices of the IPC@CHIP (e.g. Internal Ethernet,
PPP server or PPPclient).
For more detailed description and a generic example see
How to add an TCP/IP device driver/link layer interface.
On the first DEV_OPEN_IFACE call for installing a TCP/IP device driver, the
IfaceHandle member of the DevUserDriver
structure at [ES:DI] must be NULL. If an interface is closed with DEV_CLOSE_IFACE
and the user wants to reopen that device interface
(e.g. for changing IP configuration)
,
the IfaceHandle value set by the system in the first DEV_OPEN_IFACE call must be preserved.
You will find all needed types, constants and prototypes in the CLIB header files TCPIPAPI.H
and TCPIP.H.
Clib TCPIP.C implementation of this function:
int Dev_Open_Interface( DevUserDriver far * DriverInfo,
int * errorcode)
Please note: The API calls 0xA0 through 0xA7 for implementing your own TCP/IP device drivers
are not part of our six official @CHIP-RTOS versions. For ordering special version including this
feature, please contact support@beck-ipc.com.
Related Topics
-
- DEV_CLOSE_IFACE - Close device driver interface
-
- DEV_WAIT_DHCP_COMPLETE - Wait for DHCP IP configuration
-
- Example - Installing device driver
Top of list Index page
Interrupt 0xAC service 0xA1: DEV_CLOSE_IFACE, Close TCP/IP device driver/interface
- Close a TCP device driver/interface, remove an added link layer from the internal TCP/IP stack.
Parameters
- AH
- 0xA1 (=DEV_CLOSE_IFACE)
- ES:DI
- Device handle from
the IfaceHandle member of the DevUserDriver
structure used at the
DEV_OPEN_IFACE call.
Return Value
- DX = 0, AX = 0: Success.
DX = -1: AX contains error code
222: Invalid parameter
236: Closing already in progress
237: Device already closed
Comments
- This function closes the device driver/interface. It calls the driver close function
and deactivates the layer from the internal TCP/IP stack of the @CHIP-RTOS.
For more detailed description see
How to add a user device driver/link layer interface
Clib TCPIP.C implementation of this function:
int Dev_Close_Interface(DevUserIfaceHandle DevHandlePtr,
int * errorcode);
Related Topics
-
- DEV_OPEN_IFACE - Open device driver interface
Top of list Index page
Interrupt 0xAC service 0xA2: DEV_RECV_IFACE, Move received data
- Receive and process incoming data at the TCP/IP stack.
Parameters
- AH
- 0xA2 (=DEV_RECV_IFACE)
- ES:DI
- Device handle from
the IfaceHandle member of the DevUserDriver
structure used at the
DEV_OPEN_IFACE call.
Return Value
- DX = 0, AX = 0: Success.
DX = -1: Failure, AX contains error code
255: Insufficient memory to complete operation
Comments
- This function must be called to process incoming data on the TCP/IP stack. This
function in turn calls the driver receive function (specified by the DevRecv
member of the DevUserDriver
structure at the DEV_OPEN_IFACE call)
and inserts the received data into the receive queue
of the matching socket (if there is one). Any tasks waiting on the socket (sleeping at
RECV or
RECVFROM ) are then signaled that there
is new data available.
Only IGMP and ARP requests are directly processed in the task which does this call.
Do not call this API from inside of an ISR!
This function should be used only in combination with the
Wait for receive event API call
in the user's receiver task for their device driver interface.
For more detailed description see
How to add an TCP/IP device driver/link layer interface
Clib TCPIP.C implementation of this function:
int Dev_Recv_Interface( DevUserIfaceHandle DevHandlePtr,
int * errorcode);
Related Topics
-
- Example - Receiver Task which calls this API
-
- Example Receiver function which would be called by this API
Top of list Index page
Interrupt 0xAC service 0xA3: DEV_RECV_WAIT, Wait for received data
- Waits for data received signal from Interrupt Service Routine.
Parameters
- AH
- 0xA3 (=DEV_RECV_WAIT)
- ES:DI
- Device handle from
the IfaceHandle member of the DevUserDriver
structure used at the
DEV_OPEN_IFACE call.
Return Value
- DX = 0, AX = 0: Success
DX = -1: Failure, AX contains error code
255: Insufficient memory to complete operation
Comments
- This function sleeps until a DEV_NOTIFY_ISR
signal by the device's ISR indicates that received data is available.
This function should be used in combination with the
DEV_RECV_IFACE API within the user
implemented receiver task.
For more detailed description see
How to add a user device driver/link layer interface
Clib TCPIP.C implementation of this function:
int Dev_Recv_Wait(DevUserIfaceHandle DevHandlePtr,
int * errorcode);
Related Topics
-
- Example - Receiver Task
Top of list Index page
Interrupt 0xAC service 0xA4: DEV_NOTIFY_ISR, Signal from ISR
- Notify the TCP/IP stack from inside of an Interrupt Service Routine
that there is incoming data available and/or that the device has sent a
frame successfully.
Parameters
- AH
- 0xA4 (=DEV_NOTIFY_ISR)
- BX
- Number of available received packets
- CX
- Number of sent packets completed (provisional)
- ES:DI
- Device handle from
the IfaceHandle member of the DevUserDriver
structure used at the
DEV_OPEN_IFACE call.
Return Value
- DX = 0, AX = 0
Comments
- This function should only be called from the device driver specific ISR.
It can be used to signal a receiver task
which is waiting at the DEV_RECV_WAIT call.
In this case the number of received packets should be set in BX register.
The current implementation does not support a transmit task. The sent packets count
in CX is a provision for informing a transmit task about completion of packet transmission.
For more detailed description see
How to add a user device driver/link layer interface.
CLIB TCPIP.C implementation of this function:
int Dev_Notify_ISR( DevUserIfaceHandle DevHandlePtr,
unsigned int rcvdPackets,
unsigned int sentPackets);
Related Topics
-
- Example - User device ISR
Top of list Index page
Interrupt 0xAC service 0xA5: DEV_GET_BUF, Get a buffer from TCP/IP stack
- Get a buffer from TCP/IP stack's pre-allocated buffer for storing
incoming data from this device
Parameters
- AH
- 0xA5 (=DEV_GET_BUF)
- CX
- Number of bytes buffer required
- ES:DI
- Output Parameter: Pointer to a variable of type
DevUserBufferHandle
where the user buffer handle is stored. (This value is for internal
use.)
Return Value
- DX: 0, AX 0: Success. Returns in DS:SI a pointer to the
beginning of the allocated buffer
DX: -1, AX-1, DS=SI=0 (null pointer)
Comments
- This call should be only used inside the driver specific receive function (implemented
by the user). It allocates a buffer from the internal TCP/IP memory pool
which can be used for storing the incoming data.
The usage of this function is optional. It is not required, but is recommended that a user
work with these buffers from the TCP/IP memory pool.
For more detailed description see
How to add an TCP/IP device driver/link layer interface
Clib TCPIP.C implementation of this function:
int Dev_Get_Buffer( DevUserIfaceHandle DevHandlePtr,
unsigned char far * far * buf,
unsigned int len);
Related Topics
-
- Example Receiver function
-
- DevUserBufferHandle type definition
-
- IPC@CHIP TCP/IP memory chip.ini Configuration
Top of list Index page
Interrupt 0xAC service 0xA6: DEV_SND_COMPLETE, Signal message send complete
- This API signals the TCP/IP stack that the final frame in a message
has been sent. (Note that a message can be fragmented into
multiple link layer frames.)
Parameters
- AH
- 0xA6 (=DEV_SND_COMPLETE)
- ES:DI
- Device handle from
the IfaceHandle member of the DevUserDriver
structure used at the
DEV_OPEN_IFACE call.
Return Value
- DX = 0, AX = 0
Comments
- This function must be called from the driver send function (implemented by the user)
on completion of sending data. After this call, the TCP/IP stack of the @CHIP-RTOS
is able to reuse the transmission data buffer.
For more detailed description see
How to add an TCP/IP device driver/link layer interface
Clib TCPIP.C implementation of this function:
int Dev_Send_Complete(DevUserIfaceHandle DevHandlePtr);
Related Topics
-
- Example - User's Device Send Function
Top of list Index page
Interrupt 0xAC service 0xA7: DEV_WAIT_DHCP_COMPLETE, Wait for DHCP
- Waits for completion of IP configuration process by DHCP ("Dynamic Host
Configuration Protocol
"). This call must be used if
DEV_OPEN_IFACE API was called with DHCP enabled
(see use_dhcp ) in
DevUserDriver structure.
Parameters
- AH
- 0xA7 (=DEV_WAIT_DHCP_COMPLETE)
- CX
- Timeout seconds. This value will depend on the DHCP server used.
A minimum value of 15 seconds is recommended.
- ES:DI
- Pointer to same DevUserDriver
structure used at the DEV_OPEN_IFACE call.
Return Value
- DX = 0, AX = 0: Success
The
variables IPAddr and Netmask in the
DevUserDriver structure
contain the valid IP configuration.
The Dhcp_Data structure member points to the full
configuration data
provided by the DHCP server.
DX = -1: AX contains error code: 260 Timeout.
Comments
- Before calling this function, the device receiver task must be running.
For more detailed description see
How to add an TCP/IP device driver/link layer interface
You will find all needed types, constants and prototypes in the CLIB header files
TCPIPAPI.H and TCPIP.H.
Clib TCPIP.C implementation of this function:
int Dev_Wait_DHCP_Complete(
DevUserDriver far * DriverInfo,
unsigned int time_s,
int * errorcode)
Related Topics
-
- Example - User's receiver task
Top of list Index page
End of document
|