Important The GetAddressByName function is a Microsoft-specific extension to the Windows Sockets 1.1 specification. This function is obsolete. For the convenience of Windows Sockets 1.1 developers, the reference material is below.
The functions detailed in Protocol-Independent Name Resolution provide equivalent functionality in Windows Sockets 2.
The GetAddressByName function queries a name space, or a set of default name spaces, in order to obtain network address information for a specified network service. This process is known as service name resolution. A network service can also use the function to obtain local address information that it can use with the bind function.
INT GetAddressByName(
DWORD dwNameSpace, // name space to query for service address
// information
LPGUID lpServiceType, // the type of the service
LPTSTR lpServiceName, // the name of the service
LPINT lpiProtocols, // points to array of protocol identifiers
DWORD dwResolution, // set of bit flags that specify aspects of
// name resolution
LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
// reserved for future use, must be NULL
LPVOID lpCsaddrBuffer, // points to buffer to receive address
// information
LPDWORD lpdwBufferLength, // points to variable with address
// buffer size information
LPTSTR lpAliasBuffer, // points to buffer to receive alias
// information
LPDWORD lpdwAliasBufferLength
// points to variable with alias buffer
// size information
);
Use one of the following constants to specify a name space:
| Value | Name Space |
|---|---|
| NS_DEFAULT | A set of default name spaces. The function queries each name space within this set. The set of default name spaces typically includes all the name spaces installed on the system. System administrators, however, can exclude particular name spaces from the set. This is the value that most applications should use for dwNameSpace. |
| NS_DNS | The Domain Name System used in the Internet for host name resolution. |
| NS_NETBT | The NetBIOS over TCP/IP layer. All Windows NT systems register their computer names with NetBIOS. This name space is used to convert a computer name to an IP address that uses this registration. Note that NS_NETBT can access a WINS server to perform the resolution. |
| NS_SAP | The Netware Service Advertising Protocol. This can access the Netware bindery if appropriate. NS_SAP is a dynamic name space that allows registration of services. |
| NS_TCPIP_HOSTS | Lookup value in the <systemroot>\system32\drivers\etc\hosts file. |
| NS_TCPIP_LOCAL | Local TCP/IP name resolution mechanisms, including comparisons against the local host name and looks up host names and IP addresses in cache of host to IP address mappings. |
Most calls to GetAddressByName should use the special value NS_DEFAULT. This lets a client get by with no knowledge of which name spaces are available on an internetwork. The system administrator determines name space access. Name spaces can come and go without the client having to be aware of the changes.
Setting lpServiceName to NULL is the equivalent of setting dwResolution to RES_SERVICE. The function operates in its second mode, obtaining the local address to which a service of the specified type should bind. The function stores the local address within the LocalAddr member of the CSADDR_INFO structures stored into *lpCsaddrBuffer.
If dwResolution is set to RES_SERVICE, the function ignores the lpServiceName parameter.
If dwNameSpace is set to NS_DNS, *lpServiceName is the name of the host.
If lpiProtocols is NULL, the function obtains information on all available protocols.
| Value | Meaning |
|---|---|
| RES_SERVICE | If this flag is set, the function obtains the address to which a service of the specified type should bind. This is the equivalent of setting lpServiceName to NULL. If this flag is clear, normal name resolution occurs. |
| RES_FIND_MULTIPLE | If this flag is set, the operating system performs an extensive search of all name spaces for the service. It will ask every appropriate name space to resolve the service name. If this flag is clear, the operating system stops looking for service addresses as soon as one is found. |
| RES_SOFT_SEARCH | This flag is valid if the name space supports multiple levels of searching. If this flag is valid and set, the operating system performs a simple and quick search of the name space. This is useful if an application only needs to obtain easy-to-find addresses for the service. If this flag is valid and clear, the operating system performs a more extensive search of the name space. |
Upon output, this variable contains the total number of bytes required to store the array of CSADDR_INFO structures. If this value is less than or equal to the input value of *lpdwBufferLength, and the function is successful, this is the number of bytes actually stored in the buffer. If this value is greater than the input value of *lpdwBufferLength, the buffer was too small, and the output value of *lpdwBufferLength is the minimal required buffer size.
If a name space supports aliases, the function stores an array of zero-terminated name strings into the buffer pointed to by lpAliasBuffer. There is a double zero-terminator at the end of the list. The first name in the array is the service's primary name. Names that follow are aliases. An example of a name space that supports aliases is DNS.
If a name space does not support aliases, it stores a double zero-terminator into the buffer.
This parameter is optional, and can be set to NULL.
Upon output, this variable contains the total number of bytes required to store the array of name strings. If this value is less than or equal to the input value of *lpdwAliasBufferLength, and the function is successful, this is the number of bytes actually stored in the buffer. If this value is greater than the input value of *lpdwAliasBufferLength, the buffer was too small, and the output value of *lpdwAliasBufferLength is the minimal required buffer size.
If lpAliasBuffer is NULL, lpdwAliasBufferLength is meaningless and can also be NULL.
If the function succeeds, the return value is the number of CSADDR_INFO data structures written to the buffer pointed to by lpCsaddrBuffer.
If the function fails, the return value is SOCKET_ERROR( – 1). To get extended error information, call GetLastError. GetLastError can return the following extended error value:
| Value | Meaning |
|---|---|
| ERROR_INSUFFICIENT_BUFFER | The buffer pointed to by lpCsaddrBuffer was too small to receive all of the relevant CSADDR_INFO structures. Call the function with a buffer at least as large as the value returned in *lpdwBufferLength. |
This function is a more powerful version of the Windows Sockets function gethostbyname The GetAddressByName function works with multiple name services.
The GetAddressByName function lets a client obtain a Windows Sockets address for a network service. The client specifies the service of interest by its service type and service name.
Many name services support a default prefix or suffix that the name service provider considers when resolving service names. For example, in the DNS name space, if a domain is named "nt.microsoft.com", and "ftp millikan" is provided as input, the DNS software fails to resolve "millikan", but successfully resolves "millikan.nt.microsoft.com".
Note that the GetAddressByName function can search for a service address in two ways: within a particular name space, or within a set of default name spaces. Using a default name space, an administrator can specify that certain name spaces will be searched for service addresses only if specified by name. An administrator or name space setup program can also control the ordering of name space searches.
Windows NT: Yes
Windows CE: Unsupported.
Header: Declared in nspapi.h.
Import Library: Link with wsock32.lib.