@CHIP-RTOS - TCP/IP Application Programmer's Interface

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

TCP/IP API Error Codes Listing
TCP/IP API Developer Notes
TCP/IP API Data Structures
TCP/IP API TCP/IP IPv4/v6 Dual layer stack
TCP/IP API Client/Server applications
TCP/IP API IP Security Data Structures

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

TCP/IP Interrupt 0xAC Services

Common TCP/IP Socket functions

DNS services

PPP client functions

PPP server functions

DHCP

Ping services

ARP/Routing

IP Multicast

Device driver API

IPsec/PKI/SSL functions

Crypto functions

Others

This function installs a far JMP opcode in the vicinity of the return instruction pointer to enter the specified API function directly from the user code.   This linking method is provided for efficiency in real-time applications.

Parameters

AH

0x00

AL

Index which specifies which TCP/IP API function is to be linked

Return Value

Instruction Pointer is moved back 10 bytes so that newly installed far JMP will execute immediately.

(Refer to respective linked function's documention for further return value information.)

Note: All dynamically linked functions are free to use all registers except for DS, SI, DI, and BP registers which are preserved. This matches Paradigm C, Borland C++ 5.02 and Microsoft Visual C 1.52 calling conventions.

Comments

Dynamic linking is implemented only for some of the TCP/IP API functions!

Interrupts are masked and restored to their state on entry.


Note:

The following information is provided only for completeness.   The user should generally have no need to know these details due to that only the provided C-Library functions should use this mechanism. (However, during debugging at a low level you may in some cases be interested in exactly what is going on here.)

A JMP FAR instruction will be written 10 bytes before the user's return instruction pointer. This far jump will transfer control directly into the RTOS from the user code when executed. This new far JMP will execute immediately upon return from this software interrupt due to the instruction pointer adjustment performed within the call.

Since the code at the calling site will be patched by this RTOS call, it is essential that it has exactly the following form (the link index carried in AL register will vary):

     JMP SHORT over_patch ; 2 bytes of code here
     NOP                  ; Never executed (1 byte)
     NOP                  ; Never executed (1 byte)
     NOP                  ; Never executed (1 byte)
over_patch:               ; Linker overwrites above 5 bytes
                          ; with JMP FAR instruction.
     MOV AX,000A2h        ; AH = 0x00, AL = 0xA2 =>
                          ; index for Dev_Recv_Interface().
     INT 0ACh

Developer Notes

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.15	V1.00

Creates an IPv4 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

Open IPv6 socket API_OPENSOCKET_IPV6

Close socket API_CLOSESOCKET

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

Open IPv4 socket API_OPENSOCKET

Open IPv6 socket API_OPENSOCKET_IPV6

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Bind a unnamed socket with an IP address and port number.

Parameters

AH

0x03 (= API_BIND)

BX

Socket descriptor

SC1x Parameters

DX:SI

Pointer to a sockaddr_in structure, the first three elements of which must be filled in by caller prior to calling.

SC1x3/SC2x Parameters

DX:SI

Pointer to a sockaddr_in structure (for IPv4 sockets) or to a sockaddr_in6 structure (for IPv6 sockets).   Caller must set the sin_family, sin_port and sin_addr (or sin6_family, sin6_port and sin6_addr for IPv6) elements 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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

SC1x Parameters

DX:SI

Pointer to a sockaddr_in structure containing host's IP address and port number.

SC1x3/SC2x Parameters

DX:SI

Pointer to a sockaddr_in (for IPv4 sockets) or sockaddr_in6 structure (for IPv6 sockets) containing host's IP address and port number.

Return Value

DX = 0 success AX: 0
DX != 0 AX: contains error code

SC1x Comments

The caller must fill in the first three elements (sin_family, sin_port and sin_addr) of the sockaddr_in data structure at [DX:SI] prior to calling here.

SC1x3/SC2x Comments

The caller must fill in the sin_family, sin_port and sin_addr elements of the sockaddr_in structure (IPv4) or the sin6_family, sin6_port and sin6_addr elements of the sockaddr_in6 structure (IPv6) at [DX:SI] prior to calling here.

Related Topics

Open IPv4 socket - API_OPENSOCKET

Open IPv6 socket - API_OPENSOCKET_IPV6

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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:  Failure, 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 TCP/IP stack's timing resolution is 100 milliseconds.   Therefore if a timeout value is set in the recv_params structure of less than 100 milliseconds, the RECV API call will timeout after 100 milliseconds.

SC1x Comments

The sender can be identified by the IP address and port number reported in the sockaddr_in data structure.
API_RECVFROM can only return complete UDP datagrams at the user provided buffer.   If the waiting datagram at the internal socket receive queue has size larger than the specified recv_param.bufferlength, API_RECVFROM returns with DX!=0 and AX error code 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.

SC1x3/SC2x Comments

The sender can be identified by the IP address and port number reported in the sockaddr_in structure (for IPv4 sockets) or in the sockaddr_in6 structure (for IPv6 sockets).
If the waiting datagram at the internal socket receive queue has size larger than the specified recv_param.bufferlength, API_RECVFROM returns with DX!=0 and AX error code 240. ("Message too long"). User buffer contains the truncated the datagram.

Related Topics

API_SENDTO - Send UDP datagram

API_RECV - Receive TCP data

API_SELECT - Socket select() operation

API_GETRCV_BYTES - Get waiting bytes on a socket

API_OPENSOCKET_IPV6 - Open IPv6 socket

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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 data structure which caller must fill in prior to call.

Return Value

DX = 0:   Success, AX contains the number of bytes sent
DX != 0:  Failure, AX contains error code

Comments

On success, the return value in AX register indicates the actual number of bytes sent.

SC1x 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.  

SC1x3/SC2x 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 (for IPv4 sockets) or by the sockaddr_in6 structure (for IPv6 sockets) referenced by the send_params.toPtr pointer.

Related Topics

API_RECVFROM - Receive UDP datagram

API_SEND - Send TCP data

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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).

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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 IPv4 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 IPv4 address value. This IP address is stored in network byte order.

Return Value

DX = 0    AX = 0, [ES:DI] contains converted 32 bit binary value
DX != 0    AX = -1, syntax error

Related Topics

Get IPv4 address of the Ethernet interface

Convert binary IPv4 address to ASCII dotted decimal

Convert IPv4 or IPv6 address ASCII string to binary

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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.

For new applications, the DOS interrupt 0x21 function is recommended.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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.

For new applications, the DOS interrupt 0x21 memory allocate service 0x48 and release service 0x49 are recommended.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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)

SC1x Parameters

DX:SI

Output Parameter:   Pointer to a sockaddr_in structure (see tcpipapi.h)

SC1x3/SC2x Parameters

DX:SI

Output Parameter:   Pointer to a sockaddr_in structure (for IPv4 sockets) or to a sockaddr_in6 structure (for IPv6 sockets).

Return Value

DX = 0    success, AX: contains new socket descriptor for the connection
DX != 0    failure, AX: contains error code

SC1x 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).

SC1x3/SC2x Comments

This call is used by a TCP server.

On success, this function fills in the sockaddr_in structure or sockaddr_in6 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

API_OPENSOCKET_IPV6 - Open IPv6 socket

IPV6 - Socket interface

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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 data 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.

If flag member of send_params 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.

Related Topics

API_RECV - Receive TCP data

API_SENDTO - Send UDP datagram

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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 data 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 may be less 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.

The TCP/IP stack's timing resolution is 100 milliseconds. Therefore if a time-out value is set in recv_params data structure less than 100 milliseconds, the RECV API call will time-out after 100 milliseconds.

Related Topics

API_SEND - Send TCP data

API_RECVFROM - Receive UDP datagram

API_SELECT - Socket select() operation

API_GETRCV_BYTES - Get waiting bytes on a socket

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Converts an unsigned long IPv4 address to an ASCII dotted decimal IP string.

Parameters

AH

0x11 (= API_INETTOASCII)

BX:SI

Input Parameter:   Pointer to the 32 bit IPv4 address in network byte order

ES:DI

Output Parameter:   Pointer to the string buffer, where this function outputs the converted ASCII dotted decimal IP string.   This buffer must have space for 16 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 IPv4 address string to binary

Convert binary IPv4 or IPv6 address to ASCII string

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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 function is used to abort a connection on a socket. It only works with TCP sockets and sends a RST and discards all outstanding data. The function does not close the socket.   (The API_CLOSESOCKET API must be used to close the socket.)

The reset socket cannot 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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Applies only to TCP sockets.

Parameters

AH

0x13 (= API_SETLINGER)

BX

Socket descriptor

CX

Linger time in seconds, default: 20 seconds, 0 means linger turned off.

Return Value

DX = 0    success
DX != 0    failure, AX: contains error code

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Controls option settings for specfied socket.

Parameters

AH

0x16 (= API_SETSOCKOPT)

BX

Socket descriptor

ES:DI

Pointer to a SetSocketOption type data structure that specifies the socket options

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 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

API_GETSOCKOPT - Get socket options

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Reads out an option setting for a specified socket.

Parameters

AH

0x17 (= API_GETSOCKOPT)

BX

Socket descriptor

ES:DI

Pointer to GetSocketOption data 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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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 or 237 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, until a successful connection is established. In this case the connect function returns error code 0 or 256 (socket is already connected).

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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 from specified events happens on a TCP socket connection.

Note that most of the call back calls will be made in the context of the drivers receive task (e.g. task ETH0). Therefore processing should be kept at a minimum in the call back function. The user call back function should set a flag or increase a counter and signal the user application task.

The callback function must be of the following type (Borland C):

void huge socketCallBackFunc(int socketdescriptor,
                             int eventFlags)

A socket callback may be removed by calling this API function with both a null null pointer in ES:DI and value 0 in register CX.   Closing the socket also deactivates the callback.   Before exiting a program, any sockets which have callbacks installed must either be closed or have the callback removed.   Otherwise a callback could be present which references a program no longer loaded into memory.

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 TCP callback functions

IP_USER_CB Install IP callback function

ARP_USER_CB Install ARP callback function

IP_USER_CB_SND Install IP callback function on outgoing packets

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Wait on specified events for a selected set of sockets.

Parameters

AH

0x1A (= API_SELECT)

SS:BX

Pointer to the first parameter passed to either the select() or select_ms() C-library API.   In either case this first parameter is the nfds argument.   The other parameters follow this one on the program stack, per the _cdecl calling convention.

Return Value

DX = 0
AX = hit count, which is the number of sockets for which bits have been set in the fd_set output bit fields.   On time-out or illegal input parameters, this count is zero.

Comments

This API provides functionality similar to the Berkeley sockets standard select() function.   The calling thread can wait for events on a set of sockets.   The function will return after either a time-out period or when one of the specified events occurs on one of the selected sockets.

Socket selection is specified by the input fd_set data structures.   Refer to the C-library function documentation for more information reqarding the set of input parameters that appear here at [SS:BX].

Beck C-Library Usage

select()

select_ms()

Related Topics

API_RECV Receive TCP message

API_RECVFROM Receive UDP message

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.22	V1.22	V1.22	V1.11	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	n/a	n/a

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	V0.90	V1.00

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 greater or equal to 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

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

SC1x3/SC2x Comments

Deprecated, because only IPv4 addresses can be stored at the provided 32-bit buffer [ES:DI].
Use API_GET_TCP_STATE_IP_ALL instead.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.04	V1.00	V1.00	V0.90	V1.00

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 data structure 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

If CX >= AX then all sockets in the socket table have been reported.

Note that the localPort and remotePort members of SocketInfo data structures are in little endian format.   The IfIpAddress and remoteIP members remain in network byte order (big endian).

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:

SC1x3/SC2x Comments

Deprecated, due to that only IPv4 addresses can be stored in the SocketInfo data structure.   The API_FINDALL_SOCKETS_IP_ALL function should instead be used, which also covers IPv6.

SC1x Comments

This function is only available in @CHIP-RTOS versions which contain the SNMP MIB feature.

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 %u Protocol %u, LocalPort %u",
     s[i].socIndex, s[i].protocol, s[i].localPort);
}

Related Topics

SocketInfo data structure

API_FINDALL_SOCKETS_IP_ALL Get information about all open sockets

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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

0x24 (= API_GET_TCP_STATE_IP_ALL)

BX

Local port (e.g. htons(23) for telnet)

ES:DI

Pointer to storage 16 Byte (IPv6 or IPv4) remote IP address

Return Value

AL: contains last TCP socket state (see below)

If AL!=20 and AL greater or equal to 2 (a TCP connection is established), the storage at ES:DI holds the 128 bit IPv6 (or mapped IPv4) address of the connected remote peer.   CX contains the remote peer's port number.   You can use the provided C-library macro IN6_IS_ADDR_V4MAPPED to determine if the stored address is a mapped IPv4 address.

Comments

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

The API function INET_NTOP provides the address conversion to ASCII text.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

Top of list
Index page

Find/return information about all open sockets at the internal socket table.

Parameters

AH

0x25 (= API_FINDALL_SOCKETS_IP_ALL)

ES:DI

Output Parameter:   Pointer to an array of CX SocketInfoIPv4v6 data 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

If CX >= AX then all sockets in the socket table have been reported.

Note that the localPort and remotePort members of SocketInfoIPv4v6 data structures are in little endian format.   The IfIpAddress and remoteIP members remain in network byte order (big endian).   IPv4 addresses will appear in the ip6Addr.ip6U32[3] member of the in6_addr data structures.

Below is an example of using API_FINDALL_SOCKETS_IP_ALL with the FindAllOpenSockets_IP_All C-library wrapper function.   This example lists up to 64 current entries in the TCP/IP socket table:

SocketInfoIPv4v6 s[64];
int avail, i;

avail = FindAllOpenSockets_IP_All(s, 64);
if (avail > 64) avail = 64;

for (i = 0; i < avail; i++)
{
   printf("\r\nSocket index %u Protocol %u, LocalPort %u",
     s[i].socIndex, s[i].protocol, s[i].localPort);
}

Related Topics

API_FINDALL_SOCKETS - Find all IPv4 sockets

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

Shutdown a socket in read, write or both directions.

Parameters

AH

0x26 (= API_SHUTDOWN)

AL

Direction: 0=Read, 1=write, 2=both

BX

socket descriptor

Return Value

DX = 0: Success
DX != 0: Failure AX contains error code

Comments

This API function only works on TCP sockets.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V0.90	V1.00

For UDP only, Same as API_RECVFROM but returns also the destination address to which this packet was sent.

Parameters

AH

0x27 (= API_RECVFROM_TO)

BX

Socket descriptor

DX:SI

Pointer to a recv_params data structure which caller must fill in prior to call.

ES:DI

Pointer to a user provided storage from type sockaddr_in structure, which contains (after sucessful return) the destination address of the received datagram.

Return Value

DX = 0:   Success, AX number of received bytes where 0 bytes indicates a timeout
DX != 0:  Failure, AX contains error code

DX = 0:   Success, AX number of received bytes where 0 bytes indicates a timeout
Storage pointed by ES:DI contains the destination address. DX != 0:  Failure, AX contains error code

Related Topics

API_RECVFROM - Receive UDP datagram

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

For UDP only, transmits message to another transport end-point via a specified interface.

Parameters

AH

0x28 (= API_SENDTO_IFACE)

BX

Socket descriptor

DX:SI

Pointer to a send_params data structure which caller must fill in prior to call.

ES:DI

Driver handle pointer Device handle, which caller must fill in prior to call. TCPIP send the packet via this specified Device handle.

Return Value

DX = 0:   Success, AX contains the number of bytes sent
DX != 0:  Failure, AX contains error code

Comments

This function is required, to send packets with a IP multicast destination address over a specified device. If packets with multicast address are send by using the existing API_SENDTO function, TCPIP will use as default the fixed SC1xx ethernet device. On success, the return value in AX register indicates the actual number of bytes sent.

SC1x 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.  

SC1x3/SC2x 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 (for IPv4 sockets) or by the sockaddr_in6 structure (for IPv6 sockets) referenced by the send_params.toPtr pointer.

Related Topics

API_SENDTO - Send UDP data

DEV_GET_HANDLE_BYNAME - Get device handle pointer

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.21	V1.21	V1.21	V1.10	V1.00

This function can be used to find the IPv4 addresses of a remote host associated to its domain name via the Domain Name Service (DNS).
The operating system manages a DNS cache. Thus it is save to call this software interrupt each time you want to connect to the respective domain. The function will not issue another request to the name server before the cached address has expired.

Parameters

AH

DNS_GET_HOST_BY_NAME (0x30)

ES:BX

Domain name of the host (e.g. "www.beck-ipc.com")

AL

Maximum number of IP addresses that the function is to return

CX:DX

Pointer to a buffer where the function is to store the found IP addresses; The buffer must be large enough to hold the number of IP addresses stated in the AL register. Ideally this should point to an array of type struct in_addr.

Return Value

Number of addresses actually stored in the given buffer or negative error code in AX

Comments

It is recommended to use the CLIB API call getHostByName instead of the software interrupt.

Related Topics

DNS_GET_HOST_BY_NAME2

DNS_GET_HOST_BY_ADDR

DNS_GET_HOST_BY_ADDR2

DNS_GET_MAIL_HOSTS

DNS_SET_NAME_SERVER

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.05	V1.00

This function can be used to find the IPv6 addresses of a remote host associated to its domain name via the Domain Name Service (DNS).
The operating system manages a DNS cache. Thus it is save to call this software interrupt each time you want to connect to the respective domain. The function will not issue another request to the name server before the cached address has expired.

Parameters

AH

DNS_GET_HOST_BY_NAME2 (0x31)

ES:BX

Domain name of the host (e.g. "www.beck-ipc.com")

AL

Maximum number of IP addresses that the function is to return

CX:DX

Pointer to a buffer where the function is to store the found IP addresses; The buffer must be large enough to hold the number of IP addresses stated in the AL register. Ideally this should point to an array of type struct in6_addr.

Return Value

Number of addresses actually stored in the given buffer or negative error code in AX

Comments

It is recommended to use the CLIB API call getHostByName2 instead of the software interrupt.

Related Topics

DNS_GET_HOST_BY_NAME

DNS_GET_HOST_BY_ADDR

DNS_GET_HOST_BY_ADDR2

DNS_GET_MAIL_HOSTS

DNS_SET_NAME_SERVER

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.05	V1.00

This function can be used to find the (canonical) domain name associated with a host by one of its IPv4 addresses via the Domain Name Service (DNS).
The operating system manages a DNS cache. Thus it is save to call this software interrupt each time you need the respective domain name. The function will not issue another request to the name server before the cached name has expired.

Parameters

AH

DNS_GET_HOST_BY_ADDR (0x32)

ES:BX

Pointer to the host's IP address of type struct in_addr

CX:DX

Pointer to a buffer where the function is to store the domain name; A domain name can be up to 254 characters long. Adding one byte for the trailing zero byte of the string, the buffer must have a size of at least 255 bytes.

Return Value

Zero in case of success or negative error code in AX

Comments

It is recommended to use the CLIB API call getHostByAddr instead of the software interrupt.

Related Topics

DNS_GET_HOST_BY_NAME

DNS_GET_HOST_BY_NAME2

DNS_GET_HOST_BY_ADDR2

DNS_GET_MAIL_HOSTS

DNS_SET_NAME_SERVER

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.05	V1.00

This function can be used to find the (canonical) domain name associated with a host by one of its IPv6 addresses via the Domain Name Service (DNS).
The operating system manages a DNS cache. Thus it is save to call this software interrupt each time you need the respective domain name. The function will not issue another request to the name server before the cached name has expired.

Parameters

AH

DNS_GET_HOST_BY_ADDR2 (0x33)

ES:BX

Pointer to the host's IP address of type struct in6_addr

CX:DX

Pointer to a buffer where the function is to store the domain name; A domain name can be up to 254 characters long. Adding one byte for the trailing zero byte of the string, the buffer must have a size of at least 255 bytes.

Return Value

Zero in case of success or negative error code in AX

Comments

It is recommended to use the CLIB API call getHostByAddr2 instead of the software interrupt.

Related Topics

DNS_GET_HOST_BY_NAME

DNS_GET_HOST_BY_NAME2

DNS_GET_HOST_BY_ADDR

DNS_GET_MAIL_HOSTS

DNS_SET_NAME_SERVER

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.05	V1.00

Use this function to determine the mail host(s) of a domain, i.e. the host accepting internet mail for the domain.
The operating system manages a DNS cache. Thus it is save to call this software interrupt each time you need the respective mail host. The function will not issue another request to the name server before the cached mail host entry has expired.

Parameters

AH

DNS_GET_MAIL_HOSTS (0x34)

ES:BX

Domain name to find mail hosts for (e.g. "beck-ipc.com")

AL

Maximum number of host names that the function is to return

CX:DX

Pointer to an array of type DnsMailHost where domain name and preference value of the mail hosts will be stored; The array must be large enough to hold the number of entries passed in AL register.

Return Value

Number of mail hosts actually stored or negative error code in AX

Comments

It is recommended to use the CLIB API call getMailHosts instead of the software interrupt.

Related Topics

DNS_GET_HOST_BY_NAME

DNS_GET_HOST_BY_NAME2

DNS_GET_HOST_BY_ADDR

DNS_GET_HOST_BY_ADDR2

DNS_SET_NAME_SERVER

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.05	V1.00

This function can be used to add a prioritised name server which will be queried before all other name servers. Normally the DNS resolver determines name server addresses automatically from network devices configured via DHCP or PPP. In addition you can specify two name servers in the CHIP.INI configuration file. Name servers found via DHCP have the lowest priotity. Next come name servers found via PPP, then the two configured in CHIP.INI. The name server added here has the highest priority. Note that calling this function a second time overwrites the name server address added first.

Parameters

AH

DNS_SET_NAME_SERVER (0x35)

CX

Address family, AF_INET for IPv4 or AF_INET6 for IPv6

ES:BX

Pointer to the IP address of the name server; should point to a structure of either type struct in_addr or struct in6_addr.

Return Value

Zero in case of success or negative error code in AX

Comments

It is recommended to use the CLIB API call setNameServer instead of the software interrupt.

Related Topics

DNS_GET_HOST_BY_NAME

DNS_GET_HOST_BY_NAME2

DNS_GET_HOST_BY_ADDR

DNS_GET_HOST_BY_ADDR2

DNS_GET_MAIL_HOSTS

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.05	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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!!

SC1x3/SC2x Comments

This API applies to IPv4 PPP connections.

Related Topics

PPPCLIENT_OPEN_IPV6 - Open IPv6 PPP client connection

PPPCLIENT_CLOSE - Closes PPP client connection

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Opens a PPP client connection with IPv6 Control protocol (IPv6CP).

Parameters

AH

0x46 (= PPPCLIENT_OPEN_IPV6)

ES:DI

Pointer to a PPPClient_Init_IPv6 type data structure (declared in 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

IPv6 address configuration is done by a auto negotiation process.   At connection time the peers negotiate an Interface-ID for the PPP device and auto configure their link-local scope addresses.   After sucessful return of this function, the PPPClieipAddrStr and PPPClieRemipAddrStr members of the PPPClient_Init_IPv6 data structure are filled with the negotiated IPv6 addresses.   By default they contain the :: zero address.

Refer to the PPP6CLIE.C example for how to use this API.   Also see the PPPClient_Init_IPv6 data structure documentation.

Note:   Only one PPP client connection can be open at a time!!

Related Topics

PPPCLIENT_OPEN - Open IPv4 PPP client connection

PPPCLIENT_CLOSE - Closes PPP client connection

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

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

After this API returns, the PPP client after closing the PPP session executes the modem hang-up commands specified in the PPPClient_Init data structure that was provided at the PPPCLIENT_OPEN call.   Therefore we recommend waiting approximately 10 seconds before opening a subsequent PPP connection to assure that this hang-up command sequence has completed.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

SC1x 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 - PPP client installed check

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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 IPv4 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.

SC1x3/SC2x Comments

At the current @Chip-RTOS version, only IPv4 addresses are supported.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.04	V1.00	V1.00	V0.90	V1.00

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 = 0

Comments

If you want to use this function, you have to call it before opening a connection (see related links below).   Setting 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.

Here is an example which sets three PPP options using the Beck C-Library wrapper functions:

unsigned int  ipcp_comp   = 1;
unsigned long DNS_Pri_IP  = 0L;
unsigned long DNS_Sec_IP  = 0L;

PPP_Option My_Options[] = {

     // Allow remote peer to use VJ TCPIP header compression.
  { PPP_IPCP_PROTOCOL, PPP_OPTION_ALLOW, PPP_IPCP_COMP_PROTOCOL,
     (const char *)&ipcp_comp, sizeof(ipcp_comp)},

    // Allow remote peer to set primary DNS IP.
  { PPP_IPCP_PROTOCOL, PPP_OPTION_WANT, PPP_IPCP_DNS_PRI,
     (const char *)&DNS_Pri_IP, sizeof(DNS_Pri_IP)},

    // Allow remote peer to set secondary DNS 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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	V0.90	V1.00

Pause/Resume the PPP client task.

Parameters

AH

0x47 (= PPPCLIENT_PAUSE)

BX

1: Pause the PPP client task
0:resume.

Return Value

AX = 0, DX = 0 PPP client task is halted
AX != 0: DX holds special failure reason code
            DX == -1 Action not allowed due to the current state ot the PPP client
            DX == -2 PPP client is not running (disabled)
            DX == -3 PPP client timeout failure (should not happen)

Comments

If this API function is called with parameter pause=1, the PPP client task stops listening for incoming data at the serial RS232 port . No data is send.
The RS232 port of the PPP client is now ready to use for other purposes.
The client task must be resumed by a call of this function with parameter pause==0.
Please note: If the PPP client is halted during a running PPP session, the PPP session could be closed by the remote peer.
The internal idle timeout counters are cleared, if the client was halted by this call.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.30	V1.30

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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 specified in BX.

Related Topics

PPPSERVER_ACTIVATE API - Reactivate PPP server

PPPSERVER HANGUPTIMEOUTx - CHIP.INI timeout for wait on answer from modem

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

Comments

If the PPP server is disabled from start up by the CHIP.INI configuration entry, this API function will start the server.

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

SC1x3/SC2x Comments

Only PPP IPv4 connections are supported by this API.

Related Topics

PPPSERVER_GET_CFG_IPV6 - Get PPP IPv6 configuration

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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.

Here is an example which sets three PPP options using the C-Library wrapper functions:

unsigned int  ipcp_comp   = 1;
unsigned long DNS_Pri_IP  = 0L;
unsigned long DNS_Sec_IP  = 0L;

PPP_Option My_Options[] = {

   // Allow remote peer to use VJ TCPIP header compression.
  { PPP_IPCP_PROTOCOL, PPP_OPTION_ALLOW, PPP_IPCP_COMP_PROTOCOL,
     (const char *)&ipcp_comp, sizeof(ipcp_comp)},

   // Allow remote peer to set primary DNS IP.
  { PPP_IPCP_PROTOCOL, PPP_OPTION_WANT, PPP_IPCP_DNS_PRI,
     (const char *)&DNS_Pri_IP, sizeof(DNS_Pri_IP)},

   // Allow remote peer to set secondary DNS 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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.03	V1.00	V1.00	V0.90	V1.00

Gets the current main IPv6 configuration data of the PPP server.

Parameters

AH

0x56 (= PPPSERVER_GET_CFG_IPV6)

ES:DI

Output Parameter:   Pointer to PPP_IPCfg_Data_IPv6 data structure where this function will report the configuration data.

Return Value

DX != 0 AX != 0:   PPP server is not installed
DX = 0:   The caller's PPP_IPCfg_Data_IPv6 structure at [ES:DI] is filled with the PPP server IPv6 configuration data

Comments

Only PPP IPv6 connections are supported by this API.   IPv6 address configuration is done by a auto negotiation process.   At connection time the peers negotiate an Interface-ID for the PPP device and auto configure their link-local scope addresses.   If a connection is established, the IP and RemoteIP members of the PPP_IPCfg_Data_IPv6 data structure are filled with the negotiated addresses.   By default, they contain the "::" zero address.

Related Topics

PPPSERVER_GET_CFG - Get PPP IPv4 configuration

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V0.90	V1.00

Pause/Resume the PPP server.

Parameters

AH

0x57 (= PPPSERVER_PAUSE)

BX

1: Pause the PPP server task
0:resume.

Return Value

AX = 0, DX = 0 PPP server task is halted
AX != 0: DX holds special failure reason code
            DX == -1 Action not allowed due to the current state ot the PPP server
            DX == -2 PPP server is not running (disabled)
            DX == -3 PPP server timeout (should not happen)

Comments

If this API function is called with parameter pause=1, the PPP server stops listening for incoming data at the serial RS232 port . No data is send.
The RS232 port of the PPP server is now ready to use for other purposes.
The server must be resumed by a call of this function with parameter pause==0.
Please note: If the PPP server is halted during a running PPP session, the PPP session could be closed by the remote peer.
The internal idle timeout counters are cleared, if the server was halted by this call.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.30	V1.30

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 (100 Hz counter).

DS:SI

If parameter AL==7, DS:SI must contain the address of a buffer into which up to CX far pointers to IpMib data structures can be reported by this API.   Otherwise these registers are not referenced.

CX

If parameter AL==7, CX specifies the number of far pointers (capacity) which the user buffer at [DS:SI] can hold.   Otherwise it is not referenced.

Return Value

DX != 0 AX != 0 : @CHIP-RTOS without internal SNMP MIB variables

DX = AX = 0: Success, return values depend on AL input value.

If input parameter AL was 7:

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.


Otherwise (AL was 1..6, or 8):

ES:DI contains a pointer to the requested @CHIP-RTOS data structure

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.

SC1x Comments

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 SC1x @CHIP-RTOS variants.   It is necessary to order directly a @CHIP-RTOS variant which includes this feature.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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: Success

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.01	V1.00	V1.00	V0.90	V1.00

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: Success

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.01	V1.00	V1.00	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.01	V1.00	V1.00	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.01	V1.00	V1.00	V0.90	V1.00

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.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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!

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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 received 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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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 received 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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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.

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.

SC1x Comments

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.

SC1x3/SC2x Comments

The default size of this memory block is 140 kBytes.

Related Topics

BIOSINT API Install a user fatal error handler

IPC@CHIP® TCP/IP memory chip.ini Configuration

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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.   If the Telnet timeout is changed, a reboot is not necessary for the new value to take affect. If the FTP timeout is changed, a reboot is required, before the new time-out value takes 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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	V0.90	V1.00

This function allows the application programmer to install an callback function on incoming IPv4 packets.

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 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 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!

SC1x3/SC2x Comments

Important:    The callback will only execute on incoming IPv4 packets.

Related Topics

API_REGISTERCALLBACK Install TCP callback function

API_REGISTERCALLBACK_PASCAL For Pascal TCP callback functions

ARP_USER_CB Install ARP callback function

IP_USER_CB_SND Install IP callback function on outgoing packets

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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. If the size of the returned structure ArpUserCallbackInfo_t is equal or bigger 12, the structure now contains a devicehandle_ptr to determine the source device of the incoming packet.

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!

Related Topics

API_REGISTERCALLBACK Install TCP callback function

API_REGISTERCALLBACK_PASCAL For Pascal TCP callback functions

IP_USER_CB Install IP callback function

IP_USER_CB_SND Install IP callback function on outgoing packets

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.22	V1.22	V1.22	V1.11	V1.00

This function allows the application programmer to install an IP callback function on outgoing IP packets.

Parameters

AH

0x7C (= IP_USER_CB_SND)

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 far *ipInfo );

If a function of this type is installed by the user, the TCP/IP stack will call this function for any outgoing IP packet.   Inside of this function the user is able to check the given IP parameters (which are available through the IpUserCallbackInfo type at the ipInfo parameter) and decide whether the TCP/IP stack should process this packet or ignore it.

If the callback function returns -1 the TCP/IP stack doesn't send this packet.

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!

SC1x3/SC2x Comments

Important:    The callback will only execute on incoming IPv4 packets.

Related Topics

API_REGISTERCALLBACK Install TCP callback function

API_REGISTERCALLBACK_PASCAL For Pascal TCP callback functions

IP_USER_CB Install IP callback function

ARP_USER_CB Install ARP callback function

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.11	V1.01	V1.01	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

This function is used to add a route for an interface.   It allows packets for a different network to be routed to 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:

SC1x3/SC2x Comments

Important:    The current SC1x3/SC2x Chip-RTOS version supports only route definitions based on the IPv4 protocol.

Related Topics

DEL_STATIC_ROUTE API function

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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.

SC1x3/SC2x Comments

Important:    The current SC1x3/SC2x Chip-RTOS version supports only route definitions based on the IPv4 protocol.

Related Topics

ADD_STATIC_ROUTE API function

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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 ARP entries 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 ARP entries 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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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].

SC1x3/SC2x Comments

This function return only the IPv4 configuration of the found TCP/IP device interfaces.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

This function sets the MTU (Maximum Transfer Unit) size of a device interface.

Parameters

AH

0x8E (= SET_IFACE_MTU)

BX

Interface number
0:internal ethernet interface
1:internal ppp server
2:internal ppp client
3:user specific: interface handle at es:di

CX

MTU

ES:DI

if bx==3, ES:DI must contain the User device handle pointer.

Return Value

DX: 0, AX 0 success
DX:-1, AX contains error code

Related Topics

DEV_OPEN_IFACE API function

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.11	V1.01	V1.01	V0.90	V1.00

This function returns information about all installed TCP/IP device interfaces.

Parameters

AH

0x8F (= GET_IFACE_ENTRIES_EXT)

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].

Comments

This function is different from GET_IFACE_ENTRIES. It stores at the user provided array from type structures all ip configurations (IP multihoming on one interface) of each interface found, not only the first one.

SC1x3/SC2x Comments

This function return only the IPv4 configuration of the found TCP/IP device interfaces.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V1.05	V1.00

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 IPv4 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.

This implementation does not support multicast routing.   Sending and receiving multicast datagrams works only at local network.
Using multicast addresses is only possible on the Ethernet interface.  

SC1x3/SC2x Comments

This function supports only IPv4 multicast addressing.

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	V0.90	V1.00

Delete an IP multicast address entry, leaving a multicast host group.

Parameters

AH

0x91 (= ADD_IGMP_MEMBERSHIP)

ES:DI

Pointer to multicast IPv4 address of type unsigned long

Return Value

DX = 0, AX = 0:   Success
DX = -1, AX = -1:   IP address entry not found

SC1x3/SC2x Comments

This function supports only IPv4 multicast addressing.

Related Topics

API function ADD_IGMP_MEMBERSHIP - Delete an IP multicast address entry

API function MCASTIP_TO_MACADDR - Map IP multicast address to Ethernet address

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	V0.90	V1.00

Maps an IP multicast address to the corresponding Ethernet address.

Parameters

AH

0x92 (= MCASTIP_TO_MACADDR)

ES:DI

Pointer to multicast IPv4 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

SC1x3/SC2x Comments

This function supports only IPv4 multicast addressing.

Related Topics

API function ADD_IGMP_MEMBERSHIP - Install an IP multicast address entry

API function DROP_IGMP_MEMBERSHIP - Delete an IP multicast address entry

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	V0.90	V1.00

This function is used to get the IP address and net mask assigned to a user device.

Parameters

AH

0x9F (=DEV_GET_IP)

ES:DI

Device handle from the IfaceHandle member of the DevUserDriver structure used at the DEV_OPEN_IFACE call.

DX:SI

Output Parameter:   Pointer to the buffer, where the 32 bit IP address will be stored by this API in network byte order.

BX:CX

Output Parameter:   Pointer to the buffer, where the 32 bit net mask will be stored by this API in network byte order.

Return Value

DX = 0, AX = 0, success
DX = -1, AX contains error code

Comments

This API is used to get the IP address information from a user device interface.   This function can be useful for PPP client user defined devices.

The C-library implementation of this function has the prototype:

int Dev_Get_IP( DevUserIfaceHandle DevHandlePtr,
                         long * ipaddr,
                         long * netmask,
                         int * errorcode) ;

Related Topics

DEV_PPP_GET_PEER_IP - Get PPP peer IP address

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V1.05	V1.00

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 DEV_ETHERNET (=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 0x9F - 0xB3 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 PPP client).

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.

The DEV_ADD_ONLY flag bit can be OR'ed into the iface_type member of DevUserDriver structure in order to add the new device interface to the TCP/IP stack without immediately configuring this new device.   In this way, PPP options may be set between a first call to DEV_OPEN_IFACE which adds a new interface and a subsequent call to configure the interface.

You will find all needed types, constants and prototypes in the CLIB header files TCPIPAPI.H and TCPIP.H.

The C-library implementation of this function has the prototype:

int Dev_Open_Interface( DevUserDriver far * DriverInfo,
                        int * errorcode)

SC1x3/SC2x Comments

At the current SC1x3/SC2x CHIP-RTOS version, the device driver interface only supports IPv4.

The SC1x3 CHIP-RTOS also supports the PPPoE client interface (DEV_PPPoE_CLIENT).

Related Topics

DEV_CLOSE_IFACE - Close device driver interface

DEV_WAIT_DHCP_COMPLETE - Wait for DHCP IP configuration

Example - Installing device driver

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V1.05	V1.00

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

The C-library implementation of this function has the prototype:

int Dev_Close_Interface(DevUserIfaceHandle DevHandlePtr,
                        int * errorcode);

SC1x3/SC2x Comments

At the current SC1x3/SC2x CHIP-RTOS version, the device driver interface only supports IPv4.

Related Topics

DEV_OPEN_IFACE - Open device driver interface

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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

The C-library implementation of this function has the prototype:

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

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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

The C-library implementation of this function has the prototype:

int Dev_Recv_Wait(DevUserIfaceHandle DevHandlePtr,
                  int * errorcode);

Related Topics

Example - Receiver Task

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

Notify the TCP/IP stack from inside of an Interrupt Service Routine that there is incoming data available and/or 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.

The C-library implementation of this function has the prototype:

int Dev_Notify_ISR( DevUserIfaceHandle DevHandlePtr,
                    unsigned int rcvdPackets,
                    unsigned int sentPackets);

Related Topics

Example - User device ISR

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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

Size of buffer required, number of bytes

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 only be 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

The C-library implementation of this function has the prototype:

int Dev_Get_Buffer( DevUserBufferHandle BufHandlePtr,
                    unsigned char far * far * buf,
                    unsigned int len);

Related Topics

Example Receiver function

DevUserBufferHandle type definition

IPC@CHIP® TCP/IP memory chip.ini Configuration

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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

The C-library implementation of this function has the prototype:

int Dev_Send_Complete(DevUserIfaceHandle DevHandlePtr);

Related Topics

Example - User's Device Send Function

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

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.   The C-library implementation of this function has the prototype:

int Dev_Wait_DHCP_Complete( DevUserDriver far * DriverInfo,
                            unsigned int time_s,
                            int * errorcode)

Related Topics

Example - User's receiver task

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.10	V1.00	V1.00	V0.90	V1.00

When acting as an PPP server, a function must be called to validate an incoming authentication request. The prototype of the user provided function is defined to be:

    char huge * myCHAPAuthenticate(char *username) ;

which returns the password (secret) corresponding to this user.   If the user name is invalid, this callback function must return a NULL pointer.

Parameters

AH

0xA8 (=DEV_PPP_REGISTER_CHAP)

ES:DI

Device handle from the IfaceHandle member of the DevUserDriver structure used at the DEV_OPEN_IFACE call.

DS:SI

Pointer to the authentication callback function.

Return Value

DX = 0, AX = 0, success
DX = -1, AX = 222, Invalid driver handle specified

Comments

The C-library implementation of this function has the prototype:

int Dev_PPP_Register_Chap( DevUserIfaceHandle DevHandlePtr,
                           const void * AuthCallbackFunction,
                           int * errorcode) ;

SC1x Comments

This function is only available in @CHIP-RTOS variants with the PPP feature included.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.11	V1.01	V1.01	V0.90	V1.00

When acting as an PPP server, a function must be called to validate an incoming authentication request.   The prototype of the user provided function is defined to be:

    int huge myPAPAuthenticate(char *username,char * password) ;

which returns 1 for a valid username/password pair, else 0.

Parameters

AH

0xA9 (=DEV_PPP_REGISTER_PAP)

ES:DI

Device handle from the IfaceHandle member of the DevUserDriver structure used at the DEV_OPEN_IFACE call.

DS:SI

Pointer to the authentication callback function.

Return Value

DX = 0, AX = 0, success
DX = -1, AX = 222, Invalid driver handle specified

Comments

The C-library implementation of this function has the prototype:

int Dev_PPP_Register_Pap( DevUserIfaceHandle DevHandlePtr,
                          const void * AuthCallbackFunction,
                          int * errorcode) ;

SC1x Comments

This function is only available in @CHIP-RTOS variants with the PPP feature included.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.11	V1.01	V1.01	V0.90	V1.00

This function is used to set the PPP options, that we want to negotiate as well those options that we will allow.

Parameters

AH

0xAA (=DEV_PPP_SET_OPTION)

ES:DI

Device handle from the IfaceHandle member of the DevUserDriver structure used at the DEV_OPEN_IFACE call.

DS:SI

Pointer to user filled PPP_Option structure, which contains all needed option parameters.

Return Value

DX = 0, AX = 0, success
DX = -1, AX contains error code

Comments

The C-library implementation of this function has the prototype:

int Dev_PPP_Set_Option( DevUserIfaceHandle DevHandlePtr,
                        PPP_Option * ppp_option,
                        int * errorcode) ;

SC1x Comments

This function is only available in @CHIP-RTOS variants with the PPP feature included.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.11	V1.01	V1.01	V0.90	V1.00

This function is used to get the PPP address, that the remote peer has used.

Parameters

AH

0xAB (=DEV_PPP_GET_PEER_IP)

ES:DI

Device handle from the IfaceHandle member of the DevUserDriver structure used at the DEV_OPEN_IFACE call.

DS:SI

Output Parameter:   Pointer to the buffer, where the peer address will be stored by this API.

Return Value

DX = 0, AX = 0, success
DX = -1, AX contains error code

Comments

If a default gateway should be added for that interface, then the retrieved IP address should be used.

The C-library implementation of this function has the prototype:

int Dev_PPP_Get_Peer_IP( DevUserIfaceHandle DevHandlePtr,
                         long * Address,
                         int * errorcode) ;

SC1x Comments

This function is only available in @CHIP-RTOS variants with the PPP feature included.

Related Topics

DEV_GET_IP - Get user device interface IP address

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.11	V1.01	V1.01	V0.90	V1.00

This function is used to return the DNS addresses as negotiated by the remote PPP server.

Parameters

AH

0xAC (=DEV_PPP_GET_PEER_DNS)

ES:DI

Device handle from the IfaceHandle member of the DevUserDriver structure used at the DEV_OPEN_IFACE call.

BX

Flag 1: Primary DNS address 2: Secondary DNS address

DS:SI

Pointer to the buffer, where the DNS address will be stored into.

Return Value

DX = 0, AX = 0, success
DX = -1, AX contains error code

Comments

The C-library implementation of this function has the prototype:

int Dev_PPP_Get_Peer_DNSIP( DevUserIfaceHandle DevHandlePtr,
                            long * Address,
                            int flag,
                            int * errorcode) ;

SC1x Comments

This function is only available in @CHIP-RTOS variants with the PPP feature included.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.11	V1.01	V1.01	V0.90	V1.00