GetServiceA function (nspapi.h)
The GetService function retrieves information about a network service in the context of a set of default namespaces or a specified namespace. 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.
Syntax
INT GetServiceA(
[in] DWORD dwNameSpace,
[in] LPGUID lpGuid,
[in] LPSTR lpServiceName,
[in] DWORD dwProperties,
[out] LPVOID lpBuffer,
[in, out] LPDWORD lpdwBufferSize,
[in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo
);
Parameters
[in] dwNameSpace
The namespace, or a set of default namespaces, that the operating system should query for information about the specified network service.
Use one of the following constants to specify a namespace.
Most calls to GetService should use the special value NS_DEFAULT. This lets a client get by without knowing available namespaces on an internetwork. The system administrator determines namespace access. Namespaces can come and go without the client having to be aware of the changes.
[in] lpGuid
A pointer to a globally unique identifier (GUID) that specifies the type of the network service. The Svcguid.h header file includes GUID service types from many well-known services within the DNS and SAP namespaces.
The Svcguid.h header file is not automatically included by the Winsock2.h header file.
[in] lpServiceName
A pointer to a zero-terminated string that uniquely represents the service name. For example, "MY SNA SERVER."
[in] dwProperties
A set of bit flags that specify the service information that the function retrieves. 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.
[out] lpBuffer
A pointer to a buffer to receive an array of NS_SERVICE_INFO structures and associated service information. Each NS_SERVICE_INFO structure contains service information in the context of a particular namespace. 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.
[in, out] lpdwBufferSize
A pointer 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.
[in, optional] lpServiceAsyncInfo
Reserved for future use. Must be set to NULL.
Return value
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, which returns one of the following extended error values.
| Error code | Meaning |
|---|---|
|
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. |
|
The specified service was not found, or the specified namespace is not in use. The function return value is zero in this case. |
Remarks
Note
The nspapi.h header defines GetService as an alias that 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 is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | nspapi.h |
| Library | Mswsock.lib |
| DLL | Mswsock.dll |