www.beck-ipc.com

TCP/IP Application Programmer's Interface - SC12 @CHIP-RTOS V1.10


    IPC@CHIP Documentation Index          TCP/IP API News

TCP/IP API

This interface provides access to the IPC@CHIP TCP/IP stack's socket interface for programming TCP/IP applications.   The TCP/IP API are all reached though software interrupt 0xAC.  The desired service is selected with the high order byte of the AX register (AH).

Please note, that we cannot explain the entire functionality of the TCP/IP protocol and the working of the socket interface in this document.   Good books for understanding TCP/IP and the socket interface are:
    1. Internetworking with TCP/IP, Volume 1-3 from Douglas E.Comer
    2. TCP/IP Illustrated, Volume 1 from W. Richard Stevens

For some useful comments see Programming notes.

All needed constants (e.g. API_OPENSOCKET) and data structures are defined in the header file tcpipapi.h.


TCP/IP API News
TCP/IP API Error Codes Listing
TCP/IP API Developer Notes
TCP/IP API Data Structures
TCP/IP API Client/Server applications

Notes :

  • "Network byte order" is big endian (like Motorola machines, unlike Intel), where most significant byte appears at the lowest address byte of a multibyte integer.
  • At return of most API the DX-Register is used for error checking:
      DX:   =  0 =API_ENOERROR ==> success
      DX:   = -1 =API_ERROR       ==> error, AX contains error code
API Functions :

  • Interrupt_0xAC_function_0x01:_API_OPENSOCKET, open a socket
  • Interrupt_0xAC_function_0x02:_API_CLOSESOCKET, close a socket
  • Interrupt_0xAC_function_0x03:_API_BIND, bind TCP or UDP server socket
  • Interrupt_0xAC_function_0x04:_API_CONNECT, Connect to another socket
  • Interrupt_0xAC_function_0x05:_API_RECVFROM, Receive UDP message
  • Interrupt_0xAC_function_0x06:_API_SENDTO, Transmit a UDP datagram
  • Interrupt_0xAC_function_0x07:_API_HTONS, Convert byte order
  • Interrupt_0xAC_function_0x08:_API_INETADDR, Convert an IP-String to binary
  • Interrupt_0xAC_function_0x09:_API_SLEEP, Sleep
  • Interrupt_0xAC_function_0x0A:_API_MALLOC, Allocate memory
  • Interrupt_0xAC_function_0x0B:_API_FREE, Free an allocated buffer
  • Interrupt_0xAC_function_0x0C:_API_GETRCV_BYTES, Get waiting bytes count
  • Interrupt_0xAC_function_0x0D:_API_ACCEPT, Accept the next incoming connection
  • Interrupt_0xAC_function_0x0E:_API_LISTEN, Listen for incoming connections
  • Interrupt_0xAC_function_0x0F:_API_SEND, Transmit TCP message
  • Interrupt_0xAC_function_0x10:_API_RECV, Receive TCP message
  • Interrupt_0xAC_function_0x11:_API_INETTOASCII, Convert IP address to IP string
  • Interrupt_0xAC_function_0x12:_API_RESETCONNECTION, Abort a connection on a socket
  • Interrupt_0xAC_function_0x13:_API_SETLINGER, Set linger time on close
  • Interrupt_0xAC_function_0x14:_API_SETREUSE, Set reuse option on a listening socket
  • Interrupt_0xAC_function_0x15:_API_SETIPTOS, Set IP Type-Of-Service
  • Interrupt_0xAC_function_0x16:_API_SETSOCKOPT, Set options on socket
  • Interrupt_0xAC_function_0x17:_API_GETSOCKOPT, Get options on socket
  • Interrupt_0xAC_function_0x18:_API_SETBLOCKINGMODE, Set socket mode
  • Interrupt_0xAC_function_0x19:_API_REGISTERCALLBACK, Register a user callback function
  • Interrupt_0xAC_function_0x20:_API_REGISTERCALLBACK_PASCAL, Pascal user callback
  • Interrupt_0xAC_function_0x21:_API_GET_SOCKET_ERROR, Get last socket error.
  • Interrupt_0xAC_function_0x22:_API_GET_TCP_STATE, Find TCP socket and return state.
  • Interrupt_0xAC_function_0x23:_API_FINDALL_SOCKETS, Get information about all open sockets.
  • Interrupt_0xAC_function_0x40:_PPPCLIENT_INSTALLED, Check if PPP client installed.
  • Interrupt_0xAC_function_0x41:_PPPCLIENT_OPEN, Open a PPP connection
  • Interrupt_0xAC_function_0x42:_PPPCLIENT_CLOSE, Close a PPP client connection
  • Interrupt_0xAC_function_0x43:_PPPCLIENT_GET_STATUS, Get PPP client status
  • Interrupt_0xAC_function_0x44:_PPPCLIENT_GET_DNSIP, Get DNS IP address
  • Interrupt_0xAC_function_0x45:_PPPCLIENT_SET_OPTIONS, Set options for the PPP client
  • Interrupt_0xAC_function_0x50:_PPPSERVER_INSTALLED, Check if PPP server installed
  • Interrupt_0xAC_function_0x51:_PPPSERVER_SUSPEND, Suspend PPP server task
  • Interrupt_0xAC_function_0x52:_PPPSERVER_ACTIVATE, Activate PPP server
  • Interrupt_0xAC_function_0x53:_PPPSERVER_GET_STATUS, Get server state
  • Interrupt_0xAC_function_0x54:_PPPSERVER_GET_CFG, Get PPP server configuration
  • Interrupt_0xAC_function_0x55:_PPPSERVER_SET_OPTIONS, Set options for PPP server
  • Interrupt_0xAC_function_0x60:_API_SNMP_GET, Get internal TCP/IP SNMP variables
  • Interrupt_0xAC_function_0x65:_API_FTP_GET_LOGIN, Get FTP server login counters
  • Interrupt_0xAC_function_0x66:_API_TELNET_GET_LOGIN, Get Telnet server login counters
  • Interrupt_0xAC_function_0x67:_API_GET_TELNET_STATE, Test Telnet session active
  • Interrupt_0xAC_function_0x70:_GET_INSTALLED_SERVERS and interfaces
  • Interrupt_0xAC_function_0x71:_RECONFIG_ETHERNET, Reconfigure Ethernet interface
  • Interrupt_0xAC_function_0x72:_DHCP_USE, Enable/Disable DHCP usage
  • Interrupt_0xAC_function_0x73:_DHCP_STAT, Get DHCP status of the Ethernet interface
  • Interrupt_0xAC_function_0x74:_TCPIP_STATISTICS, Access packet counters
  • Interrupt_0xAC_function_0x75:_PING_OPEN, Open and start ICMP echo requests
  • Interrupt_0xAC_function_0x76:_PING_CLOSE, Finish ICMP echo requests
  • Interrupt_0xAC_function_0x77:_PING_STATISTICS, Retrieve ping information
  • Interrupt_0xAC_function_0x78:_GETMEMORY_INFO, Report TCP/IP memory usage
  • Interrupt_0xAC_function_0x79:_SET_SERVER_IDLE_TIMEOUT, Control FTP/Telnet timeout
  • Interrupt_0xAC_function_0x7A:_IP_USER_CB, Install IP callback function
  • Interrupt_0xAC_function_0x7B:_ARP_USER_CB, Install ARP callback function
  • Interrupt_0xAC_function_0x80:_ADD_DEFAULT_GATEWAY, Add the default gateway
  • Interrupt_0xAC_function_0x81:_DEL_DEFAULT_GATEWAY, Delete the default gateway
  • Interrupt_0xAC_function_0x82:_GET_DEFAULT_GATEWAY, Get the current default gateway
  • Interrupt_0xAC_function_0x83:_ADD_STATIC_ROUTE, Add a route for an interface
  • Interrupt_0xAC_function_0x84:_DEL_STATIC_ROUTE, Delete a route for an interface
  • Interrupt_0xAC_function_0x88:_DEL_ARP_ENTRY_BY_PHYS, Delete by physical address
  • Interrupt_0xAC_function_0x89:_ADD_ARP_ENTRY, Add an entry to the ARP table
  • Interrupt_0xAC_function_0x8A:_GET_ARPROUTE_CACHE, Read ARP/Route cache table
  • Interrupt_0xAC_function_0x8D:_GET_IFACE_ENTRIES, Read table of TCP/IP device interfaces
  • Interrupt_0xAC_function_0x90:_ADD_IGMP_MEMBERSHIP, Install an IP multicast address entry
  • Interrupt_0xAC_function_0x91:_DROP_IGMP_MEMBERSHIP, Delete an IP multicast address entry
  • Interrupt_0xAC_function_0x92:_MCASTIP_TO_MACADDR, Map IP multicast address to Ethernet
  • Interrupt_0xAC_function_0xA0:_DEV_OPEN_IFACE, Install user device driver
  • Interrupt_0xAC_function_0xA1:_DEV_CLOSE_IFACE, Close TCP/IP device driver/interface
  • Interrupt_0xAC_function_0xA2:_DEV_RECV_IFACE, Move received data
  • Interrupt_0xAC_function_0xA3:_DEV_RECV_WAIT, Wait for received data
  • Interrupt_0xAC_function_0xA4:_DEV_NOTIFY_ISR, Signal from ISR
  • Interrupt_0xAC_function_0xA5:_DEV_GET_BUF, Get a buffer from TCP/IP stack
  • Interrupt_0xAC_function_0xA6:_DEV_SND_COMPLETE, Signal message send complete
  • Interrupt_0xAC_function_0xA7:_DEV_WAIT_DHCP_COMPLETE, Wait for DHCP

  • Interrupt 0xAC service 0x01: API_OPENSOCKET, open a socket

    Creates an end-point for communication and returns a socket descriptor (i.e. a handle).

    Parameters

    AH
    0x01 (= API_OPENSOCKET)

    AL
    type of socket :
    AL = 1 (= SOCK_STREAM) ==> TCP
    AL = 2 (= SOCK_DGRAM) ==> UDP

    Return Value

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

    Comments

    This function provides the BSD socket() functionality.

    Related Topics

    Close socket API_CLOSESOCKET

    Top of list
    Index page

    Interrupt 0xAC service 0x02: API_CLOSESOCKET, close a socket

    Closes the socket indicated by BX and releases all of its associated resources.

    Parameters

    AH
    0x02 (= API_CLOSESOCKET)

    BX
    Socket descriptor

    Return Value

    DX = 0 success AX: 0
    DX = -1 = API_ERROR     AX: contains error code

    Related Topics

    Open socket API_OPENSOCKET

    Top of list
    Index page

    Interrupt 0xAC service 0x03: API_BIND, bind TCP or UDP server socket

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

    Parameters

    AH
    0x03 (= API_BIND)

    BX
    Socket descriptor

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

    Return Value

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

    Comments

    The bind call sets a specific port number as an application's source port number.   Otherwise a random 16-bit source port number will be used when no bind call is made.

    The bind call is necessary for server applications in order that clients can connect to them at the agreed upon ("well known") port number.

    The older TCP and UDP echo client examples also used a bind call, but this was not necessary.   If you use the bind call in a client application, the client uses the given port number as its own source port number.

    Related Topics

    Get IP address of the Ethernet interface
    Convert ASCII IP address to binary
    For proper port number byte order: htons function

    Top of list
    Index page

    Interrupt 0xAC service 0x04: API_CONNECT, Connect to another socket

    For TCP only.   The connect call attempts to make a connection to another socket (either local or remote).   This call is used by a TCP client.

    Parameters

    AH
    0x04 (= API_CONNECT)

    BX
    Socket descriptor

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

    Return Value

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

    Comments

    The caller must fill in the first three elements of the sockaddr_in data structure at [DX:SI] prior to calling here.


    Top of list
    Index page

    Interrupt 0xAC service 0x05: API_RECVFROM, Receive UDP message

    For UDP only, receives message from another socket.

    Parameters

    AH
    0x05 (= API_RECVFROM)

    BX
    Socket descriptor

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

    Return Value

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

    Comments

    This function will output the received data to the buffer referenced by recv_params.bufferPtr pointer.   Up to recv_params.bufferLength bytes will be accepted.   The AX return value indicates the number of bytes put into the buffer.

    The sender can be identified by the IP address and port number reported in the sockaddr_in structure
    API_RECVFROM can only return complete UDP datagrams at the user provided buffer. If the next waiting datagram at the internal socket receive queue has a higher size than the specified recv_param.bufferlength, API_RECVFROM returns errorcode 240 (Message too long) without writing the datagram into the user buffer. You can use API_GETRCV_BYTES to detect the size of the next waiting datagram at the internal receive queue of this socket.

    Related Topics

    API_SENDTO - Send UDP datagram
    API_RECV - Receive TCP data
    API_GETRCV_BYTES - Get waiting bytes on a socket

    Top of list
    Index page

    Interrupt 0xAC service 0x06: API_SENDTO, Transmit a UDP datagram

    For UDP only, transmits message to another transport end-point.

    Parameters

    AH
    0x06 (= API_SENDTO)

    BX
    Socket descriptor

    DX:SI
    Pointer to a send_params structure which caller must fill in prior to call.

    Return Value

    DX = 0 success AX: number of bytes sent
    DX != 0 AX: contains error code

    Comments

    This function will output up to send_params.bufferLength bytes from the buffer at send_params.bufferPtr to the IP address specified by the sockaddr_in structure referenced by the send_params.toPtr pointer.   The return value indicates the actual number of bytes sent.

    Related Topics

    API_RECVFROM - Receive UDP datagram
    API_SEND - Send TCP data

    Top of list
    Index page

    Interrupt 0xAC service 0x07: API_HTONS, Convert byte order

    Converts a short (16 bit) value from host byte order to network byte order.

    Parameters

    AH
    0x07 (= API_HTONS)

    BX
    short value

    Return Value

    DX = 0, AX contains converted value

    Comments

    This is used to convert port numbers; e.g. htons(7).


    Top of list
    Index page

    Interrupt 0xAC service 0x08: API_INETADDR, Convert an IP-String to binary

    Converts a dotted decimal IP address string to an unsigned long in network byte order.

    Parameters

    AH
    0x08 (= API_INETADDR)

    BX:SI
    Pointer to the IP dotted decimal string set by caller.   This ASCII string must be zero terminated.

    ES:DI
    Pointer to a 32 bit unsigned long variable, where this function outputs the converted IP address value.

    Return Value

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

    Related Topics

    Get IP address of the Ethernet interface
    Convert binary IP address to ASCII dotted decimal

    Top of list
    Index page

    Interrupt 0xAC service 0x09: API_SLEEP, Sleep

    The application sleeps for a specified number of milliseconds.

    Parameters

    AH
    0x09 (= API_SLEEP)

    BX
    milliseconds

    Return Value

    DX = 0, AX = 0

    Comments

    This call has been superceded by the similar RTOS API call RTX_SLEEP_TIME.   This call here is maintained in the TCP/IP API for compatibility with earlier @CHIP-RTOS version.

    For new applications, the RTX function with more meaningful return values is recommended.


    Top of list
    Index page

    Interrupt 0xAC service 0x0A: API_MALLOC, Allocate memory

    This function allocates memory direct from the @CHIP-RTOS heap.

    Parameters

    AH
    0x0A (= API_MALLOC)

    BX
    size in bytes

    Return Value

    DX = 0   , AX = 0, ES:DI points to the allocated buffer
    DX != 0    allocation error, ES:DI is a NULL-Pointer

    Comments

    This function has been replaced by the DOS Int21h 0x48 API and is maintained here in the TCP/IP API only for compatibility with earlier @CHIP-RTOS versions (prior to version 1.00).

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


    Top of list
    Index page

    Interrupt 0xAC service 0x0B: API_FREE, Free an allocated buffer

    Releases a block of allocated memory.

    Parameters

    AH
    0x0B (= API_FREE)

    DX:SI
    Pointer to the buffer

    Return Value

    DX = 0   , AX = 0 success
    DX != 0   , AX = 0 free failed

    Comments

    This out dated function releases memory allocated with API_MALLOC.   It is maintained here only for compatibility with earlier @CHIP-RTOS versions (before version 1.00).

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


    Top of list
    Index page

    Interrupt 0xAC service 0x0C: API_GETRCV_BYTES, Get waiting bytes count

    Get the number of bytes on a socket, waiting for read.

    Parameters

    AH
    0x0C (= API_GETRCV_BYTES)

    BX
    socket descriptor

    Return Value

    DX = 0    success, AX contains the number of bytes ready
    DX != 0    failed, AX contains error code

    Comments

    If the specified socket is an UDP socket, API_GETRCV_BYTES will return the size (in bytes) of the next waiting datagram at the internal socket receive queue.

    Related Topics

    API_RECVFROM - UDP Receive
    API_RECV - TCP Receive

    Top of list
    Index page

    Interrupt 0xAC service 0x0D: API_ACCEPT, Accept the next incoming connection

    This API extracts the first connection on the queue of pending connections (from API_LISTEN) and creates a new socket for this connection.

    Parameters

    AH
    0x0D (= API_ACCEPT)

    BX
    Socket descriptor (must be switched into listen mode using API_LISTEN)

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

    Return Value

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

    Comments

    This call is used by a TCP server.

    On success, this function fills in the sockaddr_in structure at [DX:SI] with the IP address and port number of the accepted connection.

    The new socket will have the same socket options as the listening socket (BX).

    Related Topics

    API_SETSOCKOPT - Set socket options

    Top of list
    Index page

    Interrupt 0xAC service 0x0E: API_LISTEN, Listen for incoming connections

    Places the socket into passive mode and sets the number of incoming TCP connections that the system will queue.

    Parameters

    AH
    0x0E (= API_LISTEN)

    BX
    Socket descriptor

    CX
    The maximum number (limited to 5) of allowed outstanding connections

    Return Value

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

    Comments

    This call is used by a TCP server.

    Related Topics

    API_ACCEPT - Accept the next incoming connection

    Top of list
    Index page

    Interrupt 0xAC service 0x0F: API_SEND, Transmit TCP message

    For TCP only, this API transmits a message to another transport end-point.

    Parameters

    AH
    0x0F (= API_SEND)

    BX
    Socket descriptor

    DX:SI
    Pointer to a send_params structure which must be filled in by caller.

    Return Value

    DX = 0    success, AX: number of bytes sent
    DX != 0    failure, AX: contains error code

    Comments

    API_SEND may be used only if the socket is in a connected state.

    On success, the return value in AX contains the number of bytes which were successfully inserted into the socket's send queue.

    Related Topics

    API_RECV - Receive TCP data
    API_SENDTO - Send UDP datagram


    Developer Notes

    Since @CHIP-RTOS 1.00 the MSG_DONTWAIT option is available in the flag member of send_params structure for the API_SEND function (or recv_params structure for API_RECV function).   If flag is set to MSG_DONTWAIT the send call returns immediately.   As much data as fits into the internal TCP buffer is accepted for transmission and the transmit byte count is returned in AX.   If none of the data fits then -1 is returned in DX and error code 235 in AX.

    If flag is set to MSG_BLOCKING, the send call blocks until enough internal buffer space is available or a socket error occurs.   By default the blocking mode is set for all sockets at the open call.   If a socket has been set to non-blocking with the API_SETBLOCKINGMODE function, the MSG_BLOCKING flag is ignored and the call will be non-blocking.


    Top of list
    Index page


    Interrupt 0xAC service 0x10: API_RECV, Receive TCP message

    For TCP only, this API receives a message from another socket.

    Parameters

    AH
    0x10 (= API_RECV)

    BX
    Socket Descriptor

    DX:SI
    Pointer to recv_params structure which must be filled in by user.

    Return Value

    DX = 0    success, AX: number of received bytes; 0 bytes implies timeout
    DX != 0    failure, AX: contains error code

    Comments

    API_RECV may only be used when the socket is in a connected state.

    On success, the return value in AX contains the number of bytes which were successfully inserted into the caller's receive buffer at recv_params.bufferPtr.
    The length of the message returned could also be smaller than the parameter bufferlength of the recv_param structure. This is not an error.
    If flag member of recv_params structure is set to MSG_DONTWAIT, the API_RECV call returns immediately.   If no data is available -1 is returned in DX with error code 235 in AX.   If flag is set to MSG_BLOCKING, the API_RECV call waits for a message to arrive.

    By default the blocking mode is set for all sockets at the open call.   If a socket was set to non-blocking with the API_SETBLOCKINGMODE function, the MSG_BLOCKING flag is ignored and the call will be non-blocking.

    Related Topics

    API_SEND - Send TCP data
    API_RECVFROM - Receive UDP datagram

    Top of list
    Index page

    Interrupt 0xAC service 0x11: API_INETTOASCII, Convert IP address to IP string

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

    Parameters

    AH
    0x11 (= API_INETTOASCII)

    BX:SI
    Input Parameter:   Pointer to the 32 bit IP address in network byte order

    ES:DI
    Output Parameter:   Pointer to the string buffer, where this function outputs the converted dotted decimal IP string.   This buffer must have space for 17 Bytes!

    Return Value

    DX = 0, AX = 0, [ES:DI] buffer contains converted string value

    Comments

    The dotted decimal IP address ASCII string output to [ES:DI] buffer is zero terminated.

    Related Topics

    Convert ASCII dotted decimal IP address to binary

    Top of list
    Index page

    Interrupt 0xAC service 0x12: API_RESETCONNECTION, Abort a connection on a socket

    Applies only to TCP sockets.

    Parameters

    AH
    0x12 (= API_RESETCONNECTION)

    BX
    Socket descriptor

    Return Value

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

    Comments

    This API_RESETCONNECTION API does not close the socket, which must be done with API_CLOSESOCKET.

    The reset socket can not be used for a new connection.   You must close the socket and open a new one to get a new connection.

    Related Topics

    Close socket API_CLOSESOCKET

    Top of list
    Index page

    Interrupt 0xAC service 0x13: API_SETLINGER, Set linger time on close

    Applies only to TCP sockets.

    Parameters

    AH
    0x13 (= API_SETLINGER)

    BX
    Socket descriptor

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

    Return Value

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


    Top of list
    Index page

    Interrupt 0xAC service 0x14: API_SETREUSE, Set reuse option on a listening socket

    Sets SO_REUSEADDR socket option to '1'.

    Parameters

    AH
    0x14 (= API_SETREUSE)

    BX
    Socket descriptor

    Return Value

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

    Comments

    This API applies only to TCP sockets.   The reuse option is necessary if a listening socket is closed and then a new socket is opened and bound to the same port as the earlier socket.


    Developer Notes

    Since @CHIP-RTOS version 071, the API_OPENSOCKET call sets the SO_REUSEADDR option to '1' as default for all TCP sockets.   So calling this API is no longer necessary.


    Top of list
    Index page


    Interrupt 0xAC service 0x15: API_SETIPTOS, Set IP Type-Of-Service

    Sets socket's default Type-Of-Service placed in the IP datagram header's TOS field.

    Parameters

    AH
    0x15 (= API_SETIPTOS)

    AL
    Type-Of-Service for IP datagrams

    BX
    Socket descriptor

    Return Value

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

    Comments

    The 8 bits in the IP datagram Type-Of-Service field are defined as follows:

      Bits 0: unused bit (must be 0)
      Bits 1-4: Type of Service, see TCP/IP documentation e.g.
              Section 3.2 of "TCP/IP Illustrated, Volume 1 " by W. Richard Stevens.
              At most one of these four bits is set.
      Bits 5-7: "Precedence field" (unused today)

    Note:   Many routers ignore this IP datagram header field.


    Top of list
    Index page

    Interrupt 0xAC service 0x16: API_SETSOCKOPT, Set options on socket

    Controls option settings for specfied socket.

    Parameters

    AH
    0x16 (= API_SETSOCKOPT)

    BX
    Socket descriptor

    ES:DI
    Pointer to SetSocketOption type that specifies the socket options (see tcpipapi.h)

    Return Value

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

    Comments

    This API function makes it possible to manipulate options associated with a socket.   Prior to calling this function the caller must fill in a SetSocketOption type data structure.

    The socket options of an incoming connection (using accept) will be the same as the socket options from its listening socket.

    See SetSocketOption type definition for example usage of this API function.

    Related Topics

    GetSocketOption typedef with option names
    API_GETSOCKOPT - Get socket options

    Top of list
    Index page

    Interrupt 0xAC service 0x17: API_GETSOCKOPT, Get options on socket

    Reads out an option setting for a specified socket.

    Parameters

    AH
    0x17 (= API_GETSOCKOPT)

    BX
    Socket descriptor

    ES:DI
    Pointer to GetSocketOption structure

    Return Value

    DX = 0    success, Buffer pointed to by the optionValue member of the GetSocketOption
            structure at [ES:DI] contains the requested socket option value.
    DX != 0    failure, AX: contains error code

    Comments

    This API function makes it possible to read options associated with a socket.

    Prior to calling this function, the caller must fill in a GetSocketOption type data structure.
    The user must set the protocol_level and optionName members.   Also the pointer optionValue must point to a valid buffer in the user application's memory.

    The optionLength member is both an input and an output parameter.   The length of the buffer must be specified at the location referenced by optionLength and this length must be sufficient for the size of the requested option data.   On success, this API writes to the optionLength location the number of bytes output to the optionValue buffer.

    The socket options of an incoming connection (using accept) will be the same as the socket options from its listening socket.

    Related Topics

    GetSocketOption typedef with option names
    API_SETSOCKOPT - Set socket options

    Top of list
    Index page

    Interrupt 0xAC service 0x18: API_SETBLOCKINGMODE, Set socket mode

    Sets a socket in blocking or non-blocking mode

    Parameters

    AH
    0x18 (= API_SETBLOCKINGMODE)

    AL
    0: switch blocking off, 1: switch blocking on

    BX
    Socket descriptor

    Return Value

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

    Comments

    By default all sockets are in blocking mode.   If a socket is set to non-blocking mode, socket calls like CONNECT, ACCEPT, ... do not wait until full completion.   They will instead return immediately.

    Example usage of non-blocking mode:

      The connect call returns for a non-blocking socket with -1 in DX and error code 236 if the connection was not completed.   The user can call connect within a loop, periodically polling for connection completion condition while performing some other activity.


    Top of list
    Index page

    Interrupt 0xAC service 0x19: API_REGISTERCALLBACK, Register a user callback function

    Register a user callback function for events occurring on a TCP socket.

    Parameters

    AH
    0x19 (= API_REGISTERCALLBACK)

    BX
    Socket descriptor

    CX
    Event flag mask (see below)

    ES:DI
    Pointer to callback function (see below)

    Return Value

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

    Comments

    The TCP/IP stack of the IPC@CHIP is able to execute a registered user callback function, if one or more some specified events happens on a TCP socket connection.

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

    void huge socketCallBackFunc(int socketdescriptor,
                                 int eventFlags)


    Before closing a socket, you should remove the callback function.   This is done by calling this API function with a null pointer in ES:DI and value 0 in register CX.

    The input parameter eventFlags to the callback is a bit field indicating the event(s) that have occurred.

    The set of events for either the CX event mask argument to this API or the eventFlags callback parameter are defined in TCPIPAPI.H as follows:

                
    #define CB_CONNECT_COMPLT   0x0001   // Connection complete
    
    #define CB_ACCEPT           0x0002   // Remote client has established
    
                                         //  a connection to our listening server.
    
    #define CB_RECV             0x0004   // Incoming data arrived
    
    #define CB_SEND_COMPLT      0x0010   // Sending of data has been acked by the peer
    
    #define CB_REMOTE_CLOSE     0x0020   // Peer has shutdown the connection
    
    #define CB_SOCKET_ERROR     0x0040   // An error occurred on the connection
    
    #define CB_RESET            0x0080   // Peer has sent a rest on the connection
    
    #define CB_CLOSE_COMPLT     0x0100   // close has been completed

    Related Topics

    API_REGISTERCALLBACK_PASCAL For Pascal callback functions

    Top of list
    Index page

    Interrupt 0xAC service 0x20: API_REGISTERCALLBACK_PASCAL, Pascal user callback

    Registers a user callback function written in Pascal for events occurring on a TCP socket.

    Parameters

    AH
    0x20 (= API_REGISTERCALLBACK_PASCAL)

    BX
    Socket descriptor

    CX
    Event flag mask (see below)

    ES:DI
    Pointer to callback function (see below)

    Return Value

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

    Comments

    The number of Pascal TCP callback functions is limited to 10.

    The first action required in your callback function is to read the pointer to the PacCallBack record passed in registers ES:DI.   This can be accomplished by implementing the callback function as follows (Borland Pascal):

    procedure socketCallBackFunc; interrupt;
    var
        ESReg     : Integer;
        DIReg     : Integer;
        CBParamPtr    : CallBackParamPtr;
    begin
        (*********************************)
        (* Required to get the Parameter *)
        asm
            mov ax, es
            mov ESReg, ax
            mov ax, di
            mov DIReg, ax
        end;
        (*********************************)

        [... your code ...]

    end;

    Before closing a socket, you should remove the callback function.   This is done by calling this API function with a null pointer in ES:DI and value 0 in register CX.

    The event flags are defined as follows:
    const
        CB_CONNECT_COMPLT = $0001;
        CB_ACCEPT = $0002;
        CB_RECV = $0004;
        CB_SEND_COMPLT = $0010;
        CB_REMOTE_CLOSE = $0020;
        CB_SOCKET_ERROR = $0040;
        CB_RESET = $0080;
        CB_CLOSE_COMPLT = $0100;

    Related Topics

    API_REGISTERCALLBACK For C language callback functions

    Top of list
    Index page

    Interrupt 0xAC service 0x21: API_GET_SOCKET_ERROR, Get last socket error.

    Returns the last error which occurred on the specified socket.

    Parameters

    AH
    0x21 (= API_GET_SOCKET_ERROR)

    BX
    Socket descriptor

    Return Value

    DX =0: success AX: contains last socket error code


    Top of list
    Index page

    Interrupt 0xAC service 0x22: API_GET_TCP_STATE, Find TCP socket and return state.

    Search for a TCP socket at a given local port number, returning the socket state, IP address and port number of the remote peer (if any).

    Parameters

    AH
    0x22 (= API_GET_TCP_STATE)

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

    ES:DI
    Pointer to storage 32 Bit remote IP address

    Return Value

    AL: contains last TCP socket state (see below)
    If AL!=20 and AL bigger or equal 2 (a TCP connection is established), the storage at ES:DI holds the 32 bit IP address of the connected remote peer
    CX contains remote peer port number

    Comments

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

    Possible TCP socket states:

         0:   CLOSED
         1:   LISTEN
         2:   SYN_SENT
         3:   SYN_RECEIVED
         4:   ESTABLISHED
         5:   CLOSE_WAIT
         6:   FIN_WAIT_1
         7:   CLOSING
         8:   LAST_ACK
         9:   FIN_WAIT_2
        10:   TIME_WAIT
        20:   INVALID


    Top of list
    Index page


    Interrupt 0xAC service 0x23: API_FINDALL_SOCKETS, Get information about all open sockets.

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

    Parameters

    AH
    0x23 (= API_FINDALL_SOCKETS)

    ES:DI
    Output Parameter:   Pointer to an array of CX SocketInfo structures in the user's memory space into which this API will report the socket information.

    CX
    Size of the array (maximum number of table entries reported).

    Return Value

    AX holds the number of all open sockets.   The user provided array at [ES:DI] holds the socket information for up to CX sockets (the lesser of two register counts: AX, CX).

    Comments

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

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

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

                
    SocketInfo s[64];
    
    int avail, i;
    
    
    
    avail = FindAllOpenSockets(s, 64);
    
    if (avail > 64) avail = 64;
    
    
    
    for (i = 0; i < avail; i++)
    
    {
    
       printf("\r\nSocket index %d Protocol %d, LocalPort %d",
    
    	 s[i].socIndex, s[i].protocol, s[i].localport);
    
    }

    Related Topics

    SocketInfo data structure

    Top of list
    Index page

    Interrupt 0xAC service 0x40: PPPCLIENT_INSTALLED, Check if PPP client installed.

    Tests if PPP client services are available in this @CHIP-RTOS version and not disabled via CHIP.INI configuration.

    Parameters

    AH
    0x40 (= PPPCLIENT_INSTALLED)

    Return Value

    AX = 0: PPP client is not installed
    AX != 0: PPP client is installed

    Related Topics

    PPPCLIENT_GET_STATUS API - PPP client status

    Top of list
    Index page

    Interrupt 0xAC service 0x41: PPPCLIENT_OPEN, Open a PPP connection

    Opens a PPP client connection.

    Parameters

    AH
    0x41 (= PPPCLIENT_OPEN)

    ES:DI
    Pointer to a PPPClient_Init type data structure (declared at tcpipapi.h)

    Return Value

    DX: 0   AX: 0, success [ES:DI] contains the needed IP data for further TCP/IP socket communication
    DX: -1   AX: contains error code, open failed

    Comments

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

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

    Related Topics

    PPPCLIENT_CLOSE - Closes PPP client connection

    Top of list
    Index page

    Interrupt 0xAC service 0x42: PPPCLIENT_CLOSE, Close a PPP client connection

    Closes a PPP client connection.

    Parameters

    AH
    0x42 (= PPPCLIENT_CLOSE)

    Return Value

    DX: 0, AX =0: PPP client connection is closed
    DX: -1, AX contains error code, Connection close timed out

    Comments

    At the close call the PPP client also executes after closing the PPP session the modem hang-up commands specified in the PPPClient_Init structure referenced at the PPPCLIENT_OPEN call.
    Therefore we recommend waiting approximately 10 seconds before opening a subsequent PPP connection.


    Top of list
    Index page

    Interrupt 0xAC service 0x43: PPPCLIENT_GET_STATUS, Get PPP client status

    Gets PPP client's current status.

    Parameters

    AH
    0x43 (= PPPCLIENT_GET_STATUS)

    Return Value

    AX = -2 (=API_NOT_SUPPORTED), DX =- 2: PPP client task is not running
    AX = -1 (=API_ERROR), DX = PPP client status
    AX >= 0, then AX = PPP client status, DX unchanged

    Comments

    If the PPP client is not supported in this @CHIP-RTOS version, then the value returned in AX is zero and DX is set to -1 (=API_ERROR).   In this case an error message is issued to the console.

    Related Topics

    PPPCLIENT_INSTALLED API - @CHIP-RTOS feature check

    Top of list
    Index page

    Interrupt 0xAC service 0x44: PPPCLIENT_GET_DNSIP, Get DNS IP address

    Returns the Domain Name System (DNS) addresses as negotiated by the remote PPP server.

    Parameters

    AH
    0x44 (= PPPCLIENT_GET_DNSIP)

    BX
    1: Get primary DNS address, 2: Get secondary address

    ES:DI
    Output Parameter:   Pointer to an unsigned long variable where the requested DNS IP address will be stored by this API.

    Return Value

    AX = -2 (=API_NOT_SUPPORTED), DX = -2: PPP client is not installed.
    AX = -1 (=API_ERROR) DX contains error code.
    AX = 0, then unsigned long at [ES:DI] holds the DNS IP address.

    Comments

    The IP address output to [ES:DI] is in network byte order.


    Top of list
    Index page

    Interrupt 0xAC service 0x45: PPPCLIENT_SET_OPTIONS, Set options for the PPP client

    Sets the PPP options for the PPP client.

    Parameters

    AH
    0x45 (= PPPCLIENT_SET_OPTIONS)

    ES:DI
    Pointer to an array of PPP_Option data structures.   This array is terminated by first PPP_Option structure with a null optionValuePtr member (see example below).

    Return Value

    AX = -3 PPP Connection already established AX = -2 PPP client is not installed.
    AX = -1 Invalid Option(s) AX = 0 Success

    Comments

    If you want to use this function, you have to call it before opening a connection (see related links below).   Settings options during an established connection will not work!

    The settings are only valid for the next established connection.   The data structures referenced here with ES:DI must persist until after the subsequent PPP client open function completes.

    A C-Library function is available in the CLIB file TCPIP.C.   Here is an example which sets three PPP options using the C-Library wrapper functions:

                
    // Allow remote peer to set primary DNS IP.
    
    unsigned long DNS_Pri_IP  = 0L;
    
    // Allow remote peer to set secondary DNS IP.
    
    unsigned long DNS_Sec_IP  = 0L;
    
    // Allow remote peer to use VJ TCPIP header compression.
    
    unsigned int  ipcp_comp   = 1;
    
    
    
    PPP_Option My_Options[] = {
    
     { PPP_IPCP_PROTOCOL, PPP_OPTION_ALLOW, PPP_IPCP_COMP_PROTOCOL,
    
    	(const char *)&ipcp_comp, sizeof(ipcp_comp)},
    
     { PPP_IPCP_PROTOCOL, PPP_OPTION_WANT, PPP_IPCP_DNS_PRI,
    
    	(const char *)&DNS_Pri_IP, sizeof(DNS_Pri_IP)},
    
     { PPP_IPCP_PROTOCOL, PPP_OPTION_WANT, PPP_IPCP_DNS_SEC,
    
    	(const char *)&DNS_Sec_IP, sizeof(DNS_Sec_IP)},
    
       // This last PPP_Option is used to terminate array.
    
     { 0, 0, 0, NULL, 0}
    
    } ;
    
    
    
    //***** Call the C-Library functions as follows ****
    
    
    
    // Install options with CLIB function
    
    PPP_Client_SetOptions(&My_Options[0]);  // Point to first member of array
    
    
    
    PPP_Client_Open(&pppclient);            // Open the connection

    Related Topics

    PPPCLIENT_OPEN open a PPP connection
    PPPCLIENT_CLOSE close a PPP connection

    Top of list
    Index page

    Interrupt 0xAC service 0x50: PPPSERVER_INSTALLED, Check if PPP server installed

    Tests if PPP server is available in this @CHIP-RTOS version and not disabled via CHIP.INI configuration.

    Parameters

    AH
    0x50 (= PPPSERVER_INSTALLED)

    Return Value

    AX = 0: PPP server is not installed
    AX != 0: PPP server is installed


    Top of list
    Index page

    Interrupt 0xAC service 0x51: PPPSERVER_SUSPEND, Suspend PPP server task

    Suspends the PPP server task, "PPPS".

    Parameters

    AH
    0x51 (= PPPSERVER_SUSPEND)

    BX
    Timeout seconds

    Return Value

    AX = 0, DX= 0 PPP server is suspended
    AX != 0, DX != 0 Suspending PPP server failed, PPP server is not installed or timeout

    Comments

    Note that the timeout value in BX depends on your timeout entries for the modem commands specified in CHIP.INI.   If this call returns with -1 in AX and DX, the most likely reason for this is that the modem commands were not finished within the timeout period the timeout specified in BX.

    Related Topics

    PPPSERVER_ACTIVATE API - Reactivate PPP server
    PPPSERVER HANGUPTIMEOUTx - CHIP.INI timeout for wait on answer from modem

    Top of list
    Index page

    Interrupt 0xAC service 0x52: PPPSERVER_ACTIVATE, Activate PPP server

    Re-activate suspended PPP server.

    Parameters

    AH
    0x52 (= PPPSERVER_ACTIVATE)

    BX
    Timeout seconds

    Return Value

    AX = 0, DX = 0 PPP server is activated
    AX != 0, DX != 0 Activating PPP server failed, PPP server is not installed or timeout

    Comments

    This API will not activate the PPP server disabled from start up by the CHIP.INI configuration entry.

    On success, the PPP server is now able to serve a connection.

    Note that the timeout value in BX depends on your timeout entries for the modem commands specified in CHIP.INI.   If this call returns with -1 in AX and DX, the most likely reason for this is that the modem commands were not finished within the timeout period specified in BX.

    Related Topics

    PPPSERVER_SUSPEND API - Suspend PPP server
    PPPSERVER HANGUPTIMEOUTx - CHIP.INI timeout for wait on answer from modem

    Top of list
    Index page

    Interrupt 0xAC service 0x53: PPPSERVER_GET_STATUS, Get server state

    Gets the current state of the PPP server.

    Parameters

    AH
    0x53 (= PPPSERVER_GET_STATUS)

    Return Value

    DX != 0: PPP server is not installed
    DX = 0: AX contains the current PPP server state listed below

    Comments

    PPP server states:

    -1   Error state, should not happen
    1    Server disabled
    2    Server enabled, waiting for connection
    3    PPP connection is established
    4    Server tries to hang up modem
    5    Server tries to initialize modem


    Top of list
    Index page

    Interrupt 0xAC service 0x54: PPPSERVER_GET_CFG, Get PPP server configuration

    Gets the current main configuration data of the PPP server.

    Parameters

    AH
    0x54 (= PPPSERVER_GET_CFG)

    ES:DI
    Output Parameter:   Pointer to PPP_IPCfg_Data data structure where this function will report the configuration data.

    Return Value

    DX != 0 AX != 0: PPP server is not installed
    DX = 0 The user PPP_IPCfg_Data structure at [ES:DI] is filled with the PPP server configuration data

    Related Topics

    PPP_IPCfg_Data structure definition

    Top of list
    Index page

    Interrupt 0xAC service 0x55: PPPSERVER_SET_OPTIONS, Set options for PPP server

    Sets the PPP options for the PPP server.

    Parameters

    AH
    0x55 (= PPPSERVER_SET_OPTIONS)

    ES:DI
    Pointer to an array of PPP_Option data structures.   This array is terminated by first PPP_Option structure with a null optionValuePtr member. (see example below).

    Return Value

    AX = -3:   PPP Connection already established
    AX = -2:   PPP server is not installed
    AX = -1:   Invalid Option(s)
    AX =   0:   Success

    Comments

    It is only possible to set PPP options when the PPP server is suspended.   PPP server must be at status 1.   Setting options while the PPP server is active (state 2,3,4,5) has no effect.   The installed options will be applied as the PPP server is re-activated.  The data structures referenced by ES:DI must persists until that time.

    If you want to reset the options, call this function with a null pointer in ES:DI.

    A C-Library function for this API is available in the CLIB file TCPIP.C.   Here is an example which sets three PPP options using the C-Library wrapper functions:

                
    // Allow remote peer to set primary DNS IP.
    
    unsigned long DNS_Pri_IP  = 0L;
    
    // Allow remote peer to set secondary DNS IP.
    
    unsigned long DNS_Sec_IP  = 0L;
    
    // Allow remote peer to use VJ TCPIP header compression.
    
    unsigned int  ipcp_comp   = 1;
    
    
    
    PPP_Option My_Options[] = {
    
     { PPP_IPCP_PROTOCOL, PPP_OPTION_ALLOW, PPP_IPCP_COMP_PROTOCOL,
    
    	(const char *)&ipcp_comp, sizeof(ipcp_comp)},
    
     { PPP_IPCP_PROTOCOL, PPP_OPTION_WANT, PPP_IPCP_DNS_PRI,
    
    	(const char *)&DNS_Pri_IP, sizeof(DNS_Pri_IP)},
    
     { PPP_IPCP_PROTOCOL, PPP_OPTION_WANT, PPP_IPCP_DNS_SEC,
    
    	(const char *)&DNS_Sec_IP, sizeof(DNS_Sec_IP)},
    
       // This last PPP_Option is used to terminate array.
    
     { 0, 0, 0, NULL, 0}
    
    } ;
    
    
    
    //***** Call the C-Library functions as follows ****
    
    
    
    // Suspend the PPP server
    
    PPP_Server_Suspend(20, &error);
    
    // Install options with CLIB function
    
    PPP_Server_SetOptions(&My_Options[0]);  // Point to first member of array
    
     // Re-activate the server
    
    PPP_Server_Activate(20, &error);

    Related Topics

    PPPSERVER_SUSPEND suspend PPP server task
    PPPSERVER_ACTIVATE activate PPP server
    PPPSERVER_GET_STATUS Get status of the PPP server

    Top of list
    Index page

    Interrupt 0xAC service 0x60: API_SNMP_GET, Get internal TCP/IP SNMP variables

    Accesses Management Information Base (MIB) data structures residing inside the @CHIP-RTOS TCP/IP stack.

    Parameters

    AH
    0x60 (= API_SNMP_GET)

    AL
    1 Get pointer to IfMib data structure (only for the internal Ethernet device interface)
    2 Get pointer to IpMib data structure
    3 Get pointer to IcmpMib data structure
    4 Get pointer to TcpMib data structure
    5 Get pointer to UdpMib data structure
    6 Get pointer to AtEntry data structure (only of the internal Ethernet device interface)
    7 Get array of far pointers to IfMib entries of all current open TCP/IP device interfaces.
        (Local Loopback, Ethernet, PPP server, PPP client)
    8 Get far pointer to unsigned long sysuptime variable (10 Hz counter).

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

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

    Return Value

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

    DX = AX = 0 ES:DI contains a pointer to the structure unless input parameter AH was 7,
      in which case the user provided array (still addressed by DS:SI) contains the far pointers to the IfMib entries of the currently installed device interfaces.   CX is set to indicate the total number of currently installed devices.   If CX is less than it was on entry, then the reported list of pointers is not complete due to lack of user buffer space.

    Comments

    If this API call is used with AL==1-6, or 8, the pointers are granting direct access to the internal TCP/IP stack counters.   It's recommended to execute these calls only one time at the start of your application.

    For AL=7, the API call returns the pointers to the interface variables for the currently installed device interfaces.   To maintain an up to date array of pointers for all currently opened device interfaces, it is necessary to periodically request (e.g. every 10 seconds) the array of pointers.

    Note:   These structures are only available in @CHIP-RTOS versions which contain the SNMP option.   A SNMP agent is not part of the @CHIP-RTOS.   But if a user is able to implement an agent based on the TCP/IP API, they need access to the internal TCP/IP SNMP variables.   The SNMP MIB variables are not a part of our current official 6 @CHIP-RTOS versions.   It is necessary to order directly a @CHIP-RTOS version which includes this feature.


    Top of list
    Index page

    Interrupt 0xAC service 0x65: API_FTP_GET_LOGIN, Get FTP server login counters

    Accesses the FTP server login counters.

    Parameters

    AH
    0x65 (= API_FTP_GET_LOGIN)

    Return Value

    DX != 0 AX != 0 : @CHIP-RTOS doesn't support FTP server
    DX = AX = 0
    ES:DI contains the address of the 32 Bit (unsigned long) login counter
    DS:SI contains the address of the 32 Bit (unsigned long) login fail counter


    Top of list
    Index page

    Interrupt 0xAC service 0x66: API_TELNET_GET_LOGIN, Get Telnet server login counters

    Accesses the Telnet server login counters.

    Parameters

    AH
    0x66 (= API_TELNET_GET_LOGIN)

    Return Value

    DX != 0 AX != 0 : @CHIP-RTOS doesn't support Telnet server
    DX = AX = 0
    ES:DI contains the address of the 32 Bit (unsigned long) login counter
    DS:SI contains the address of the 32 Bit (unsigned long) login fail counter


    Top of list
    Index page

    Interrupt 0xAC service 0x67: API_GET_TELNET_STATE, Test Telnet session active

    Check if the Telnet server is currently handling an active Telnet session.

    Parameters

    AH
    0x67 (= API_GET_TELNET_STATE)

    Return Value

    DX = -1 AX = -1 :   @CHIP-RTOS doesn't support Telnet server
    DX = 0 AX = 1:   Telnet session is active
    DX = 0 AX = 0:   No Telnet session


    Top of list
    Index page

    Interrupt 0xAC service 0x70: GET_INSTALLED_SERVERS and interfaces

    Get information about running servers and interfaces of the IPC@CHIP TCP/IP Stack

    Parameters

    AH
    0x70 (= GET_INSTALLED_SERVERS)

    Return Value

    Bits of AX and DX contains the requested information

      Bit=0 service or device is not available.
      Bit=1 service or device is available.

    AX:
      Bit 0: Ethernet device
      Bit 1: PPP server
      Bit 2: PPP client
      Bit 3: Web server
      Bit 4: Telnet server
      Bit 5: FTP server
      Bit 6: TFTP server
      Bit 7: DHCP client

    DX:
      Bit 0: SNMP MIB variables support
      Bit 1: UDP Config server
      Bit 2: Ping client


    Top of list
    Index page

    Interrupt 0xAC service 0x71: RECONFIG_ETHERNET, Reconfigure Ethernet interface

    Reconfigures Ethernet interface, e.g. after changing the IP configuration

    Parameters

    AH
    0x71 (= RECONFIG_ETHERNET)

    Return Value

    AX:0 success
    else restart failed (should not happen).   Error code 237 indicates
    that an Ethernet interface configuration was already in progress.

    Comments

    A new IP configuration set with the prompt commands ip, netmask and gateway (or the corresponding @CHIP-RTOS API calls) becomes valid after a successful call to this function.

    If DHCP is changed from 1 to 0 then a new IP address, subnet mask and gateway should be set with the prompt commands ip, netmask and gateway or with the @CHIP-RTOS API interrupt 0xA0
    services 0x02, 0x04, 0x06 before using this function.


    Top of list
    Index page

    Interrupt 0xAC service 0x72: DHCP_USE, Enable/Disable DHCP usage

    Set/Reset DHCP usage by the Ethernet interface.

    Parameters

    AH
    0x72 (= DHCP_USE)

    AL
    0: DHCP not used, 1:DHCP_USE

    Return Value

    -- none --

    Comments

    This entry becomes valid only after rebooting the system or after calling function 0x71.

    If DHCP is changed from 1 to 0 then a new IP address, subnet mask and gateway should be set with the prompt commands ip, netmask and gateway or with the @CHIP-RTOS API interrupt 0xA0 services 0x02, 0x04, 0x06.


    Top of list
    Index page

    Interrupt 0xAC service 0x73: DHCP_STAT, Get DHCP status of the Ethernet interface

    Gets the DHCP status of the Ethernet interface.

    Parameters

    AH
    0x73 (= DHCP_STAT)

    Return Value

    AX: 1 System uses DHCP, AX:0 DHCP is not used
    DX: 0 System is not configured (is in progress)
    DX: 1 System is configured by a DHCP Server
    DX: 2 System configure retry failed (or no retry started before)

    If DX == 1 ES:DI points to a UserEthDhcp_Entry data structure which contains the received DHCP configuration data.

    Comments

    The returned DHCP configuration data must be treated by the user as read-only information.   Do not write to this data structure!


    Top of list
    Index page

    Interrupt 0xAC service 0x74: TCPIP_STATISTICS, Access packet counters

    This function returns the address of a structure which contains pointers to network packet counters.

    Parameters

    AH
    0x74 (= TCPIP_STATISTICS)

    Return Value

    AX: 0, DX:0
    ES:DI contains a pointer to the Packet_Count structure

    Comments

    The counters count_all_packets and count_all_sended packets count only Ethernet packets.   Other counters also count the packets from and to other devices, e.g. local loopback packets and PPP packets.

    The user is free to read and/or reset these counters.

    Related Topics

    Packet_Count structure type definition

    Top of list
    Index page

    Interrupt 0xAC service 0x75: PING_OPEN, Open and start ICMP echo requests

    This function opens and starts periodic Internet Control Message Protocol (ICMP) echo request (ping) to a specified remote host.

    Parameters

    AH
    0x75 (= PING_OPEN)

    ES:DI
    Pointer to user's Ping structure, four members of which must be set by caller prior to call.

    Return Value

    DX: -1, AX contains error code, Ping open failed
         else
    DX: socket descriptor, AX: 0

    Comments

    Important:
    If structure member count (set by user) is non-zero, the PING_STATISTICS call closes the ping socket automatically if structure member transmitted has reached the count value.   If structure member count is zero, ping process runs until PING_CLOSE is called.

    Related Topics

    PING_CLOSE API
    PING_STATISTICS API
    Console PING command

    Top of list
    Index page

    Interrupt 0xAC service 0x76: PING_CLOSE, Finish ICMP echo requests

    This function stops cyclic ICMP echo request (ping).

    Parameters

    AH
    0x76 (= PING_CLOSE)

    BX
    Socket descriptor from inside Ping structure from PING_OPEN call.

    Return Value

    DX: -1, AX -1, Ping close failed, should not happen, only if socket descriptor is invalid
        else
    DX: 0, AX: 0: success

    Comments

    The ping socket is closed here.

    Related Topics

    PING_OPEN API

    Top of list
    Index page

    Interrupt 0xAC service 0x77: PING_STATISTICS, Retrieve ping information

    The user can retrieve ping information by calling PING_STATISTICS.

    Parameters

    AH
    0x77 (= PING_STATISTICS)

    ES:DI
    Pointer to user's Ping structure from PING_OPEN call

    Return Value

    DX = 0, AX = 0: Success
    DX = -1, AX = -1: Failure

    Comments

    Structure at [ES:DI] is filled with the ping statistics on success.

    Important:
    If structure member count (set by user) is non-zero, the PING_STATISTICS call closes the ping socket automatically if structure member transmitted has reached the count value.   If structure member count is zero, ping process runs until PING_CLOSE is called.

    Related Topics

    PING_OPEN API
    PING_CLOSE API

    Top of list
    Index page

    Interrupt 0xAC service 0x78: GETMEMORY_INFO, Report TCP/IP memory usage

    This function reports the maximum available and the currently used memory of the TCP/IP stack.

    Parameters

    AH
    0x78 (= GETMEMORY_INFO)

    ES:DI
    Output Parameter:   Pointer to user's unsigned long where this API will report the maximum available TCP/IP memory byte count.

    DS:SI
    Output Parameter:   Pointer to user's unsigned long where this API will report the currently used TCP/IP memory byte count.

    Return Value

    DX: 0, AX 0 (The described memory sizes are stored at [ES:DI] and [DS:SI])

    Comments

    The maximum available memory for the TCP/IP stack can be configured in chip.ini (see TCPIPMEM).

    The amount of memory required by the TCP/IP stack depends on the number of open sockets and the size and number of transported data packets.   For memory blocks equal or smaller than 4096 bytes, the TCP/IP stack allocates memory from this pre-allocated block.   Once allocated, the TCP/IP stack does not release this memory back to the system.   It will be internally recycled for further usage.

    The default size of this memory block is 90 kBytes in the IPC@CHIP Large version and 98 kBytes in the @CHIP-RTOS version including PPP.

    Memory blocks larger than 4096 bytes are allocated directly from the @CHIP-RTOS memory.   The TCP/IP stack releases these blocks back to the IPC@CHIP memory management.   If your application requires a lot of memory you should avoid sending and receiving frames larger than 2048 bytes.   Larger packets should be split into some smaller ones prior to sending.

    With BIOS interrupt 0xA0 it is possible to install a user error handler function, which will be called if the memory limit is reached.

    Related Topics

    BIOSINT API Install a user fatal error handler
    IPC@CHIP TCP/IP memory chip.ini Configuration

    Top of list
    Index page

    Interrupt 0xAC service 0x79: SET_SERVER_IDLE_TIMEOUT, Control FTP/Telnet timeout

    Set/Get the Idle timeout for either the FTP or Telnet server.

    Parameters

    AH
    0x79 (= SET_SERVER_IDLE_TIMEOUT)

    AL
    0: Set Timeout,   Non-zero: Get Timeout

    BX
    0: FTP Server, 1: Telnet Server

    DX
    Timeout value in seconds (If AL = 0 for set)

    Return Value

    Set idle timeout -
      DX = AX = 0:   Success
      AX = DX = -1:   Server not provided

    Get idle timeout -
      AX = 0:   DX contains timeout value
      AX = DX = -1:   Server not provided

    Comments

    If input parameter AL is zero, this API inserts the new timeout value in DX into the CHIP.INI.   A reboot is not necessary for the new value to take affect.

    If AL is non-zero, this API returns the existing timeout for the specified server.

    Related Topics

    FTP Timeout in chip.ini Configuration
    Telnet Timeout in chip.ini Configuration

    Top of list
    Index page

    Interrupt 0xAC service 0x7A: IP_USER_CB, Install IP callback function

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

    Parameters

    AH
    0x7A (= IP_USER_CB)

    ES:DI
    Pointer to IP callback function (or set to null to remove a previously installed callback)

    Return Value

    DX: 0, AX 0 success

    Comments

    The application programmer can implement a function of the type (Borland C):

        typedef int (huge *MyIpCallbackFuncPtr)(
                     IpUserCallbackInfo_t far *ipInfo );


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

    If the callback function returns -1 the incoming packet will be ignored by the TCP/IP stack.

    To remove the callback function, this API call must be called with a null pointer in ES:DI.   Do not forget to uninstall the callback, if your application exits!


    Top of list
    Index page

    Interrupt 0xAC service 0x7B: ARP_USER_CB, Install ARP callback function

    This function allows the application programmer to install an ARP callback function.

    Parameters

    AH
    0x7B (= ARP_USER_CB)

    ES:DI
    Pointer to ARP callback function (or set to null to remove a previously installed callback)

    Return Value

    DX: 0, AX 0   Success

    Comments

    The application programmer can implement a function from the type described below:

        typedef int (huge *MyArpCallbackFuncPtr)(
                     ArpUserCallbackInfo_t far *arpInfo );


    If a function of this type is installed by the user, the TCP/IP stack will call this function for any incoming ARP packet.   The input parameter to the callback function allows access to the ARP packet.   Inside of this function the user is able to check the content of the incoming ARP packet and decide whether the TCP/IP stack should process this packet or ignore it.   If the callback function returns -1, the incoming packet will be ignored by the TCP/IP stack.

    For structure of an ARP packet see ArpHeader.

    To remove the callback function, this API call must be called with a null pointer in ES:DI.   Do not forget to uninstall the callback, if your application exits!


    Top of list
    Index page

    Interrupt 0xAC service 0x80: ADD_DEFAULT_GATEWAY, Add the default gateway

    This function is used to add the default gateway for all interfaces.

    Parameters

    AH
    0x80 (= ADD_DEFAULT_GATEWAY)

    BX
    Device entry of the gateway, 0: Ethernet, 1: PPP server, 2: PPP client, 3: User device driver

    ES:DI
    Pointer to an unsigned long containing the gateway IP in network byte order.

    DX:SI
    If BX == 3 DX:SI must contain User device handle pointer.

    Return Value

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

    Comments

    If this function is used, the gateway entry in the chip.ini becomes invalidated, but unchanged.

    If the PPP server or PPP client is specified in BX, the gateway is set to the remote peer IP address.

    Related Topics

    DEL_DEFAULT_GATEWAY API function
    DEV_OPEN_IFACE API function
    IP Gateway chip.ini Configuration
    PPP server Gateway chip.ini Configuration

    Top of list
    Index page

    Interrupt 0xAC service 0x81: DEL_DEFAULT_GATEWAY, Delete the default gateway

    This function is used to delete the default gateway.

    Parameters

    AH
    0x81 (= DEL_DEFAULT_GATEWAY)

    ES:DI
    Pointer to an unsigned long containing the gateway IP to be deleted in network byte order.

    Return Value

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

    Comments

    If this function is used, the gateway entry in the chip.ini becomes invalidated, but unchanged.

    Related Topics

    ADD_DEFAULT_GATEWAY API function
    IP Gateway chip.ini Configuration
    PPP server Gateway chip.ini Configuration

    Top of list
    Index page

    Interrupt 0xAC service 0x82: GET_DEFAULT_GATEWAY, Get the current default gateway

    This function is used to get the default gateway for all interfaces.

    Parameters

    AH
    0x82 (= GET_DEFAULT_GATEWAY)

    ES:DI
    Output Parameter:   Pointer to user's unsigned long variable where the gateway IP will be written.

    Return Value

    DX = 0, AX = 0:   Success.   Location at [ES:DI] contains the gateway IP in network byte order.
    DX = -1:   AX contains error code


    Top of list
    Index page

    Interrupt 0xAC service 0x83: ADD_STATIC_ROUTE, Add a route for an interface

    This function is used to add a route for an interface.   It allows packets for a different network to be routed by the interface.

    Parameters

    AH
    0x83 (= ADD_STATIC_ROUTE)

    BX
    Device entry of the gateway, 0: Ethernet, 1: PPP server, 2: PPP client, 3: User device driver

    DX:SI
    If BX = 3, DX:SI must contain User device handle pointer.

    ES:DI
    Pointer to user Route_Entry structure

    Return Value

    DX = 0, AX = 0:   Success
    DX = -1:   AX contains error code

    Comments

    The Route_Entry structure is defined in tcpipapi.h:

    Related Topics

    DEL_STATIC_ROUTE API function

    Top of list
    Index page

    Interrupt 0xAC service 0x84: DEL_STATIC_ROUTE, Delete a route for an interface

    This function is used to delete a route from an interface.

    Parameters

    AH
    0x84 (= DEL_STATIC_ROUTE)

    ES:DI
    Pointer to user Route_Entry structure

    Return Value

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

    Comments

    Only structure members destIPAddress and destNetmask must be valid at the function's call.

    Related Topics

    ADD_STATIC_ROUTE API function

    Top of list
    Index page

    Interrupt 0xAC service 0x88: DEL_ARP_ENTRY_BY_PHYS, Delete by physical address

    This function deletes the entry from the ARP table by the given physical address.

    Parameters

    AH
    0x88 (= DEL_ARP_ENTRY_BY_PHYS)

    ES:DI
    Pointer to physical address buffer (6 Byte)

    Return Value

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

    Related Topics

    ADD_ARP_ENTRY    Add ARP entry
    GET_ARPROUTE_CACHE    Get ARP cache

    Top of list
    Index page

    Interrupt 0xAC service 0x89: ADD_ARP_ENTRY, Add an entry to the ARP table

    This function adds an entry into the Address Resolution Protocol (ARP) table.

    Parameters

    AH
    0x89 (= ADD_ARP_ENTRY)

    BX:SI
    Pointer to IP address (unsigned long)

    ES:DI
    Pointer to physical address (6 Byte)

    Return Value

    DX = 0, AX = 0:   Success
    DX = -1: Failure, AX contains error code

    Related Topics

    DEL_ARP_ENTRY_BY_PHYS    Delete ARP entry by physical address
    GET_ARPROUTE_CACHE    Get ARP/ROUTE cache

    Top of list
    Index page

    Interrupt 0xAC service 0x8A: GET_ARPROUTE_CACHE, Read ARP/Route cache table

    This function returns all valid entries in the internal ARP/Route cache table.

    Parameters

    AH
    0x89 (= GET_ARPROUTE_CACHE)

    BX:SI
    Output Parameter:   Pointer to a user provided array of 64 of ArpRouteCacheEntry data structures for storing ARP/Route cache table.

    Return Value

    DX = 0, AX = 0, the user provided array at [BX:SI] contains the current ARP/Route cache table.
    CX holds the number of valid entries in table.

    Comments

    The array must provide 64 entries.   The API call returns only a copy of the current device interface variables.   In order to always have the current table status, it is necessary to cyclically (e.g. every 10 seconds) request the table with this API.

    Related Topics

    DEL_ARP_ENTRY_BY_PHYS    Delete ARP entry by physical address
    ADD_ARP_ENTRY    Add ARP entry

    Top of list
    Index page

    Interrupt 0xAC service 0x8D: GET_IFACE_ENTRIES, Read table of TCP/IP device interfaces

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

    Parameters

    AH
    0x8D (= GET_IFACE_ENTRIES)

    BX:SI
    Pointer to a user provided array of Iface_Entry data structures for storing the information.

    CX
    Number of data structures in array at [BX:SI].   Up to this number of device interfaces will be reported.

    Return Value

    DX = 0, the user provided array at [BX:SI] contains the current device interface information
    AX = Number of entries reported in array at [BX:SI].


    Top of list
    Index page

    Interrupt 0xAC service 0x90: ADD_IGMP_MEMBERSHIP, Install an IP multicast address entry

    Install an IP multicast address entry to become a member of an IP multicast group.

    Parameters

    AH
    0x90 (= ADD_IGMP_MEMBERSHIP)

    ES:DI
    Pointer to multicast IP address of type unsigned long

    DS:SI
    Pointer to a 6 byte array that contains the corresponded Ethernet address

    Return Value

    DX = 0, AX = 0:   Success
    DX = -1:   AX contains error code, invalid class D address, or no free entry in IGMP table available

    Comments

    IP Multicasting is the Internet abstraction of hardware multicasting.   It allows transmission of IP datagrams to a group of hosts that form a single multicast group.   Membership in a multicast group is dynamic.   Hosts may join or leave the group at any time.   Each multicast group has unique IP multicast address (Class D address).   The first four bits of an IP multicast address must match to binary 1110.   IP multicast addresses range from 224.0.0.0 through 239.255.255.255.

    For the usage of IP multicasting on an Ethernet interface, IP multicast addresses must be mapped to Ethernet hardware addresses.   The Ethernet device of the IPC@CHIP will be switched into the Ethernet multicast mode.   In this mode it receives any incoming IP packet with the mapped Ethernet multicast address and forwards it to the TCP/IP layer.   Each IP multicast packet will be sent with the mapped Ethernet multicast address.

    Because of the feature, that a multicast IP packet will be received by any member of a multicast group, sending and receiving of IP multicast packets is only usable with UDP sockets (datagram sockets).

    After installing a IP multicast address with this API, the application programmer is able use this address as a destination address when sending datagrams.   A UDP socket is able to receive datagrams at the specified multicast address.

    The maximum number of supported IP multicast addresses in the IPC@CHIP is limited to 15.   Before installing an IP multicast address, you can find out the corresponding Ethernet multicast address with Map IP multicast address to Ethernet address API.

    Using multicast addresses is only possible on the Ethernet interface.  

    Related Topics

    API function DROP_IGMP_MEMBERSHIP - Delete an IP multicast address entry
    API function MCASTIP_TO_MACADDR - Map IP multicast address to Ethernet address


    Developer Notes

    This implementation does not support multicast routing.   Sending and receiving multicast datagrams works only at local network.


    Top of list
    Index page


    Interrupt 0xAC service 0x91: DROP_IGMP_MEMBERSHIP, Delete an IP multicast address entry

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

    Parameters

    AH
    0x91 (= ADD_IGMP_MEMBERSHIP)

    ES:DI
    Pointer to multicast IP address of type unsigned long.

    Return Value

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

    Related Topics

    API function ADD_IGMP_MEMBERSHIP - Install an IP multicast address entry
    API function MCASTIP_TO_MACADDR - Map IP multicast address to Ethernet address

    Top of list
    Index page

    Interrupt 0xAC service 0x92: MCASTIP_TO_MACADDR, Map IP multicast address to Ethernet

    Maps an IP multicast address to the corresponding Ethernet address.

    Parameters

    AH
    0x92 (= MCASTIP_TO_MACADDR)

    ES:DI
    Pointer to multicast IP address of type unsigned long

    DS:SI
    Output Parameter:   Pointer to a 6 byte array where the generated Ethernet multicast address will be written.

    Return Value

    DX = 0, AX = 0:   Success, storage at DS:SI contains the generated Ethernet address
    DX = -1, AX = -1:   Invalid IP address

    Comments

    This API function computes the MAC address in the following manner:   To map an IP multicast address to a corresponding Ethernet multicast address place the low-order 23 bits of the IP multicast address into the low order 23 bits of the special Ethernet multicast address 01 00 5E 00 00 00
    e.g. IP multicast address 224.0.0.1 becomes Ethernet address 01 00 5E 00 00 01

    Related Topics

    API function ADD_IGMP_MEMBERSHIP - Install an IP multicast address entry
    API function DROP_IGMP_MEMBERSHIP - Delete an IP multicast address entry

    Top of list
    Index page

    Interrupt 0xAC service 0xA0: DEV_OPEN_IFACE, Install user device driver

    Open and install a user TCP device driver/interface at the internal TCP/IP stack of the @CHIP-RTOS.
    Add a new link layer for TCP/IP communication.

    Parameters

    AH
    0xA0 (=DEV_OPEN_IFACE)

    ES:DI
    Pointer to user filled DevUserDriver structure, which contains all needed information (device driver functions, etc.) for the user's driver implementation.

    Return Value

    DX = 0, AX = 0 (or =236):   Success

      The IfaceHandle member of DevUserDriver structure at [ES:DI] contains the valid Device Handle, which will be required as a parameter for most of the other device interface API for this device.

      If member variables iface_type and use_dhcp were set to 1, AX should contain code 236.   In this case, the user must make the additional call to DEV_WAIT_DHCP_COMPLETE API to wait for completion of the IP configuration by DHCP.

    DX = -1:   AX contains error code.   Installation failed

    Comments

    This is the first function to use when adding your own interface to the TCP/IP stack of the @CHIP-RTOS.

    The TCP/IP API calls 0xA0 - 0xA7 allow the application developer to implement an additional TCP/IP driver interface for a connected hardware device (e.g. connected UART or an Ethernet controller).   This new interface has its own IP configuration and is used by the TCP/IP stack for IP communication in the same way as the pre-installed internal devices of the IPC@CHIP (e.g. Internal Ethernet, PPP server or PPPclient).

    For more detailed description and a generic example see How to add an TCP/IP device driver/link layer interface.

    On the first DEV_OPEN_IFACE call for installing a TCP/IP device driver, the IfaceHandle member of the DevUserDriver structure at [ES:DI] must be NULL.   If an interface is closed with DEV_CLOSE_IFACE and the user wants to reopen that device interface (e.g. for changing IP configuration) , the IfaceHandle value set by the system in the first DEV_OPEN_IFACE call must be preserved.

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

    Clib TCPIP.C implementation of this function:

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


    Please note:   The API calls 0xA0 through 0xA7 for implementing your own TCP/IP device drivers are not part of our six official @CHIP-RTOS versions.   For ordering special version including this feature, please contact support@beck-ipc.com.

    Related Topics

    DEV_CLOSE_IFACE - Close device driver interface
    DEV_WAIT_DHCP_COMPLETE - Wait for DHCP IP configuration
    Example - Installing device driver

    Top of list
    Index page

    Interrupt 0xAC service 0xA1: DEV_CLOSE_IFACE, Close TCP/IP device driver/interface

    Close a TCP device driver/interface, remove an added link layer from the internal TCP/IP stack.

    Parameters

    AH
    0xA1 (=DEV_CLOSE_IFACE)

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

    Return Value

    DX = 0, AX = 0:   Success.
    DX = -1:   AX contains error code
        222: Invalid parameter
        236: Closing already in progress
        237: Device already closed

    Comments

    This function closes the device driver/interface.   It calls the driver close function and deactivates the layer from the internal TCP/IP stack of the @CHIP-RTOS.

    For more detailed description see How to add a user device driver/link layer interface

    Clib TCPIP.C implementation of this function:

    int Dev_Close_Interface(DevUserIfaceHandle DevHandlePtr,
                            int * errorcode);

    Related Topics

    DEV_OPEN_IFACE - Open device driver interface

    Top of list
    Index page

    Interrupt 0xAC service 0xA2: DEV_RECV_IFACE, Move received data

    Receive and process incoming data at the TCP/IP stack.

    Parameters

    AH
    0xA2 (=DEV_RECV_IFACE)

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

    Return Value

    DX = 0, AX = 0:   Success.
    DX = -1:  Failure, AX contains error code
        255:   Insufficient memory to complete operation

    Comments

    This function must be called to process incoming data on the TCP/IP stack.   This function in turn calls the driver receive function (specified by the DevRecv member of the DevUserDriver structure at the DEV_OPEN_IFACE call) and inserts the received data into the receive queue of the matching socket (if there is one).   Any tasks waiting on the socket (sleeping at RECV or RECVFROM ) are then signaled that there is new data available.   Only IGMP and ARP requests are directly processed in the task which does this call.

    Do not call this API from inside of an ISR!
    This function should be used only in combination with the Wait for receive event API call in the user's receiver task for their device driver interface.

    For more detailed description see How to add an TCP/IP device driver/link layer interface

    Clib TCPIP.C implementation of this function:

    int Dev_Recv_Interface( DevUserIfaceHandle DevHandlePtr,
                            int * errorcode);

    Related Topics

    Example - Receiver Task which calls this API
    Example Receiver function which would be called by this API

    Top of list
    Index page

    Interrupt 0xAC service 0xA3: DEV_RECV_WAIT, Wait for received data

    Waits for data received signal from Interrupt Service Routine.

    Parameters

    AH
    0xA3 (=DEV_RECV_WAIT)

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

    Return Value

    DX = 0, AX = 0:   Success
    DX = -1:   Failure, AX contains error code
    255: Insufficient memory to complete operation

    Comments

    This function sleeps until a DEV_NOTIFY_ISR signal by the device's ISR indicates that received data is available.   This function should be used in combination with the DEV_RECV_IFACE API within the user implemented receiver task.

    For more detailed description see How to add a user device driver/link layer interface

    Clib TCPIP.C implementation of this function:

    int Dev_Recv_Wait(DevUserIfaceHandle DevHandlePtr,
                      int * errorcode);

    Related Topics

    Example - Receiver Task

    Top of list
    Index page

    Interrupt 0xAC service 0xA4: DEV_NOTIFY_ISR, Signal from ISR

    Notify the TCP/IP stack from inside of an Interrupt Service Routine that there is incoming data available and/or that the device has sent a frame successfully.

    Parameters

    AH
    0xA4 (=DEV_NOTIFY_ISR)

    BX
    Number of available received packets

    CX
    Number of sent packets completed (provisional)

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

    Return Value

    DX = 0, AX = 0

    Comments

    This function should only be called from the device driver specific ISR.   It can be used to signal a receiver task which is waiting at the DEV_RECV_WAIT call.   In this case the number of received packets should be set in BX register.

    The current implementation does not support a transmit task.   The sent packets count in CX is a provision for informing a transmit task about completion of packet transmission.

    For more detailed description see How to add a user device driver/link layer interface.

    CLIB TCPIP.C implementation of this function:

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

    Related Topics

    Example - User device ISR

    Top of list
    Index page

    Interrupt 0xAC service 0xA5: DEV_GET_BUF, Get a buffer from TCP/IP stack

    Get a buffer from TCP/IP stack's pre-allocated buffer for storing incoming data from this device

    Parameters

    AH
    0xA5 (=DEV_GET_BUF)

    CX
    Number of bytes buffer required

    ES:DI
    Output Parameter:   Pointer to a variable of type DevUserBufferHandle where the user buffer handle is stored.   (This value is for internal use.)

    Return Value

    DX:   0, AX 0:  Success.   Returns in DS:SI a pointer to the beginning of the allocated buffer
    DX: -1, AX-1, DS=SI=0 (null pointer)

    Comments

    This call should be only used inside the driver specific receive function (implemented by the user).   It allocates a buffer from the internal TCP/IP memory pool which can be used for storing the incoming data.

    The usage of this function is optional.   It is not required, but is recommended that a user work with these buffers from the TCP/IP memory pool.

    For more detailed description see How to add an TCP/IP device driver/link layer interface

    Clib TCPIP.C implementation of this function:

    int Dev_Get_Buffer( DevUserIfaceHandle DevHandlePtr,
                        unsigned char far * far * buf,
                        unsigned int len);

    Related Topics

    Example Receiver function
    DevUserBufferHandle type definition
    IPC@CHIP TCP/IP memory chip.ini Configuration

    Top of list
    Index page

    Interrupt 0xAC service 0xA6: DEV_SND_COMPLETE, Signal message send complete

    This API signals the TCP/IP stack that the final frame in a message has been sent.   (Note that a message can be fragmented into multiple link layer frames.)

    Parameters

    AH
    0xA6 (=DEV_SND_COMPLETE)

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

    Return Value

    DX = 0, AX = 0

    Comments

    This function must be called from the driver send function (implemented by the user) on completion of sending data.   After this call, the TCP/IP stack of the @CHIP-RTOS is able to reuse the transmission data buffer.

    For more detailed description see How to add an TCP/IP device driver/link layer interface

    Clib TCPIP.C implementation of this function:

    int Dev_Send_Complete(DevUserIfaceHandle DevHandlePtr);

    Related Topics

    Example - User's Device Send Function

    Top of list
    Index page

    Interrupt 0xAC service 0xA7: DEV_WAIT_DHCP_COMPLETE, Wait for DHCP

    Waits for completion of IP configuration process by DHCP ("Dynamic Host Configuration Protocol ").   This call must be used if DEV_OPEN_IFACE API was called with DHCP enabled (see use_dhcp ) in DevUserDriver structure.

    Parameters

    AH
    0xA7 (=DEV_WAIT_DHCP_COMPLETE)

    CX
    Timeout seconds.   This value will depend on the DHCP server used.   A minimum value of 15 seconds is recommended.

    ES:DI
    Pointer to same DevUserDriver structure used at the DEV_OPEN_IFACE call.

    Return Value

    DX = 0, AX = 0:  Success
      The variables IPAddr and Netmask in the DevUserDriver structure contain the valid IP configuration.   The Dhcp_Data structure member points to the full configuration data provided by the DHCP server.

    DX = -1: AX contains error code: 260 Timeout.

    Comments

    Before calling this function, the device receiver task must be running.

    For more detailed description see How to add an TCP/IP device driver/link layer interface
    You will find all needed types, constants and prototypes in the CLIB header files TCPIPAPI.H and TCPIP.H.

    Clib TCPIP.C implementation of this function:

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

    Related Topics

    Example - User's receiver task

    Top of list
    Index page


    End of document