Funzione RpcBindingBind (rpcasync.h)

Articolo
03/15/2023

La funzione RpcBindingBind contatta un server RPC e la associa.

Sintassi

RPC_STATUS RpcBindingBind(
  [in, optional] PRPC_ASYNC_STATE   pAsync,
  [in]           RPC_BINDING_HANDLE Binding,
  [in]           RPC_IF_HANDLE      IfSpec
);

Parametri

[in, optional] pAsync

Puntatore alla struttura RPC_ASYNC_STATE che contiene informazioni sulle chiamate asincrone. Queste informazioni sullo stato contengono il metodo di completamento usato per segnalare quando l'operazione di associazione è stata completata.

[in] Binding

RPC_BINDING_HANDLE struttura che contiene l'handle di associazione creato con una chiamata precedente a RpcBindingCreate.

[in] IfSpec

RPC_IF_HANDLE valore che specifica l'interfaccia in cui verranno effettuate le chiamate per questo handle di associazione.

Valore restituito

Questa funzione restituisce RPC_S_OK in caso di esito positivo; in caso contrario, viene restituito un codice di errore RPC_S_*. Per informazioni su questi codici di errore, vedere Valori restituiti RPC.

Codice restituito	Descrizione
RPC_S_OK	È possibile associare l'RPC al server e le chiamate remote possono essere effettuate.
RPC_S_CANNOT_SUPPORT	Per questa operazione di associazione è stata richiesta una funzionalità obsoleta di RPC.

Nota Per un elenco di codici di errore validi, vedere Valori restituiti RPC.

Commenti

RpcBindingBind contatta il server RPC e lo associa usando l'handle di associazione restituito da una chiamata precedente a RpcBindingCreate. Gli handle di associazione stabiliti usando questo metodo vengono definiti handle di associazione "veloci".

Se il valore del parametro pAsync non è NULL, il binding sarà asincrono e le chiamate a RpcAsyncCancelCall e RpcAsyncGetCallStatus possono essere effettuate sullo stato asincrono fornito. Metodo di completamento specificato nelle informazioni sullo stato asincrono usate per segnalare al chiamante che l'associazione è stata completata. Al termine della notifica, le chiamate possono essere effettuate usando l'handle di associazione appena associato.

Il metodo bind non determina le chiamate che è possibile eseguire usando l'handle di associazione. Se l'associazione è sincrona, è comunque possibile eseguire chiamate asincrone sull'handle di associazione e viceversa. Il metodo bind determina la modalità di segnalazione della notifica per un'associazione riuscita, in particolare nel caso di associazioni asincrone.

Poiché questa API scambia messaggi con il server RPC, le operazioni di associazione possono richiedere molto tempo in base a diversi fattori indipendenti, tra cui il traffico di rete e il blocco del server. Se l'associazione è sincrona, l'operazione di associazione può bloccare se il server è bloccato.

Al termine dell'associazione, la semantica delle chiamate effettuate sull'handle di associazione è la stessa delle chiamate effettuate su qualsiasi altro tipo di handle di associazione, ma con quattro differenze rilevanti, elencate di seguito:

Tutte le chiamate a questo handle di associazione devono essere effettuate sull'interfaccia specificata in IfSpec. L'handle di associazione è associato in modo univoco a questa interfaccia. L'interfaccia stessa può essere scaricata prima che l'handle di associazione venga eliminato definitivamente, ma le informazioni complete sull'interfaccia vengono memorizzate nella cache nell'handle di associazione e, se viene eseguita una chiamata sullo stesso handle di associazione per un'interfaccia diversa, i risultati non sono definiti.
I callback RPC non sono consentiti in un handle di associazione. Se il server RPC tenta di eseguire un callback usando un metodo con l'attributo [callback], la chiamata viene rifiutata con il codice di stato di errore RPC_S_CANNOT_SUPPORT.
Con gli handle di associazione classici, RPC tenterà di riconnettersi in modo trasparente con il server se la connessione viene interrotta. Per gli handle di associazione rapida, RPC non tenterà di riconnettersi in modo trasparente al server; restituirà invece uno degli errori seguenti: RPC_S_SERVER_UNAVAILABLE, RPC_S_CALL_FAILED e RPC_C_CALL_FAILED_DNE. Se la connessione viene eliminata a causa di credenziali rifiutate, viene restituito RPC_S_ACCESS_DENIED; e se il server rileva un errore temporaneo a causa di una mancanza di memoria, viene restituito RPC_S_OUT_OF_MEMORY. Qualsiasi altro errore di connettività è il risultato del marshalling o dell'annullamento del marshalling degli errori restituiti dalle routine del server. Nel caso di una connessione persa, il chiamato deve annullare l'associazione chiamando RpcBindingUnbind e quindi riassociare con un'altra chiamata a RpcBindingBind.

Se la chiamata a RpcBindingBind ha esito negativo, l'handle di associazione non è associato al server e il chiamante può tentare di eseguire di nuovo l'associazione con un'altra chiamata alla stessa API oppure liberare l'handle di associazione. Poiché un'operazione di associazione non riuscita non sposta l'handle di associazione allo stato associato, RpcBindingUnbind non deve essere chiamato su di esso.

Alcune funzioni non devono essere chiamate finché l'operazione di associazione non ha segnalato il completamento, in particolare:

Nota Attualmente, questa funzione supporta solo la sequenza di protocollo ncalrpc .

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista, Windows XP con SP2 [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008, Windows Server 2003 con SP1 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	rpcasync.h (include Rpc.h)
Libreria	Rpcrt4.lib
DLL	Rpcrt4.dll

Vedi anche

RpcBindingCreate

RpcBindingUnbind

Condividi tramite