Funzione WSASetServiceA (winsock2.h)

Articolo
03/13/2024

La funzione WSASetService registra o rimuove dal Registro di sistema un'istanza del servizio all'interno di uno o più spazi dei nomi.

Sintassi

INT WSAAPI WSASetServiceA(
  [in] LPWSAQUERYSETA   lpqsRegInfo,
  [in] WSAESETSERVICEOP essoperation,
  [in] DWORD            dwControlFlags
);

Parametri

[in] lpqsRegInfo

Puntatore alle informazioni del servizio per la registrazione o la registrazione.

[in] essoperation

Valore che determina l'operazione richiesta. Questo parametro può essere uno dei valori del tipo di enumerazione WSAESETSERVICEOP definito nel file di intestazione Winsock2.h .

Valore	Significato
RNRSERVICE_REGISTER	Registrare il servizio. Per SAP, ciò significa inviare una trasmissione periodica. Si tratta di un NOP per lo spazio dei nomi DNS. Per gli archivi dati permanenti, ciò significa aggiornare le informazioni sull'indirizzo.
RNRSERVICE_DEREGISTER	Rimuovere il servizio dal Registro di sistema. Per SAP, ciò significa interrompere l'invio della trasmissione periodica. Si tratta di un NOP per lo spazio dei nomi DNS. Per gli archivi dati persistenti ciò significa eliminare le informazioni sull'indirizzo.
RNRSERVICE_DELETE	Eliminare il servizio da spazi permanenti e nome dinamico. Per i servizi rappresentati da più strutture di CSADDR_INFO (utilizzando il flag di SERVICE_MULTIPLE), verrà eliminato solo l'indirizzo specificato e deve corrispondere esattamente alla struttura CSADDR_INFO corrispondente specificata al momento della registrazione del servizio.

[in] dwControlFlags

Il valore di installazione del servizio controlla ulteriormente l'operazione eseguita dalla funzione WSASetService . I valori possibili per questo parametro sono definiti nel file di intestazione Winsock2.h .

Contrassegno	Significato
SERVICE_MULTIPLE	Controlla l'ambito dell'operazione. Quando questo flag non è impostato, gli indirizzi del servizio vengono gestiti come gruppo. Un registro o la rimozione dal Registro di sistema invalida tutti gli indirizzi esistenti prima di aggiungere il set di indirizzi specificato. Se impostata, l'azione viene eseguita solo sul set di indirizzi specificato. Un registro non invalida gli indirizzi esistenti e una rimozione dal Registro di sistema invalida solo il set di indirizzi specificato.

Contrassegno

Significato

SERVICE_MULTIPLE

Controlla l'ambito dell'operazione. Quando questo flag non è impostato, gli indirizzi del servizio vengono gestiti come gruppo. Un registro o la rimozione dal Registro di sistema invalida tutti gli indirizzi esistenti prima di aggiungere il set di indirizzi specificato. Se impostata, l'azione viene eseguita solo sul set di indirizzi specificato. Un registro non invalida gli indirizzi esistenti e una rimozione dal Registro di sistema invalida solo il set di indirizzi specificato.

Valore restituito

Il valore restituito per WSASetService è zero se l'operazione ha avuto esito positivo. In caso contrario, viene restituito il valore SOCKET_ERROR e è possibile recuperare un numero di errore specifico chiamando WSAGetLastError.

Codice di errore	Significato
WSAEACCES	La routine chiamante non dispone di privilegi sufficienti per installare il servizio.
WSAEINVAL	Uno o più parametri obbligatori non sono validi o mancanti.
WSANOTINITIALISED	Il Ws2_32.dll non è stato inizializzato. L'applicazione deve prima chiamare WSAStartup prima di chiamare qualsiasi funzione Di Windows Sockets.
WSA_NOT_ENOUGH_MEMORY	Memoria insufficiente per eseguire l'operazione.

Commenti

La funzione WSASetService può essere usata per influire su un provider di spazi dei nomi specifico, tutti i provider associati a uno spazio dei nomi specifico o tutti i provider in tutti gli spazi dei nomi.

I valori disponibili per essOperation e dwControlFlags combinano per controllare l'operazione della funzione WSASetService , come illustrato nella tabella seguente.

Operazione	Flags	Il servizio esiste già	Il servizio non esiste
RNRSERVICE_REGISTER	Nessuno	Sovrascrive l'oggetto . Usa solo gli indirizzi specificati. L'oggetto è REGISTERED.	Crea un nuovo oggetto. Usa solo gli indirizzi specificati. L'oggetto è REGISTERED.
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	Aggiorna l'oggetto. Aggiunge nuovi indirizzi al set esistente. L'oggetto è REGISTERED.	Crea un nuovo oggetto. Utilizza tutti gli indirizzi specificati. L'oggetto è REGISTERED.
RNRSERVICE_DEREGISTER	Nessuno	Rimuove tutti gli indirizzi, ma non rimuove l'oggetto dallo spazio dei nomi . L'oggetto viene rimosso dal Registro di sistema.	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	Aggiorna l'oggetto. Rimuove solo gli indirizzi specificati. Contrassegna l'oggetto come DEREGISTERED solo se non sono presenti indirizzi. Non rimuove l'oggetto dallo spazio dei nomi .	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	Nessuno	Rimuove l'oggetto dallo spazio dei nomi .	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	Rimuove solo gli indirizzi specificati. Rimuove l'oggetto dallo spazio dei nomi solo se non rimangono indirizzi.	WSASERVICE_NOT_FOUND

La pubblicazione di servizi in directory, ad esempio Servizi Active Directory, è limitata in base agli elenchi di controllo di accesso (ACL). Per altre informazioni, vedere Problemi di sicurezza per la pubblicazione del servizio.

Quando il parametro dwControlFlags è impostato su SERVICE_MULTIPLE, un'applicazione può gestire gli indirizzi in modo indipendente. Ciò è utile quando l'applicazione vuole gestire i protocolli singolarmente o quando il servizio risiede in più computer. Ad esempio, quando un servizio usa più di un protocollo, è possibile che un socket in ascolto venga interrotto, ma gli altri socket rimangano operativi. In questo caso, il servizio potrebbe rimuovere l'indirizzo interrotto dal Registro di sistema senza influire sugli altri indirizzi.

Quando il parametro dwControlFlags è impostato su SERVICE_MULTIPLE, un'applicazione non deve lasciare che gli indirizzi non aggiornati rimangano nell'oggetto. Ciò può verificarsi se l'applicazione viene interrotta senza inviare una richiesta DEREGISTER. Quando un servizio viene registrato, deve archiviarne gli indirizzi. Nella chiamata successiva, il servizio deve rimuovere in modo esplicito questi vecchi indirizzi non aggiornati dal Registro di sistema prima di registrare nuovi indirizzi.

Nota Se vengono usate stringhe di caratteri ANSI, è possibile che i dati WSAQUERYSET in lpqsRegInfo non contengano risultati dopo che questa funzione restituisce. Poiché la versione ANSI di questo metodo, WSASetServiceA, converte i dati ANSI in WSAQUERYSET in Unicode internamente, ma non converte nuovamente i risultati in ANSI. Ciò influisce principalmente sui trasporti che restituiscono un "handle di record di servizio" usato per identificare in modo univoco un record. Per risolvere questo problema, le applicazioni devono usare i dati stringa Unicode in WSAQUERYSET quando si chiama questa funzione.

Proprietà del servizio

Nella tabella seguente viene descritto il modo in cui i dati delle proprietà del servizio vengono rappresentati in una struttura WSAQUERYSET . I campi etichettati come (facoltativo) possono contenere un puntatore Null.

Membro WSAQUERYSET	Descrizione della proprietà del servizio
dwSize	Deve essere impostato su sizeof (WSAQUERYSET). Si tratta di un meccanismo di controllo delle versioni.
dwOutputFlags	Non applicabile e ignorato.
lpszServiceInstanceName	La stringa di riferimento contiene il nome dell'istanza del servizio.
lpServiceClassId	GUID corrispondente a questa classe di servizio.
lpVersion	(Facoltativo) Fornisce il numero di versione dell'istanza del servizio.
lpszComment	(Facoltativo) Stringa di commento facoltativa.
dwNameSpace	Vedere la tabella seguente.
lpNSProviderId	Vedere la tabella seguente.
lpszContext	(Facoltativo) Specifica il punto iniziale della query in uno spazio dei nomi gerarchico.
dwNumberOfProtocols	Ignorato.
lpafpProtocols	Ignorato.
lpszQueryString	Ignorato.
dwNumberOfCsAddrs	Numero di elementi nella matrice di strutture CSADDR_INFO a cui fa riferimento lpcsaBuffer.
lpcsaBuffer	Puntatore a una matrice di strutture CSADDR_INFO contenenti l'indirizzo (es) su cui il servizio è in ascolto.
lpBlob	(Facoltativo) Si tratta di un puntatore a un'entità specifica del provider.

Come illustrato di seguito, la combinazione dei membri dwNameSpace e lpNSProviderId determina che i provider di spazi dei nomi sono interessati da questa funzione.

dwNameSpace	lpNSProviderId	Ambito dell'impatto
Ignorato	Non Null	Provider di spazio dei nomi specificato.
Identificatore di spazio di nome valido	Null	Tutti i provider di spazio dei nomi che supportano lo spazio dei nomi indicato.
NS_ALL	Null	Tutti i provider di spazi dei nomi.

Windows Phone 8: la funzione WSASetServiceW è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: la funzione WSASetServiceW è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Nota

L'intestazione winsock2.h definisce WSASetService come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock2.h
Libreria	Ws2_32.lib
DLL	Ws2_32.dll