Funzione WSASetServiceA (winsock2.h)

Articolo
11/20/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 deregistrazione.

[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 questo significa inviare una trasmissione periodica. Si tratta di un NOP per lo spazio dei nomi DNS. Per gli archivi dati persistenti, ciò significa aggiornare le informazioni sull'indirizzo.
RNRSERVICE_DEREGISTER	Rimuovere il servizio dal Registro di sistema. Per SAP questo 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 sugli indirizzi.
RNRSERVICE_DELETE	Eliminare il servizio da spazi permanenti e nome dinamico. Per i servizi rappresentati da più strutture di CSADDR_INFO (utilizzando il flag 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 di WSASetService . I valori possibili per questo parametro vengono definiti nel file di intestazione Winsock2. h.

Bandiera	Significato
SERVICE_MULTIPLE	Controlla l'ambito dell'operazione. Quando questo flag non è impostato, gli indirizzi del servizio vengono gestiti come gruppo. Un registro o una 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 specificato di indirizzi.

Bandiera

Significato

SERVICE_MULTIPLE

Controlla l'ambito dell'operazione. Quando questo flag non è impostato, gli indirizzi del servizio vengono gestiti come gruppo. Un registro o una 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 specificato di indirizzi.

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 un numero di errore specifico può essere recuperato 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 Windows Sockets.
WSA_NOT_ENOUGH_MEMORY	Memoria insufficiente per eseguire l'operazione.

Osservazioni

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

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

Operazione	Bandiere	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. Usa 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, può scoprire che un socket in ascolto viene interrotto, ma gli altri socket rimangono 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 consentire 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 utilizzate stringhe di caratteri ANSI, è possibile che i dati di WSAQUERYSET in lpqsRegInfo non contengano risultati dopo la restituzione di questa funzione. Questo perché la versione ANSI di questo metodo, WSASetServiceA, converte i dati ANSI in WSAQUERYSET in Unicode internamente, ma non converte 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 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 di 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 a cui si fa riferimento contiene il nome dell'istanza del servizio.
lpServiceClassId	GUID corrispondente a questa classe del 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 di CSADDR_INFO a cui fa riferimento lpcsaBuffer.
lpcsaBuffer	Puntatore a una matrice di strutture CSADDR_INFO che contengono gli indirizzi 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 di dwNameSpace e lpNSProviderId membri determinano 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 nome valido	Nullo	Tutti i provider di spazi dei nomi che supportano lo spazio dei nomi indicato.
NS_ALL	Nullo	Tutti i provider di spazi dei nomi.

Windows Phone 8: La funzione WSASetServiceW è supportata per le app di 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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

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	Finestre
intestazione	winsock2.h
libreria	Ws2_32.lib
dll	Ws2_32.dll