Funzione di callback LPWSPACCEPT (ws2spi.h)

Articolo
07/16/2024

La LPWSPAccept funzione accetta in modo condizionale una connessione in base al valore restituito di una funzione condizione.

Sintassi

LPWSPACCEPT Lpwspaccept;

SOCKET Lpwspaccept(
  [in]      SOCKET s,
  [out]     sockaddr *addr,
  [in, out] LPINT addrlen,
  [in]      LPCONDITIONPROC lpfnCondition,
  [in]      DWORD_PTR dwCallbackData,
  [out]     LPINT lpErrno
)
{...}

Parametri

[in] s

Descrittore che identifica un socket in ascolto delle connessioni dopo un LPWSPListen.

[out] addr

Puntatore facoltativo a un buffer che riceve l'indirizzo dell'entità di connessione, noto come provider di servizi. Il formato esatto del parametro addr viene determinato dalla famiglia di indirizzi stabilita quando è stato creato il socket nella struttura sockaddr.

[in, out] addrlen

Puntatore facoltativo a un numero intero contenente la lunghezza del parametro addr , in byte.

[in] lpfnCondition

Indirizzo dell'istanza di routine di una funzione di condizione facoltativa fornita da Windows Sockets. Questa funzione viene usata nella decisione accept o reject in base alle informazioni del chiamante passate come parametri.

[in] dwCallbackData

I dati di callback da passare al client Windows Socket 2 come valore del parametro dwCallbackData della funzione condition. Questo parametro non viene interpretato dal provider di servizi.

[out] lpErrno

Puntatore al codice di errore.

Valore restituito

Se non si verifica alcun errore, LPWSPAccept restituisce un valore di tipo SOCKET che è un descrittore per il socket accettato. In caso contrario, viene restituito un valore di INVALID_SOCKET e un codice di errore specifico è disponibile in lpErrno.

Codice errore	Significato
WSAECONNREFUSED	La richiesta di connessione è stata rifiutata forzatamente come indicato nel valore restituito della funzione condizione (CF_REJECT).
WSAECONNRESET	È stata indicata una connessione in ingresso, ma successivamente è stata terminata dal peer remoto prima di accettare la chiamata.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAEFAULT	Il parametro addrlen è troppo piccolo o il parametro lpfnCondition non fa parte dello spazio indirizzi utente.
WSAEINTR	Una chiamata (blocco) è stata annullata tramite LPWSPCancelBlockingCall.
WSAEINPROGRESS	È in corso una chiamata di Windows Sockets bloccante.
WSAEINVAL	LPWSPListen non è stato richiamato prima di LPWSPAccept, il parametro g specificato nella funzione della condizione non è un valore valido, il valore restituito della funzione della condizione non è valido o qualsiasi caso in cui il socket specificato non sia in uno stato non valido.
WSAEMFILE	La coda non viene annullata all'ingresso in LPWSPAccept e non sono disponibili descrittori socket.
WSAENOBUFS	Non è disponibile alcuno spazio nel buffer.
WSAENOTSOCK	Il descrittore non è un socket.
WSAEOPNOTSUPP	Socket a cui si fa riferimento non è un tipo che supporta il servizio orientato alla connessione.
WSATRY_AGAIN	L'accettazione della richiesta di connessione è stata posticipata come indicato nel valore restituito della funzione condizione (CF_DEFER).
WSAEWOULDBLOCK	Il socket è contrassegnato come non bloccante e non sono presenti connessioni da accettare.
WSAEACCES	La richiesta di connessione offerta è scaduta o ritirata.

Osservazioni

La funzione LPWSPAccept estrae la prima connessione nella coda di connessioni in sospeso sul socket e la controlla sulla funzione della condizione, purché venga specificata la funzione condizione (ovvero, non Null). La funzione condizione deve essere eseguita nello stesso thread di questa routine. Se la funzione condition restituisce CF_ACCEPT, LPWSPAccept crea un nuovo socket.

I socket appena creati hanno le stesse proprietà del socket , inclusi gli eventi di rete registrati con LPWSPAsyncSelect o con LPWSPEventSelect. Come descritto in DescriptorAllocation, quando vengono allocati nuovi descrittori socket, i provider IFS devono chiamare WPUModifyIFSHandle e provider non IFS devono chiamare WPUCreateSocketHandle.

Se la funzione condizione restituisce CF_REJECT, LPWSPAccept rifiuta la richiesta di connessione. Se non è possibile prendere immediatamente la decisione di accettazione/rifiuto dell'applicazione, la funzione condizione restituirà CF_DEFER per indicare che non è stata presa alcuna decisione. Nessuna azione su questa richiesta di connessione deve essere eseguita dal provider di servizi. Quando l'applicazione è pronta per intervenire sulla richiesta di connessione, richiama LPWSPAccept e restituisce CF_ACCEPT o CF_REJECT come valore restituito dalla funzione condizione.

Per i socket in modalità di blocco (impostazione predefinita), se nella coda non sono presenti connessioni in sospeso, LPWSPAccept blocca il chiamante fino a quando non è presente una connessione. Per i socket in modalità non bloccante, se questa funzione viene chiamata quando non sono presenti connessioni in sospeso nella coda, LPWSPAccept restituisce il codice di errore WSAEWOULDBLOCK. Il socket accettato non può essere utilizzato per accettare più connessioni. Il socket originale rimane aperto.

Il parametro addr è un parametro di risultato compilato con l'indirizzo dell'entità di connessione, noto come provider di servizi. Il formato esatto del parametro di addr è determinato dalla famiglia di indirizzi in cui si sta verificando la comunicazione. Il addrlen è un parametro value-result; inizialmente conterrà la quantità di spazio a cui punta addr. In caso di restituzione, deve contenere la lunghezza effettiva (in byte) dell'indirizzo restituito dal provider di servizi. Questa chiamata viene usata con tipi socket orientati alla connessione, ad esempio SOCK_STREAM. Se addr e/o addrlen sono uguali a Null, non viene restituita alcuna informazione sull'indirizzo remoto del socket accettato. In caso contrario, questi due parametri devono essere compilati indipendentemente dal fatto che la funzione della condizione venga specificata o restituita.

Il prototipo della funzione della condizione è il seguente.

int CALLBACK 
ConditionFunc( 
  IN     LPWSABUF    lpCallerId, 
  IN     LPWSABUF    lpCallerData, 
  IN OUT LPQOS       lpSQOS, 
  IN OUT LPQOS       lpGQOS,
  IN     LPWSABUF    lpCalleeId, 
  IN     LPWSABUF    lpCalleeData, 
  OUT    GROUP FAR * g, 	
  IN     DWORD_PTR   dwCallbackData
);

Il lpCallerId e lpCallerData sono parametri di valore che devono contenere l'indirizzo dell'entità di connessione e tutti i dati utente inviati insieme alla richiesta di connessione. Se non è disponibile alcun identificatore del chiamante o dati del chiamante, il parametro corrispondente sarà Null. Molti protocolli di rete non supportano i dati del chiamante in fase di connessione. La maggior parte dei protocolli di rete convenzionali può essere prevista per supportare le informazioni sull'identificatore del chiamante in fase di richiesta di connessione. La parte buf del WSABUF a cui punta lpCallerId punta a un sockaddr. Il sockaddr viene interpretato in base alla famiglia di indirizzi (in genere eseguendo il cast del sockaddr a un tipo specifico della famiglia di indirizzi).

Il parametro lpSQOS fa riferimento alle specifiche del flusso per il socket specificato dal chiamante, uno per ogni direzione, seguito da eventuali parametri aggiuntivi specifici del provider. I valori di specifica del flusso di invio o ricezione verranno ignorati in base alle esigenze di qualsiasi socket unidirezionale. Un valore Null per lpSQOS indica che non è disponibile alcun QoS fornito dal chiamante e che non è possibile negoziare. Un puntatore NULL nonNULLlpSQOS indica che si verifica una negoziazione QoS o che il provider è pronto ad accettare la richiesta QoS senza negoziazione.

Il lpCalleeId è un parametro di valore che contiene l'indirizzo locale dell'entità connessa. La buf parte della WSABUF a cui punta lpCalleeId punta a un sockaddr. Il sockaddr viene interpretato in base alla famiglia di indirizzi (in genere eseguendo il cast del sockaddr a un tipo specifico della famiglia di indirizzi).

Il lpCalleeData è un parametro di risultato usato dalla funzione condition per fornire i dati utente all'entità di connessione. L'archiviazione per questi dati deve essere fornita dal provider di servizi. IllpCalleeData -len contiene inizialmente la lunghezza del buffer allocato dal provider di servizi e punta a lpCalleeData-buf. Un valore pari a zero indica che il passaggio dei dati utente al chiamante non è supportato. La funzione condition copia fino a lpCalleeData->len byte di dati in lpCalleeData->bufe quindi aggiornare lpCalleeData->len per indicare il numero effettivo di byte trasferiti. Se nessun dato utente deve essere passato al chiamante, la funzione condizione imposta lpCalleeData->len su zero. Il formato di tutti i dati di indirizzo e utente è specifico della famiglia di indirizzi a cui appartiene il socket.

Il valore del parametro dwCallbackData passato alla funzione condition è il valore passato come parametro dwCallbackData nella chiamata LPWSPAccept originale. Questo valore viene interpretato solo dal client Windows Sockets 2. In questo modo un client può passare alcune informazioni di contesto dal LPWSPAccept sito di chiamata alla funzione condizione, che fornisce alla funzione condizione eventuali informazioni aggiuntive necessarie per determinare se accettare la connessione. Un utilizzo tipico consiste nel passare un puntatore (correttamente cast) a una struttura di dati contenente riferimenti a oggetti definiti dall'applicazione a cui è associato questo socket.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	ws2spi.h