Функция GetServiceA (nspapi.h)
Функция GetService getService извлекает сведения о сетевой службе в контексте набора пространств имен по умолчанию или указанного пространства имен. Сетевая служба указывается по типу и имени. Сведения о службе получаются в виде набора структур данных NS_SERVICE_INFO.
Синтаксис
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
);
Параметры
[in] dwNameSpace
Пространство имен или набор пространств имен по умолчанию, которые операционная система должна запрашивать сведения об указанной сетевой службе.
Используйте одну из следующих констант, чтобы указать пространство имен.
Большинство вызовов GetService должны использовать специальное значение NS_DEFAULT. Это позволяет клиенту получить доступ, не зная доступных пространств имен в Интернете. Системный администратор определяет доступ к пространству имен. Пространства имен могут поступать и идти без необходимости знать об изменениях.
[in] lpGuid
Указатель на глобальный уникальный идентификатор (GUID), указывающий тип сетевой службы. Файл заголовка Svcguid.h включает типы служб GUID из многих известных служб в пространствах имен DNS и SAP.
Файл заголовка Svcguid.h не включается в файл заголовка Winsock2.h.
[in] lpServiceName
Указатель на строку, которая однозначно представляет имя службы. Например, "MY SNA SERVER".
[in] dwProperties
Набор битовых флагов, указывающих сведения о службе, извлекаемые функцией. Каждая из этих констант флагов, отличных от PROP_ALL, соответствует конкретному элементу структуры данных SERVICE_INFO. Если флаг задан, функция помещает сведения в соответствующий элемент структур данных, хранящихся в *lpBuffer. Определены следующие битовые флаги.
[out] lpBuffer
Указатель на буфер для получения массива структур NS_SERVICE_INFO и связанных сведений о службе. Каждая NS_SERVICE_INFO структура содержит сведения о службе в контексте определенного пространства имен. Обратите внимание, что если dwNameSpace NS_DEFAULT, функция сохраняет несколько структур в буфере; в противном случае сохраняется только одна структура.
Каждая NS_SERVICE_INFO структура содержит SERVICE_INFO структуру. Члены этих SERVICE_INFO структур будут содержать допустимые данные на основе битовых флагов, заданных в параметре dwProperties. Если соответствующий битовый флаг члена не задан в dwProperties, значение члена не определено.
Функция сохраняет структуры NS_SERVICE_INFO в последовательном массиве, начиная с начала буфера. Указатели в содержащихся SERVICE_INFO структурах указывают на сведения, хранящиеся в буфере между концами NS_SERVICE_INFO структур и концом буфера.
[in, out] lpdwBufferSize
Указатель на переменную, содержащую размер буфера в байтах, на который указывает lpBuffer. В выходных данных эта переменная содержит количество байтов, необходимых для хранения запрошенных сведений. Если это выходное значение больше входного значения, функция завершилась ошибкой из-за недостаточного размера буфера.
[in, optional] lpServiceAsyncInfo
Зарезервировано для дальнейшего использования. Необходимо задать значение NULL.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение равно числу структур NS_SERVICE_INFO, хранящихся в *lpBuffer. Ноль указывает, что структуры не были сохранены.
Если функция завершается ошибкой, возвращаемое значение SOCKET_ERROR ( – 1). Чтобы получить расширенные сведения об ошибке, вызовите GetLastError, которая возвращает одно из следующих расширенных значений ошибок.
| Код ошибки | Значение |
|---|---|
|
Буфер, на который указывает lpBuffer, слишком мал, чтобы получить всю запрошенную информацию. Вызовите функцию с буфером по крайней мере размером, как значение, возвращаемое в *lpdwBufferSize. |
|
Указанная служба не найдена, или указанное пространство имен не используется. Возвращаемое значение функции равно нулю в данном случае. |
Замечания
Заметка
Заголовок nspapi.h определяет GetService как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 2000 Профессиональный [только классические приложения] |
| минимальный поддерживаемый сервер | Windows 2000 Server [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | nspapi.h |
| библиотеки |
Mswsock.lib |
| DLL | Mswsock.dll |
См. также
Справочник