Funzione GetServiceA (nspapi.h)
La funzione GetService recupera informazioni su un servizio di rete nel contesto di un set di spazi dei nomi predefiniti o uno spazio dei nomi specificato. Il servizio di rete viene specificato dal relativo tipo e nome. Le informazioni sul servizio vengono ottenute come set di strutture di dati NS_SERVICE_INFO .
Sintassi
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
);
Parametri
[in] dwNameSpace
Spazio dei nomi o un set di spazi dei nomi predefiniti, che il sistema operativo deve eseguire query per informazioni sul servizio di rete specificato.
Usare una delle costanti seguenti per specificare uno spazio dei nomi.
La maggior parte delle chiamate a GetService deve usare il valore speciale NS_DEFAULT. Ciò consente a un client di ottenere senza conoscere gli spazi dei nomi disponibili in un internetwork. L'amministratore di sistema determina l'accesso allo spazio dei nomi. Gli spazi dei nomi possono venire e andare senza che il client deve essere consapevole delle modifiche.
[in] lpGuid
Puntatore a un identificatore univoco globale (GUID) che specifica il tipo del servizio di rete. Il file di intestazione Svcguid.h include tipi di servizio GUID da molti servizi noti all'interno degli spazi dei nomi DNS e SAP.
Il file di intestazione Svcguid.h non viene automaticamente incluso dal file di intestazione Winsock2.h .
[in] lpServiceName
Puntatore a una stringa con terminazione zero che rappresenta in modo univoco il nome del servizio. Ad esempio, "MY SNA SERVER".
[in] dwProperties
Set di flag di bit che specificano le informazioni sul servizio recuperate dalla funzione. Ognuna di queste costanti del flag di bit, diversa da PROP_ALL, corrisponde a un particolare membro della struttura di dati SERVICE_INFO. Se il flag è impostato, la funzione inserisce le informazioni nel membro corrispondente delle strutture di dati archiviate in *lpBuffer. Vengono definiti i flag di bit seguenti.
[out] lpBuffer
Puntatore a un buffer per ricevere una matrice di strutture NS_SERVICE_INFO e informazioni di servizio associate. Ogni struttura NS_SERVICE_INFO contiene informazioni sul servizio nel contesto di uno spazio dei nomi specifico. Si noti che se dwNameSpace è NS_DEFAULT, la funzione archivia più di una struttura nel buffer; in caso contrario, viene archiviata una sola struttura.
Ogni struttura NS_SERVICE_INFO contiene una struttura SERVICE_INFO . I membri di queste strutture di SERVICE_INFO contengono dati validi in base ai flag di bit impostati nel parametro dwProperties . Se il flag di bit corrispondente di un membro non è impostato in dwProperties, il valore del membro non è definito.
La funzione archivia le strutture NS_SERVICE_INFO in una matrice consecutiva, a partire dall'inizio del buffer. I puntatori nelle strutture SERVICE_INFO contenute puntano a informazioni archiviate nel buffer tra la fine delle strutture di NS_SERVICE_INFO e la fine del buffer.
[in, out] lpdwBufferSize
Puntatore a una variabile che, in input, contiene le dimensioni, in byte, del buffer a cui punta lpBuffer. Nell'output, questa variabile contiene il numero di byte necessari per archiviare le informazioni richieste. Se questo valore di output è maggiore del valore di input, la funzione non è riuscita a causa di dimensioni del buffer insufficienti.
[in, optional] lpServiceAsyncInfo
Riservato per utilizzi futuri. Deve essere impostato su NULL.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è il numero di strutture NS_SERVICE_INFO archiviate in *lpBuffer. Zero indica che non sono state archiviate strutture.
Se la funzione ha esito negativo, il valore restituito è SOCKET_ERROR ( - 1). Per ottenere informazioni sull'errore estese, chiamare GetLastError, che restituisce uno dei valori di errore estesi seguenti.
| Codice di errore | Significato |
|---|---|
|
Il buffer a cui punta lpBuffer è troppo piccolo per ricevere tutte le informazioni richieste. Chiamare la funzione con un buffer almeno pari al valore restituito in *lpdwBufferSize. |
|
Il servizio specificato non è stato trovato oppure lo spazio dei nomi specificato non è in uso. Il valore restituito dalla funzione è zero in questo caso. |
Commenti
Nota
L'intestazione nspapi.h definisce GetService come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | nspapi.h |
| Libreria | Mswsock.lib |
| DLL | Mswsock.dll |