GetService
Important The GetService
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 GetService
function obtains information about a network service in the context of a set of
default name spaces or a specified name space. The network service is specified
by its type and name. The information about the service is obtained as a set of
NS_SERVICE_INFO data structures.
INT GetService(
|
DWORD dwNameSpace, |
// specifies name
space or spaces to search |
|
PGUID lpGuid, |
// points to a GUID
service type |
|
LPTSTR lpServiceName, |
// points to a
service name |
|
DWORD dwProperties, |
// specifies
service information to be obtained |
|
LPVOID lpBuffer, |
// points to buffer
to receive service information |
|
LPDWORD lpdwBufferSize, |
// points to size
of buffer, size of service information |
|
LPSERVICE_ASYNC_INFO lpServiceAsyncInfo |
// reserved for
future use, must be NULL |
|
); |
|
Parameters
dwNameSpace
Specifies the
name space, or a set of default name spaces, that the operating system will
query for information about the specified network service.
Use one of
the following constants to specify a name space:
|
Value |
Name
Space |
|
NS_DEFAULT |
A set of
default name spaces. The operating system will query 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. NS_DEFAULT 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 resolve a computer name into an IP
address using 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 |
Looks up
host names and IP addresses 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
GetService 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.
lpGuid
Points to a
globally unique identifier (GUID) that specifies the type of the network
service. The header file SVCGUID.H includes GUID service types from many
well-known services within the DNS and SAP name spaces.
lpServiceName
Points to a
zero-terminated string that uniquely represents the service name. For example, MY SNA SERVER .
dwProperties
A set of bit
flags that specify the service information that the function obtains. Each of
these bit flag constants, other than PROP_ALL, corresponds to a particular
member of the SERVICE_INFO data structure. If the flag is set, the
function puts information into the corresponding member of the data structures
stored in *lpBuffer. The following bit flags are defined:
|
Value |
Name
Space |
|
PROP_COMMENT |
If this
flag is set, the function stores data in the lpComment member of the
data structures stored in *lpBuffer. |
|
PROP_LOCALE |
If this
flag is set, the function stores data in the lpLocale member of the
data structures stored in *lpBuffer. |
|
PROP_DISPLAY_HINT |
If this
flag is set, the function stores data in the dwDisplayHint member of
the data structures stored in *lpBuffer. |
|
PROP_VERSION |
If this
flag is set, the function stores data in the dwVersion member of the
data structures stored in *lpBuffer. |
|
PROP_START_TIME |
If this
flag is set, the function stores data in the dwTime member of the data
structures stored in *lpBuffer. |
|
PROP_MACHINE |
If this
flag is set, the function stores data in the lpMachineName member of
the data structures stored in *lpBuffer. |
|
PROP_ADDRESSES |
If this
flag is set, the function stores data in the lpServiceAddress member
of the data structures stored in *lpBuffer. |
|
PROP_SD |
If this
flag is set, the function stores data in the ServiceSpecificInfo
member of the data structures stored in *lpBuffer. |
|
PROP_ALL |
If this
flag is set, the function stores data in all of the members of the data
structures stored in *lpBuffer. |
lpBuffer
Points to a
buffer to receive an array of NS_SERVICE_INFO1M73W6 structures and associated service
information. Each NS_SERVICE_INFO structure contains service information
in the context of a particular name space. Note that if dwNameSpace is
NS_DEFAULT, the function stores more than one structure into the buffer;
otherwise, just one structure is stored.
Each NS_SERVICE_INFO
structure contains a SERVICE_INFO structure. The members of these SERVICE_INFO
structures will contain valid data based on the bit flags that are set in the dwProperties
parameter. If a member s corresponding bit flag is not set in dwProperties,
the member s value is undefined.
The function
stores the NS_SERVICE_INFO structures in a consecutive array, starting
at the beginning of the buffer. The pointers in the contained SERVICE_INFO structures
point to information that is stored in the buffer between the end of the NS_SERVICE_INFO
structures and the end of the buffer.
lpdwBufferSize
Points to a
variable that, on input, contains the size, in bytes, of the buffer pointed to
by lpBuffer. On output, this variable contains the number of bytes
required to store the requested information. If this output value is greater
than the input value, the function has failed due to insufficient buffer size.
lpServiceAsyncInfo
This
parameter is reserved for future use. It must be set to NULL.
Return Values
If the
function succeeds, the return value is the number of NS_SERVICE_INFO structures
stored in *lpBuffer. Zero indicates that no structures were stored.
If the
function fails, the return value is SOCKET_ERROR ( - 1). To get extended error information, call GetLastError. GetLastError may
return one of the following extended error values:
|
Value |
Meaning |
|
ERROR_INSUFFICIENT_BUFFER |
The buffer
pointed to by lpBuffer is too small to receive all of the requested
information. Call the function with a buffer at least as large as the value
returned in *lpdwBufferSize. |
|
ERROR_SERVICE_NOT_FOUND |
The
specified service was not found, or the specified name space is not in use. The
function return value is zero in this case. |
See Also