www.beck-ipc.com

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


    IPC@CHIP® Documentation Index

TCP/IP API

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

Service is selected by index in AH register.

Common TCP/IP Socket functions

  • 0x00:_Install dynamic link, then call function
  • 0x01:_API_OPENSOCKET, open a socket
  • 0x02:_API_CLOSESOCKET, close a socket
  • 0x03:_API_BIND, bind TCP or UDP server socket
  • 0x04:_API_CONNECT, Connect to another socket
  • 0x05:_API_RECVFROM, Receive UDP message
  • 0x06:_API_SENDTO, Transmit a UDP datagram
  • 0x07:_API_HTONS, Convert byte order
  • 0x08:_API_INETADDR, Convert an IP-String to binary
  • 0x0C:_API_GETRCV_BYTES, Get waiting bytes count
  • 0x0D:_API_ACCEPT, Accept the next incoming connection
  • 0x0E:_API_LISTEN, Listen for incoming connections
  • 0x0F:_API_SEND, Transmit TCP message
  • 0x10:_API_RECV, Receive TCP message
  • 0x11:_API_INETTOASCII, Convert IP address to IP string
  • 0x12:_API_RESETCONNECTION, Abort a connection on a socket
  • 0x13:_API_SETLINGER, Set linger time on close
  • 0x14:_API_SETREUSE, Set reuse option on a listening socket
  • 0x15:_API_SETIPTOS, Set IP Type-Of-Service
  • 0x16:_API_SETSOCKOPT, Set options on socket
  • 0x17:_API_GETSOCKOPT, Get options on socket
  • 0x18:_API_SETBLOCKINGMODE, Set socket mode
  • 0x19:_API_REGISTERCALLBACK, Register a user callback function
  • 0x1A:_API_SELECT, Wait on socket events
  • 0x20:_API_REGISTERCALLBACK_PASCAL, Pascal user callback
  • 0x21:_API_GET_SOCKET_ERROR, Get last socket error.
  • 0x22:_API_GET_TCP_STATE, Find TCP socket and return state.
  • 0x23:_API_FINDALL_SOCKETS, Get information about all open sockets.
  • 0x24:_API_GET_TCP_STATE_IP_ALL, Find TCP sockets and return state
  • 0x25:_API_FINDALL_SOCKETS_IP_ALL, Get information about all open sockets.
  • 0x26:_API_SHUTDOWN, Shutdown socket.
  • 0x27:_API_RECVFROM_TO, Receive UDP message
  • 0x28:_API_SENDTO_IFACE, Transmit a UDP datagram via specified interface
  • 0x29:_API_RECVFROMTO_IFACE, Receive a UDP datagram and get interface
  • 0x7A:_IP_USER_CB, Install IP callback function
  • 0x7B:_ARP_USER_CB, Install ARP callback function
  • 0x7C:_IP_USER_CB_SND, Install IP callback function on outgoing packets
  • 0x7D:_IPCONF_USER_CB, Install callback function on IP configuration changes
  • 0x7F:_SET_TRECK_OPTIONS, Set TCPIP options
  • 0xC1:_INET_PTON, Convert an IP address text to binary
  • 0xC2:_INET_NTOP, Convert an IP binary address to text
  • 0xC3:_API_OPENSOCKET_IPV6, open an IPv6 socket

  • DNS services

  • 0x30:_DNS_GET_HOST_BY_NAME, Get a host's address(es) by domain name (IPv4)
  • 0x31:_DNS_GET_HOST_BY_NAME2, Get a host's address(es) by domain name (IPv6)
  • 0x32:_DNS_GET_HOST_BY_ADDR, Get a host's domain name by address (IPv4)
  • 0x33:_DNS_GET_HOST_BY_ADDR2, Get a host's domain name by address (IPv6)
  • 0x34:_DNS_GET_MAIL_HOSTS, Get mail hosts
  • 0x35:_DNS_SET_NAME_SERVER, Add prioritised name server

  • PPP client functions

  • 0x40:_PPPCLIENT_INSTALLED, Check if PPP client installed.
  • 0x41:_PPPCLIENT_OPEN, Open a PPP connection
  • 0x46:_PPPCLIENT_OPEN_IPV6, Open a PPP connection
  • 0x42:_PPPCLIENT_CLOSE, Close a PPP client connection
  • 0x43:_PPPCLIENT_GET_STATUS, Get PPP client status
  • 0x44:_PPPCLIENT_GET_DNSIP, Get DNS IP address
  • 0x45:_PPPCLIENT_SET_OPTIONS, Set options for the PPP client
  • 0x47:_PPPCLIENT_PAUSE, Pause/Resume the PPP client task

  • PPP server functions

  • 0x50:_PPPSERVER_INSTALLED, Check if PPP server installed
  • 0x51:_PPPSERVER_SUSPEND, Suspend PPP server task
  • 0x52:_PPPSERVER_ACTIVATE, Activate PPP server
  • 0x53:_PPPSERVER_GET_STATUS, Get server state
  • 0x54:_PPPSERVER_GET_CFG, Get PPP server configuration
  • 0x55:_PPPSERVER_SET_OPTIONS, Set options for PPP server
  • 0x56:_PPPSERVER_GET_CFG_IPv6, Get PPP server IPv6 configuration
  • 0x57:_PPPSERVER_PAUSE, Pause/Resume the PPP server

  • DHCP

  • 0x72:_DHCP_USE, Enable/Disable DHCP usage
  • 0x73:_DHCP_STAT, Get DHCP status of the Ethernet interface

  • Ping services

  • 0x75:_PING_OPEN, Open and start ICMP echo requests
  • 0x76:_PING_CLOSE, Finish ICMP echo requests
  • 0x77:_PING_STATISTICS, Retrieve ping information

  • ARP/Routing

  • 0x80:_ADD_DEFAULT_GATEWAY, Add the default gateway
  • 0x81:_DEL_DEFAULT_GATEWAY, Delete the default gateway
  • 0x82:_GET_DEFAULT_GATEWAY, Get the current default gateway
  • 0x83:_ADD_STATIC_ROUTE, Add a route for an interface
  • 0x84:_DEL_STATIC_ROUTE, Delete a route for an interface
  • 0x88:_DEL_ARP_ENTRY_BY_PHYS, Delete by physical address
  • 0x89:_ADD_ARP_ENTRY, Add an entry to the ARP table
  • 0x8A:_GET_ARPROUTE_CACHE, Read ARP/Route cache table

  • IP Multicast

  • 0x90:_ADD_IGMP_MEMBERSHIP, Install an IP multicast address entry
  • 0x91:_DROP_IGMP_MEMBERSHIP, Delete an IP multicast address entry
  • 0x92:_MCASTIP_TO_MACADDR, Map IP multicast address to Ethernet

  • Device driver API

  • 0x9F:_DEV_GET_IP, Get IP address and net mask of user device
  • 0xA0:_DEV_OPEN_IFACE, Install user device driver
  • 0xA1:_DEV_CLOSE_IFACE, Close TCP/IP device driver/interface
  • 0xA2:_DEV_RECV_IFACE, Move received data
  • 0xA3:_DEV_RECV_WAIT, Wait for received data
  • 0xA4:_DEV_NOTIFY_ISR, Signal from ISR
  • 0xA5:_DEV_GET_BUF, Get a buffer from TCP/IP stack
  • 0xA6:_DEV_SND_COMPLETE, Signal message send complete
  • 0xA7:_DEV_WAIT_DHCP_COMPLETE, Wait for DHCP
  • 0xA8:_DEV_PPP_REGISTER_CHAP, Install a CHAP authentication callback function.
  • 0xA9:_DEV_PPP_REGISTER_PAP, Install a PAP authentication callback function
  • 0xAA:_DEV_PPP_SET_OPTION, Set PPP options
  • 0xAB:_DEV_PPP_GET_PEER_IP, Get PPP peer IPv4 address
  • 0xAC:_DEV_PPP_GET_PEER_DNS, Get PPP peer address
  • 0xAD:_DEV_GET_HANDLE_BYNAME, Get driver handle pointer
  • 0xAE:_DEV_CONFIG_IFACE, Configure an interface
  • 0xAF:_DEV_CONFIG_IFACE_IPV6, IPv6 configuration of an interface
  • 0xB0:_DEV_UNCONFIG_IFACE, Unconfigure an interface
  • 0xB1:_DEV_PPP_GET_PEER_IPV6, Get PPP peer IPv6 address
  • 0xB2:_DEV_GET_DHCP_DATA, Get DHCP boot data
  • 0xB3:_DEV_NOTIFY_IOCTL, Executing special driver functions
  • 0xB4:_DEV_SET_SPECFLAGS, Set/Erase specifice device driver flags

  • IPsec/PKI/SSL functions

  • 0xCF:_IPSEC_VECTORS, IP Security API
  • 0xD0:_PKI_CERT_ADD, Add a certificate
  • 0xD1:_PKI_CERT_DEL, Delete a certificate
  • 0xD2:_PKI_OWNKEYPAIR_ADD, Add a public/private key pair
  • 0xD4:_SSL_SRV_CREATE, Create SSL server state
  • 0xD5:_SSL_GET_CONNSTATE, Return internal SSL status information
  • 0xD6:_SSL_HANDSHAKE_COMPLETE, Test SSL handshake status
  • 0xD7:_SSL_SESSION_CLOSE, Close a SSL session
  • 0xD8:_SSL_SESSION_NEW, Open a new SSL session
  • 0xD9:_SSL_SESSION_PROP, Set proposals for a SSL session
  • 0xDA:_SSL_SESSION_OPT, Set options for a SSL session
  • 0xDB:_SSL_CLI_CA_ADD, Add a client CA certificate
  • 0xDC:_SSL_CLI_START, Start the SSL client
  • 0xDD:_SSL_SEND_FLUSH, Queued user data will be flushed
  • 0xDE:_SSL_CONN_CLOSE, Close a SSL connection

  • Crypto functions

  • 0xDF:_CRYPT_HASH, Build MD5/SHA1 checksum
  • 0xE0:_CRYPT_CIPHER, Use symmetric crypto functions

  • Others

  • 0x09:_API_SLEEP, Sleep
  • 0x0A:_API_MALLOC, Allocate memory
  • 0x0B:_API_FREE, Free an allocated buffer
  • 0x60:_API_SNMP_GET, Get internal TCP/IP SNMP variables
  • 0x65:_API_FTP_GET_LOGIN, Get FTP server login counters
  • 0x66:_API_TELNET_GET_LOGIN, Get Telnet server login counters
  • 0x67:_API_GET_TELNET_STATE, Test Telnet session active
  • 0x70:_GET_INSTALLED_SERVERS and interfaces
  • 0x71:_RECONFIG_ETHERNET, Reconfigure Ethernet interface
  • 0x74:_TCPIP_STATISTICS, Access packet counters
  • 0x78:_GETMEMORY_INFO, Report TCP/IP memory usage
  • 0x79:_SET_SERVER_IDLE_TIMEOUT, Control FTP/Telnet timeout
  • 0x8D:_GET_IFACE_ENTRIES, Read table of TCP/IP device interfaces
  • 0x8E:_SET_IFACE_MTU, Set MTU of a device interface
  • 0x8F:_GET_IFACE_ENTRIES_EXT, Read table of TCP/IP device interfaces
  • 0xC0:_GET_IPV6_IFACE_ENTRIES, Read IPv6 information for each interface



  • Interrupt 0xAC service 0x00:     Install dynamic link, then call function

    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

    This API service is intended to be used by the RTOS C-Library exclusively.
    It should not be used directly from within user applications.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.15V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x01:     API_OPENSOCKET, open a socket

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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
    Open IPv4 socket API_OPENSOCKET
    Open IPv6 socket API_OPENSOCKET_IPV6

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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.

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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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.

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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, GetWaitingBytes() will return the sum of bytes over all waiting datagrams at the internal socket receive queue.

    Related Topics

    API_RECVFROM - UDP Receive
    API_RECV - TCP Receive

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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)

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x11:     API_INETTOASCII, Convert IP address to IP string

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 SC12 @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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x1A:     API_SELECT, Wait on socket events

    Wait on specified events for a selected set of sockets.

    Parameters

    AH
    0x1A (= API_SELECT)

    AL
    Boolean, set to zero for select_ms() API where fifth parameter passed is the long timeout_ms value. Set to 1 for the select() API where the fifth parameter is a pointer to a timeval structure.

    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

      SC12SC13SC11SC1x3SC2x
      V1.22V1.22V1.22V1.11V1.00

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.02V1.00V1.00n/an/a

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.02V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.04V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x24:     API_GET_TCP_STATE_IP_ALL, Find TCP sockets 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
    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00


    Top of list
    Index page


    Interrupt 0xAC service 0x25:     API_FINDALL_SOCKETS_IP_ALL, Get information about all open sockets.

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x26:     API_SHUTDOWN, Shutdown socket.

    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

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x27:     API_RECVFROM_TO, Receive UDP message

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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x28:     API_SENDTO_IFACE, Transmit a UDP datagram via specified interface

    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

      SC12SC13SC11SC1x3SC2x
      V1.21V1.21V1.21V1.10V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x29:     API_RECVFROMTO_IFACE, Receive a UDP datagram and get interface

    For UDP only, receives message from another transport end-point and gets the interface over which the packet arrived.

    Parameters

    AH
    0x29 (= API_RECVFROMTO_IFACE)

    BX
    Socket descriptor

    DX:SI
    Pointer to a recv_params2 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
    Storage pointed by ES:DI contains the destination address.
    DX != 0:  Failure, AX contains error code

    Related Topics

    API_RECVFROM - Receive UDP datagram
    API_SENDTO_IFACE - Send UDP data
    DEV_GET_HANDLE_BYNAME - Get device handle pointer

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.50V1.50

    Top of list
    Index page
    Interrupt 0xAC service 0x30:     DNS_GET_HOST_BY_NAME, Get a host's address(es) by domain name (IPv4)

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.05V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x31:     DNS_GET_HOST_BY_NAME2, Get a host's address(es) by domain name (IPv6)

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.05V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x32:     DNS_GET_HOST_BY_ADDR, Get a host's domain name by address (IPv4)

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.05V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x33:     DNS_GET_HOST_BY_ADDR2, Get a host's domain name by address (IPv6)

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.05V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x34:     DNS_GET_MAIL_HOSTS, Get mail hosts

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.05V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x35:     DNS_SET_NAME_SERVER, Add prioritised name server

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.05V1.00

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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
    DX: -2   AX: -2: PPP client is disabled by CHIP.INI entry.

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x46:     PPPCLIENT_OPEN_IPV6, Open a PPP connection

    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.
    DX: -2   AX: -2: PPP client is disabled by CHIP.INI entry.

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    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.
    DX: -2   AX: -2: PPP client is disabled by CHIP.INI entry.

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 is disabled by CHIP.INI entry.
    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.04V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.02V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x47:     PPPCLIENT_PAUSE, Pause/Resume the PPP client task

    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: Success, PPP client task is halted.
    AX = -1, DX = -1: Action not allowed due to the current state of the PPP client.
    AX = -2, DX = -2: PPP client is disabled by CHIP.INI entry.
    AX = -3, 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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.30V1.30

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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:

    -2   Server task is disabled by CHIP.INI setting, activation required with PPPSERVER_ACTIVATE
    -1   Error state, should not happen
    1    Server suspended
    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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.

    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

      SC12SC13SC11SC1x3SC2x
      V1.03V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x56:     PPPSERVER_GET_CFG_IPv6, Get PPP server IPv6 configuration

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x57:     PPPSERVER_PAUSE, Pause/Resume the PPP server

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.30V1.30

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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.01V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.01V1.00V1.00V0.90V1.00

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.01V1.00V1.00V0.90V1.00

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.01V1.00V1.00V0.90V1.00

    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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!

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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.

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.02V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.22V1.22V1.22V1.11V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x7C:     IP_USER_CB_SND, Install IP callback function on outgoing packets

    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

      SC12SC13SC11SC1x3SC2x
      V1.11V1.01V1.01V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x7D:     IPCONF_USER_CB, Install callback function on IP configuration changes

    This function allows the application programmer to install an callback function that is called whenever the IP address configuration of the system changes.

    Parameters

    AH
    0x7D (= IPCONF_USER_CB)

    ES:DI
    Pointer to 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:

        typedef void (huge *MyIpConfCallbackFuncPtr)(DevUserIfaceHandle DevHandlePtr);

    If a function of this type is installed by the user, the TCP/IP stack will call this function for any IP configuration change.

    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

    IP_USER_CB Install IP callback function
    ARP_USER_CB Install ARP callback function

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.53V1.53

    Top of list
    Index page
    Interrupt 0xAC service 0x7F:     SET_TRECK_OPTIONS, Set TCPIP options

    Set various general TCPIP options .

    Parameters

    AH
    0x7F (= SET_TRECK_OPTIONS)

    BX
    Name of the option (see Clib documentation)

    ES:DI
    Pointer to unsigned long option value

    Return Value

    DX: 0, AX 0 success

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.10V1.16

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    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.

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

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

    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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x8E:     SET_IFACE_MTU, Set MTU of a device interface

    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

    Comments

    Changing the MTU can only be done, if the interface is closed.

    Related Topics

    DEV_OPEN_IFACE API function

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.11V1.01V1.01V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x8F:     GET_IFACE_ENTRIES_EXT, Read table of TCP/IP device interfaces

    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

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.02V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.02V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.02V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0x9F:     DEV_GET_IP, Get IP address and net mask of user device

    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

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    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

    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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    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

    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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    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

    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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    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

    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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xA8:     DEV_PPP_REGISTER_CHAP, Install a CHAP authentication callback function.

    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

      SC12SC13SC11SC1x3SC2x
      V1.11V1.01V1.01V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xA9:     DEV_PPP_REGISTER_PAP, Install a PAP authentication callback function

    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

      SC12SC13SC11SC1x3SC2x
      V1.11V1.01V1.01V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xAA:     DEV_PPP_SET_OPTION, Set PPP options

    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

      SC12SC13SC11SC1x3SC2x
      V1.11V1.01V1.01V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xAB:     DEV_PPP_GET_PEER_IP, Get PPP peer IPv4 address

    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

      SC12SC13SC11SC1x3SC2x
      V1.11V1.01V1.01V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xAC:     DEV_PPP_GET_PEER_DNS, Get PPP peer address

    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

      SC12SC13SC11SC1x3SC2x
      V1.11V1.01V1.01V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xAD:     DEV_GET_HANDLE_BYNAME, Get driver handle pointer

    This function returns the driver handle pointer by a given driver name

    Parameters

    AH
    0xAD (=DEV_GET_HANDLE_BYNAME)

    DS:SI
    Driver name

    ES:DI
    Output Parameter:   Driver handle pointer Device handle

    Return Value

    DX = 0, [ES:DI] is driver handle pointer
    DX = -1, Driver not found, es=di=0

    Comments

    This function delivers the required driver handle pointer, which is necessary for using DEV_CONFIG_IFACE.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xAE:     DEV_CONFIG_IFACE, Configure an interface

    The function provides the IPv4 configuration of an interface. This functions provides the possibility to configure a device interface (e.g. the standard internal ethernet interface) with multiple IP addresses by enter a particular multihome index number.

    Parameters

    AH
    0xAE (=DEV_CONFIG_IFACE)

    ES:DI
    Pointer to DevIpv4IfaceCfg with IP configuration parameters provided by the caller

    Return Value

    DX = 0, AX = 0
    DX = -1, failure AX contains errorcode, ES=DI=0

    Comments

    If an interface is already configured at the specified multihomeindex number, the user first has to unconfigure it with DEV_UNCONFIG_IFACE. DHCP configuration of a device is only possible at multihomeindex 0.
    It is recommended to use this function only for changing ip configuration of own device interfaces or for changing IP configuration of the internal ethernet interface for multihomeindex 1..3 (SC1x3/SC2x 1 ..4).
    Changing the IP configuration of the ethernet device at index 0 should be done by the commands IP and IPETH because of the automatic actualization of the settings at chip.ini entry ADDRESS.
    Clibrary-based example:

                
    DevUserIfaceHandle DevHandlePtr;
    DevIpv4IfaceCfg  devcfg;
    int error;
    //Get the driver handle by name
    if(-1==Dev_Get_Handle_By_Name("NE2000",&DevHandlePtr,&error))
    {
      printf("\r\nError: Cannot detect driver handle, code %d",error);
      return 0;
    }
    //Set ip configuration
    devcfg.IfaceHandle    = DevHandlePtr;
    devcfg.flags          = 0;
    devcfg.multiHomeIndex = 1;  //configure particular multihomeindex 1
    inet_addr("192.168.200.59",&devcfg.IpAddr);
    inet_addr("255.255.255.0"",&devcfg.Netmask)
    
    if(-1==Dev_Config_Iface(&devcfg,&error))
    {
         printf("Error %d\r\n",error);
    }

    Related Topics

    DEV_GET_HANDLE_BYNAME - Get driver handle by name
    DEV_UNCONFIG_IFACE - Unconfigure an interface

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xAF:     DEV_CONFIG_IFACE_IPV6, IPv6 configuration of an interface

    The function provides the IPv6 configuration of an interface. This functions provides the possibility to configure a device interface (e.g. the standard internal ethernet interface) with multiple IP addresses by enter a particular multihome index number.

    Parameters

    AH
    0xAF (=DEV_CONFIG_IFACE_IPV6)

    ES:DI
    Pointer to DevIpv6IfaceCfg with IPv6 configuration parameters provided by the caller

    Return Value

    DX = 0, AX = 0
    DX = -1, failure AX contains errorcode, ES=DI=0

    Related Topics

    DEV_CONFIG_IFACE - IPv4 Configuration of an interface
    DEV_UNCONFIG_IFACE - Unconfigure an interface

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.05V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xB0:     DEV_UNCONFIG_IFACE, Unconfigure an interface

    The function is used to remove an IPv4/v6 configuration from an interface for a particular multi home index

    Parameters

    AH
    0xB0 (=DEV_UNCONFIG_IFACE)

    AL
    Multihome index number

    BX
    Protocol family (AF_INET or AF_INET6)

    ES:DI
    Device handle

    Return Value

    DX = 0, AX = 0
    DX = -1, failure AX contains errorcode=0

    Comments

    It is recommended to use this function only to unconfigure own device interfaces or to unconfigure the IP address of the internal ethernet interface for multihomeindex 1-3 (SC1x3/SC2x 1-4).
    Changing the IP configuration of ethernet interface at index 0 should be done by the commands IP and IPETH.

    Related Topics

    DEV_CONFIG_IFACE - IPv4 Configuration of an interface
    DEV_CONFIG_IFACE_IPV6 - IPv6 Configuration of an interface

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xB1:     DEV_PPP_GET_PEER_IPV6, Get PPP peer IPv6 address

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

    Parameters

    AH
    0xB1 (=DEV_PPP_GET_PEER_IPV6)

    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 from type struct sockaddr_storage.

    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.

    SC1x Comments

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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.05V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xB2:     DEV_GET_DHCP_DATA, Get DHCP boot data

    This function is used to get the DHCP data of a specified tcpip device interface.

    Parameters

    AH
    0xB2 (=DEV_GET_DHCP_DATA)

    CX
    Must be zero

    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 a pointer that will be set by this API call, referencing a UserEthDhcp_Entry data structure within @CHIP-RTOS memory. If no data is available the pointer will be set to NULL

    Return Value

    AX = 0

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.80V1.80

    Top of list
    Index page
    Interrupt 0xAC service 0xB3:     DEV_NOTIFY_IOCTL, Executing special driver functions

    The function allows the user to call the driver icotl function for executing special driver functions. An example for a special function would be to request the current Phy tranceiver link status if the driver is a Ethernet device.

    Parameters

    AH
    0xB3 (=DEV_NOTIFY_IOCTL)

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

    CX
    The flag parameter specifies the requested functionality.
    It is formed by ORing one or more of the following:
    0x4 - 0x0100 Device specific flags, other bits are reserved by TCPIP.

    BX:SI
    Input/Output Parameter:   Pointer to specific parameters

    DX
    Length in bytes of specific parameters.

    Return Value

    DX = 0, AX = 0
    DX = -1, failure AX contains errorcode

    Comments

    IOCTL Flags already used:
    0x0001 : Called by TCPIP to inform about IPv4 configuration.
            optionPtr is a pointer to a structure of type @ref DevIpv4IfaceCfg
    0x0002 : Not implemented yet, reserved for IPv6 configuration notification.
    0x0200 : Reserved by TCPIP for future use.
    0x0400 : Reserved by TCPIP for future use.
    0x0800 : The driver should enable a multicast address.
            optionPtr points to a to array of multicast MAC addresses with optionLen addresses.
    0x1000 : The driver should enable all multicast entries.
    0x2000 : The driver should erase its internal multicast table.
    0x4000 : Reserved by TCPIP for future use.
    0x8000 : Reserved by Beck IPC for own device driver implementations.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.35V1.35

    Top of list
    Index page
    Interrupt 0xAC service 0xB4:     DEV_SET_SPECFLAGS, Set/Erase specifice device driver flags

    The function allows the user to modify specific device driver flags

    Parameters

    AH
    0xB4 (=DEV_SET_SPECFLAGS)

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

    BX
    Flag parameter (By default these features are enabled)
    Bit11 0: Disable forwarding of IP directed broadcasts to and from this device
    Bit10 0: Disable IP Forwarding
    Bit13 0: Disable forwarding of IP multicast messages
    All other bits must be set to zero.

    Return Value

    DX = 0, AX = 0
    DX = -1, AX =-1, device handle not found

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.40V1.40

    Top of list
    Index page
    Interrupt 0xAC service 0xC0:     GET_IPV6_IFACE_ENTRIES, Read IPv6 information for each interface

    This function return the IPv6 configuration for each device interface of the TCP/IP stack.

    Parameters

    AH
    0xC0 (=GET_IPV6_IFACE_ENTRIES)

    ES:DI
    Output Parameter:   Pointer to a user provided array of IfaceIPv6_Entry data structures where this API will store the information.

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

    Return Value

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

    Related Topics

    IPv4/v6 - Dual layer stack

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xC1:     INET_PTON, Convert an IP address text to binary

    Convert an ASCII IPv4 or IPv6 address string from standard text representation to binary.

    Parameters

    AH
    0xC1 (=INET_PTON)

    BX
    Address family, AF_INET (for IPv4) or AF_INET6 (for IPv6)

    ES:DI
    Input Parameter:   Pointer to the ASCII IP address text (null terminated) to be converted

    DS:SI
    Output Parameter:   Storage for the converted binary address, provided by the user.   Buffer must provide 4 bytes for AF_INET and 16 bytes for AF_INET6.

    Return Value

    DX = 1, AX=0:   Success, the user provided array at [DS:SI] contains the converted address.
    DX = 0:   Invalid input IPv4 or IPv6 address text at [ES:DI].
    DX = -1:   BX was set to an invalid address family.

    Comments

    The binary IP address is output in network byte order.

    Related Topics

    IPV6 - Socket interface
    Convert IPv4 address string to binary
    Convert binary IPv4 or IPv6 address to ASCII string

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xC2:     INET_NTOP, Convert an IP binary address to text

    Convert an IPv4 or IPv6 address from the binary format to standard text representation.

    Parameters

    AH
    0xC2 (=INET_NTOP)

    BX
    Address family, AF_INET (for IPv4) or AF_INET6( for IPv6)

    ES:DI
    Points to the IP address in binary format, in network byte order.

    DS:SI
    Storage for the converted address in text format, provided by the user.

    CX
    Size in bytes, of the provided buffer at [DS:SI].
    Buffer should provide 16 bytes for AF_INET and 46 Bytes for AF_INET6.

    Return Value

    DX = 0, AX=0:   Success, the user provided array at [DS:SI] contains the converted address.
    DX =-1 AX=-1:   Failure, Invalid address family value or inadequate buffer size specified.

    Related Topics

    IPV6 - Socket interface
    Convert binary IPv4 address to ASCII string
    Convert ASCII IPv4 or IPv6 address string to binary

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xC3:     API_OPENSOCKET_IPV6, open an IPv6 socket

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

    Parameters

    AH
    0xC3 (= API_OPENSOCKET_IPV6)

    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 IPv4 socket API_OPENSOCKET
    Close socket API_CLOSESOCKET
    IPV6 - Socket interface

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.90V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xCF:     IPSEC_VECTORS, IP Security API

    Accesses the set of API that apply to IP Security.

    Parameters

    AH
    0xCF (= IPSEC_VECTORS)

    AL
    Sub selector for one of the IP Security API services.

    Comments

    This AH vector leads to the family of IP Security API.  

    Related Topics

    IP Security API

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xD0:     PKI_CERT_ADD, Add a certificate

    Add a certificate to the public key infrastructure. The CA certificate must be added before the certificate is added. In addition, the private/public key pair for a local certificate must be added before adding the local certificate.

    Parameters

    AH
    0xD0 (= PKI_CERT_ADD)

    ES:DI
    pointer to PKI_CERT_ADD_Entry structure

    Return Value

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

    Related Topics

    Delete certificate PKI_CERT_DEL
    Add private/public key pair PKI_OWNKEYPAIR_ADD

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.91V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xD1:     PKI_CERT_DEL, Delete a certificate

    Delete a certificate from the public key infrastructure.

    Parameters

    AH
    0xD1 (= PKI_CERT_DEL)

    ES:DI
    pointer to certificate identification string

    BX
    certificate type
      Bit0 = 1: local certificate
      Bit1 = 1: non local certificate (CA or peer)

    Return Value

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

    Related Topics

    Add certificate PKI_CERT_ADD
    Add private/public key pair PKI_OWNKEYPAIR_ADD

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.91V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xD2:     PKI_OWNKEYPAIR_ADD, Add a public/private key pair

    Add a public/private key pair for a local certificate to the public key infrastructure.

    Parameters

    AH
    0xD2 (= PKI_OWNKEYPAIR_ADD)

    ES:DI
    pointer to PKI_OWNKEYPAIR_ADD_Entry structure

    Return Value

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

    Related Topics

    Add certificate PKI_CERT_ADD
    Delete certificate PKI_CERT_DEL

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.91V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xD4:     SSL_SRV_CREATE, Create SSL server state

    Used to create SSL server states. This function must be called if the user sets the socket option to use SSL server after the TCP connection has been established. If user sets the socket option (to enable SSL) before the TCP handshake begins, the user don’t need to make this call.

    Parameters

    AH
    0xD4 (= SSL_SRV_CREATE)

    BX
    SSL socket descriptor

    Return Value

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

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV2.05V2.05

    Top of list
    Index page
    Interrupt 0xAC service 0xD5:     SSL_GET_CONNSTATE, Return internal SSL status information

    Returns internal SSL status information, required by the WLAN WL01 driver for execution of EAP-TLS protocol.

    Parameters

    AH
    0xD5 (= SSL_GET_CONNSTATE)

    BX
    SSL socket descriptor

    Return Value

    DX = 0 success, CX:DI points to the required internal SSL status information
    DX != 0 AX: contains error code

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.17V1.17

    Top of list
    Index page
    Interrupt 0xAC service 0xD6:     SSL_HANDSHAKE_COMPLETE, Test SSL handshake status

    Determine if an SSL data socket is ready to send and receive data.

    Parameters

    AH
    0xD6 (= SSL_HANDSHAKE_COMPLETE)

    BX
    Socket descriptor

    CX
    Time out in milliseconds:
      Set to 0xFFFF (= -1) to block forever.
      Set to 0 for non-blocking call.
      Otherwise maximum number of milliseconds to wait, up to 65534 ms maximum.

    Return Value

    DX = 0
    AX = SSL handshake status:
      -3: Handshake failure
      -2: Invalid socket descriptor
      -1: Not a TCP type socket
      0: Either not an SSL type socket or handshake in progress
      1: SSL handshake completed

    Comments

    Use of this function is optional.   It allows the user to determine whether or not the SSL handshake process has completed and that the data socket is now ready for data transmission and reception.

    This API can be used in either polling mode (CX = 0) or blocking mode.   The timeout period is specified in CX.   Blocking mode will return as soon as the status indication returned in AX is non-zero, or the specified time-out period has elapsed.   The CX register may be set to 0xFFFF to block for an indefinite amount of time, in which case AX register is guaranteed to be non-zero on return.

    Alternatively, the user can simply make repeated calls to the send() and/or recv() functions until this handshake is completed.   The SSL handshake is performed in the user's thread, so one of these three functions must be called in order to complete the SSL connection.

    Beck C-Library Usage

    SSL_HandshakeComplete()

    Related Topics

    send() API_SEND
    recv() API_RECV
    New SSL session SSL_SESSION_NEW

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.10V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xD7:     SSL_SESSION_CLOSE, Close a SSL session

    Call this function to close a SSL session. All cached connection information in this session will be freed too. User should close the SSL connection or the socket, first.

    Parameters

    AH
    0xD7 (= SSL_SESSION_CLOSE)

    BX
    Session ID

    Return Value

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

    Comments

    Note that the peer may not accept any data after the SSL layer is closed.

    Related Topics

    Close socket API_CLOSESOCKET
    Close SSL connection SSL_CONN_CLOSE
    New SSL session SSL_SESSION_NEW

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.91V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xD8:     SSL_SESSION_NEW, Open a new SSL session

    Open a new SSL session. Could be used as either SSL server session or SSL client session. If it is used as a server session the field certIdentity should be non-null, otherwise the SSL server can't run on this session.

    Parameters

    AH
    0xD8 (= SSL_SESSION_NEW)

    ES:DI
    pointer to SSL_SESSION_NEW_Entry structure

    Return Value

    DX = 0 success AX: Session ID
    DX != 0 AX: contains negated error code

    Comments

    Each session maintains its own connect information for the convenience of resumption.   You can resume a previous connection only if the current connect attempt and the previous one are in the same SSL session, and your previous connection cache hasn't been overwritten yet.

    For SSL server, all connections spawned from a single listening socket belong to one session, you should assign the session ID to the listening socket. All accepted sockets will inherit that session ID.

    For SSL client, user determines which session one connection belongs to. For example, users may decide that any connection to the same SSL server uses a single session ID, so that when user is trying to connect to the same server again, he may resume the previous connection.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.91V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xD9:     SSL_SESSION_PROP, Set proposals for a SSL session

    Use this function to set proposals for a SSL session. For a client session, the proposals are used to construct the Client Hello message. For a server session, the proposals are used to match Client Hello message in order to determine the final cipher suite to use.

    Parameters

    AH
    0xD9 (= SSL_SESSION_PROP)

    BX
    Session ID

    ES:DI
    pointer to proposals array (array of int)

    CX
    number of entries in the proposal array

    Return Value

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

    Comments

    To use this function on a server session, a previous call to function SSL_SESSION_OPT is needed. If the user doesn't call this function to set any session proposals, the default value is going to be used.

    The set of SSL cipher suites supported can be found here.

    Related Topics

    Set SSL session options SSL_SESSION_OPT

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xDA:     SSL_SESSION_OPT, Set options for a SSL session

    Call this function to set SSL session options.

    Parameters

    AH
    0xDA (= SSL_SESSION_OPT)

    BX
    Session ID

    DX
    option
      1: Client Authentication
      2: Server Proposals
      3: Skip Certificate Validation

    CX
    option value
      0: disable option
      1: enable option

    Return Value

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

    Comments

    The client authentication option is used to enable client authentication on a SSL server session. It takes effect only if the session is bound to an SSL server socket, in which case, upon receiving the ClientHello message, the SSL server is going to send back a CertificateRequest message along with its own Certificate, ServerHello and ServerHelloDone messages.

    The server proposals option is used to allow the SSL server to have more control on which cipher suite to use. If this option is not used on an SSL server session, upon receiving a ClientHello message, the SSL server just chooses the first matched cipher suite from its own session proposal list, according to server's preference. If a cipher suite proposed by the client is not the SSL server session's proposal list, even if the SSL server supports that cipher suite, it won't be chosen. For example, if server proposals option is enabled and server prefers cipher suites 1,2,3,4 and in this order. However, client only offers 4,3,2 and in this order, then cipher suite 2 will be chosen.

    The "Skip Certificate Validation" option 3 may be used to avoid attempting to trace a received certificate back to its root. A received certificate will be accepted without this root verification when this session option has been selected.

    Related Topics

    Set SSL session proposals SSL_SESSION_PROP

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.91V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xDB:     SSL_CLI_CA_ADD, Add a client CA certificate

    Call this function to add client CAs to ServerHello message

    Parameters

    AH
    0xDB (= SSL_CLI_CA_ADD)

    BX
    Session ID

    ES:DI
    Pointer to client CA certificate identity name

    Return Value

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

    Comments

    If client authentication option is used to enable client authentication on a SSL server session, this call can be used to add CAs to the ServerHello message (called CertificateRequest).
    This function must be called against an SSL server session. The SSL server will list CA's Distinguished Name to the client in his ServerHello message . This function can be called multiple times to add multiple potential CAs for client certificates.
    Before you can use this call, the client CAs certificate must be added to the PKI.

    Related Topics

    Add certificate PKI_CERT_ADD
    Set SSL session options SSL_SESSION_OPT

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.91V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xDC:     SSL_CLI_START, Start the SSL client

    Call this function to start the SSL client and SSL handshaking. Before this call, the user should set proper socket options on socket descriptor.

    Parameters

    AH
    0xDC (= SSL_CLI_START)

    BX
    Socket descriptor

    ES:DI
    Pointer to server common name.
    The common name is used to verify the certificate of the peer. If user passes in a NULL string, the certificate identity is not checked. This means, any valid certificate, even if it belongs to a bad party, will be accepted.

    Return Value

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

    Comments

    The certificate identity (common name field) may contain the wildcard character which is considered to match any single domain name component or component fragment. E.g., "*.a.com" in certificate Common Name matches the server common name "foo.a.com" but not "bar.foo.a.com". And certificate common name "f*.com" matches server common name "foo.com" but not "bar.com".

    Related Topics

    Set socket options API_SETSOCKOPT

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.91V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xDD:     SSL_SEND_FLUSH, Queued user data will be flushed

    SSL will queue user data if the send path is not triggered up when socket option TCP_SSL_SEND_MIN_SIZE is greater than zero. All data will be sent out rigth away, if this function is called.

    Parameters

    AH
    0xDD (= SSL_SEND_FLUSH)

    BX
    Socket descriptor

    Return Value

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

    Related Topics

    Set socket options API_SETSOCKOPT

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.91V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xDE:     SSL_CONN_CLOSE, Close a SSL connection

    The user data will be flushed and a close notify message will be send to the SSL peer. User may also close the whole socket instead of only closing the SSL layer.

    Parameters

    AH
    0xDE (= SSL_CONN_CLOSE)

    BX
    Socket descriptor

    Return Value

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

    Comments

    Note that the peer may not accept any data after the SSL layer is closed.

    Related Topics

    Close socket API_CLOSESOCKET
    Close SSL session SSL_SESSION_CLOSE

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV0.91V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xDF:     CRYPT_HASH, Build MD5/SHA1 checksum

    The user can use this function to create MD5/SHA1 checksums

    Parameters

    AH
    0xDF (= CRYPT_HASH)

    AL
    Mode
      0x01: Init MD5 hash function
      0x02: Update the MD5 hash
      0x03: Finalize the MD5 hash

      SHA1 hash is only available on SC1x3/SC2x:
      0x04: Init SHA1 hash function
      0x05: Update the SHA1 hash
      0x06: Finalize the SHA1 hash

    ES:DI
    Pointer to MD5 context structure or SHA1 context structure

    DX:SI
    Pointer to input buffer (valid for mode="update" only)

    CX
    length of input buffer (valid for mode="update" only)

    Return Value

    DX = 0 success
    DX != 0 error

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.11V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xE0:     CRYPT_CIPHER, Use symmetric crypto functions

    The user can use this function to encrypt/decrypt messages

    Parameters

    AH
    0xE0 (= CRYPT_CIPHER)

    AL
    Mode
      0x01: Make AES encrypt key
      0x02: Make AES decrypt key
      0x03: Encrypt AES message
      0x04: Decrypt AES message

    ES:DI
    In mode 0x01 and 0x02: Pointer to GenericKey structure
    In mode 0x03 and 0x04: Pointer to input buffer

    DX:SI
    Pointer to AES context structure

    CX:BX
    In mode 0x03 and 0x04: Pointer to output buffer

    Return Value

    DX = 0 success
    DX != 0 error

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.11V1.00

    Top of list
    Index page


    End of document