Funzione di callback LPWSPACCEPT (ws2spi.h)

Articolo
03/15/2023

La funzione LPWSPAccept 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, come noto per il provider di servizi. Il formato esatto del parametro addr è determinato dalla famiglia di indirizzi stabilita quando è stato creato il socket nella struttura sockaddr .

[in, out] addrlen

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

[in] lpfnCondition

Indirizzo dell'istanza di procedura di una funzione condizione facoltativa fornita da Windows Sockets. Questa funzione viene usata nella decisione accettare o rifiutare 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 condizione. 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 di 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 degli indirizzi utente.
WSAEINTR	Una chiamata (blocco) è stata annullata tramite LPWSPCancelBlockingCall.
WSAEINPROGRESS	Una chiamata Windows Sockets bloccata è in corso.
WSAEINVAL	LPWSPListen non è stato richiamato prima di LPWSPAccept, il parametro g specificato nella funzione condizione non è un valore valido, il valore restituito della funzione condizione non è valido o in qualsiasi caso in cui il socket specificato è in uno stato non valido.
WSAEMFILE	La coda non viene interrotta dopo l'ingresso a LPWSPAccept e non sono disponibili descrittori socket.
WSAENOBUFS	Nessuno spazio di buffer disponibile.
WSAENOTSOCK	Il descrittore non è un socket.
WSAEOPNOTSUPP	Il 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 è stata annullata o ritirata.

Commenti

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

I socket appena creati hanno le stesse proprietà del socket s, 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 eseguire l'azione sulla richiesta di connessione, richiama nuovamente LPWSPAccept e restituisce CF_ACCEPT o CF_REJECT come valore restituito dalla funzione condizione.

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

Il componente aggiuntivo del parametro è un parametro di risultato riempito con l'indirizzo dell'entità di connessione, come noto per il provider di servizi. Il formato esatto del parametro addr è determinato dalla famiglia di indirizzi in cui si sta verificando la comunicazione. L'addrlen è un parametro value-result; inizialmente conterrà la quantità di spazio puntata da addr. Al ritorno, deve contenere la lunghezza effettiva (in byte) dell'indirizzo restituito dal provider di servizi. Questa chiamata viene usata con tipi di socket orientati alla connessione, ad esempio SOCK_STREAM. Se addr e/o addrlen sono uguali a Null, non vengono restituite informazioni sull'indirizzo remoto del socket accettato. In caso contrario, questi due parametri devono essere compilati indipendentemente dal fatto che la funzione condizione sia specificata o che restituisca.

Il prototipo della funzione 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
);

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 tempo 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 della WSABUF puntata da 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 specifici del provider aggiuntivi. I valori di specifica del flusso di invio o ricezione verranno ignorati in base alle esigenze di qualsiasi socket unidirectionale. Un valore Null per lpSQOS indica che non esiste alcun chiamante fornito da QoS e che nessuna negoziazione è possibile. Un puntatore non NULLlpSQOS indica che si verifica una negoziazione QoS o che il provider è pronto ad accettare la richiesta QoS senza negoziazione.

LpCalleeId è un parametro valore che contiene l'indirizzo locale dell'entità connessa. La parte buf della WSABUF puntata da 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).

LpCalleeData è un parametro di risultato usato dalla funzione condizione per fornire i dati utente all'entità di connessione. L'archiviazione per questi dati deve essere fornita dal provider di servizi. LpCalleeData-len contiene inizialmente la lunghezza del buffer allocata dal provider di servizi e punta a lpCalleeData-buf>.> Un valore pari a zero significa che il passaggio dei dati utente al chiamante non è supportato. La funzione condizione copia fino a lpCalleeData-len byte di dati in lpCalleeData-buf>> e quindi aggiorna lpCalleeData-len> per indicare il numero effettivo di byte trasferiti. Se non vengono passati dati utente al chiamante, la funzione condizione imposta lpCalleeData-len> su zero. Il formato di tutti gli indirizzi e i dati 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. Ciò consente a un client di passare alcune informazioni di contesto dal sito di chiamata LPWSPAccept alla funzione condizione, che fornisce la funzione condizione con eventuali informazioni aggiuntive necessarie per determinare se accettare la connessione. Un utilizzo tipico consiste nel passare un puntatore (in modo adeguato) a una struttura di dati contenente riferimenti agli oggetti definiti dall'applicazione con cui è associato questo socket.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ws2spi.h