GetAddressByName
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.
In Windows
Sockets 2, this functionality is realized with the functions detailed in Protocol-Independent
Name Resolution.
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 |
|
); |
|
Parameters
dwNameSpace
Specifies the
name space, or a set of default name spaces, that the operating system will
query for network address 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 may access a WINS server to
perform the resolution. |
|
NS_SAP |
The Netware
Service Advertising Protocol. This may 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.
lpServiceType
Points to a
globally unique identifier (GUID) that specifies the type of the network
service. The header file SVCGUID.H includes definitions of several GUID service
types, and macros for working with them.
lpServiceName
Points 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.
lpiProtocols
Points to a
zero-terminated array of protocol identifiers. The function restricts a name
resolution attempt to name space providers that offer these protocols. This
lets the caller limit the scope of the search.
If lpiProtocols
is NULL, the function obtains information on all available protocols.
dwResolution
A set of bit
flags that specify aspects of the service name resolution process. The
following bit flags are defined:
|
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. |
lplpServiceAsyncInfo
Reserved for
future use; must be set to NULL.
lpCsaddrBuffer
Points 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.
lpdwBufferLength
Points 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.
lpAliasBuffer
Points to a
buffer to receive alias information for the network service.
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.
lpdwAliasBufferLength
Points to a
variable that, upon input, specifies the size, in bytes, of the buffer pointed
to by lpAliasBuffer.
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.
Return Values
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 may
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. |
Remarks
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.
See Also