TCP_SOCKET TCPOpen( DWORD dwRemoteHost, BYTE vRemoteHostType, WORD wPort, BYTE vSocketPurpose );
Provides a unified method for opening TCP sockets. This function can open both client and server sockets. For client sockets, it can accept a host name string to query in DNS, an IP address as a string, an IP address in binary form, or a previously resolved NODE_INFO structure containing the remote IP address and associated MAC address. When a host name or IP address only is provided, the TCP module will internally perform the necessary DNS and/or ARP resolution steps before reporting that the TCP socket is connected (via a call to TCPISConnected returning TRUE). Server sockets ignore this destination parameter and listen only on the indicated port.
The vSocketPurpose field allows sockets to be opened with varying buffer size parameters and memory storage mediums. This field corresponds to pre-defined sockets allocated in the TCPSocketInitializer[] array in TCPIPConfig.h. The TCPIPConfig.h file can be edited using the TCP/IP Configuration Wizard.
Sockets are statically allocated on boot, but can be claimed with this function and freed using TCPDisconnect or TCPClose (for client sockets). Server sockets can be freed using TCPClose only (calls to TCPDisconnect will return server sockets to the listening state, allowing reuse).
TCP is initialized.
|
Parameters |
Description |
|
dwRemoteHost |
For client sockets only. Provide a pointer to a null-terminated string of the remote host name (ex: "www.microchip.com" or "192.168.1.123"), a literal destination IP address (ex: 0x7B01A8C0 or an IP_ADDR data type), or a pointer to a NODE_INFO structure with the remote IP address and remote node or gateway MAC address specified. If a string is provided, note that it must be statically allocated in memory and cannot be modified or deallocated until TCPIsConnected returns TRUE. This parameter is ignored for server sockets. |
|
vRemoteHostType |
Any one of the following flags to identify the meaning of the dwRemoteHost parameter:
|
|
wPort | |
|
vSocketPurpose |
Any of the TCP_PURPOSE_* constants defined in TCPIPConfig.h or the TCPIPConfig utility (see TCPSocketInitializer[] array). |
|
Return Values |
Description |
|
No sockets of the specified type were available to be opened. | |
|
Otherwise |
A TCP_SOCKET handle. Save this handle and use it when calling all other TCP APIs. |
This function replaces the old TCPConnect and TCPListen functions.
If TCP_OPEN_RAM_HOST or TCP_OPEN_ROM_HOST are used for the destination type, the DNS client module must also be enabled (STACK_USE_DNS must be defined in TCPIPConfig.h).
// Open a server socket skt = TCPOpen(NULL, TCP_OPEN_SERVER, HTTP_PORT, TCP_PURPOSE_HTTP_SERVER); // Open a client socket to www.microchip.com // The double cast here prevents compiler warnings skt = TCPOpen((DWORD)(PTR_BASE)"www.microchip.com", TCP_OPEN_ROM_HOST, 80, TCP_PURPOSE_DEFAULT); // Reopen a client socket without repeating DNS or ARP SOCKET_INFO cache = TCPGetSocketInfo(skt); // Call with the old socket skt = TCPOpen((DWORD)(PTR_BASE)&cache.remote, TCP_OPEN_NODE_INFO, cache.remotePort.Val, TCP_PURPOSE_DEFAULT);