GetAddressByNameA function (nspapi.h)
[GetAddressByName is no longer available for use as of Windows Sockets 2. Instead, use the functions detailed in Protocol-Independent Name Resolution.]
The GetAddressByName function queries a namespace, or a set of default namespaces, to retrieve 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 GetAddressByNameA( [in] DWORD dwNameSpace, [in] LPGUID lpServiceType, [in, optional] LPSTR lpServiceName, [in, optional] LPINT lpiProtocols, [in] DWORD dwResolution, [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo, [out] LPVOID lpCsaddrBuffer, [in, out] LPDWORD lpdwBufferLength, [in, out] LPSTR lpAliasBuffer, [in, out] LPDWORD lpdwAliasBufferLength );
The namespace, or set of default namespaces, that the operating system should query for network address information.
Use one of the following constants to specify a namespace.
Most calls to GetAddressByName should use the special value NS_DEFAULT. This lets a client get by with no knowledge of which namespaces are available on an internetwork. The system administrator determines namespace access. Namespaces can come and go without the client having to be aware of the changes.
A pointer to a globally unique identifier (GUID) that specifies the type of the network service. The Svcguid.h header file includes definitions of several GUID service types, and macros for working with them.
The Svcguid.h header file is not automatically included by the Winsock2.h header file.
[in, optional] lpServiceName
A pointer to a zero-terminated string that uniquely represents the service name. For example, "MY SNA SERVER".
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.
[in, optional] lpiProtocols
A pointer to a zero-terminated array of protocol identifiers. The function restricts a name resolution attempt to namespace providers that offer these protocols. This lets the caller limit the scope of the search.
If lpiProtocols is set to NULL, the function retrieves information on all available protocols.
A set of bit flags that specify aspects of the service name resolution process. The following bit flags are defined.
[in, optional] lpServiceAsyncInfo
Reserved for future use; must be set to NULL.
A pointer to a buffer to receive one or more CSADDR_INFO data structures. The number of structures written to the buffer depends on the amount of information found in the resolution attempt. You should assume that multiple structures will be written, although in many cases there will only be one.
[in, out] lpdwBufferLength
A pointer to a variable that, upon input, specifies the size, in bytes, of the buffer pointed to by lpCsaddrBuffer.
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.
[in, out] lpAliasBuffer
A pointer to a buffer to receive alias information for the network service.
If a namespace 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 namespace that supports aliases is DNS.
If a namespace does not support aliases, it stores a double zero-terminator into the buffer.
This parameter is optional, and can be set to NULL.
[in, out] lpdwAliasBufferLength
A pointer to a variable that, upon input, specifies the size, in elements (characters), of the buffer pointed to by lpAliasBuffer.
Upon output, this variable contains the total number of elements (characters) 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 elements 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, which returns the following extended error value.
||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 gethostbyname function. 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 namespace, 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 namespace, or within a set of default namespaces. Using a default namespace, an administrator can specify that certain namespaces will be searched for service addresses only if specified by name. An administrator or namespace—setup program can also control the ordering of namespace searches.
The nspapi.h header defines GetAddressByName as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
|Minimum supported client||Windows 2000 Professional [desktop apps only]|
|Minimum supported server||Windows 2000 Server [desktop apps only]|