Funzione RpcServerRegisterIfEx (rpcdce.h)

Articolo
03/01/2024

La funzione RpcServerRegisterIfEx registra un'interfaccia con la libreria di runtime RPC.

Sintassi

RPC_STATUS RpcServerRegisterIfEx(
  RPC_IF_HANDLE      IfSpec,
  UUID               *MgrTypeUuid,
  RPC_MGR_EPV        *MgrEpv,
  unsigned int       Flags,
  unsigned int       MaxCalls,
  RPC_IF_CALLBACK_FN *IfCallback
);

Parametri

IfSpec

Struttura generata da MIDL che indica l'interfaccia da registrare.

MgrTypeUuid

Puntatore a un UUID di tipo da associare al parametro MgrEpv . Se si specifica un valore di parametro Null (o un UUID nil) si registra IfSpec con un UUID di tipo nil.

MgrEpv

Vettore del punto di ingresso (EPV) delle routine di gestione. Per usare l'EPV predefinito generato da MIDL, specificare un valore Null . Per altre informazioni, vedere RPC_MGR_EPV.

Flags

Bandiere. Per un elenco dei valori dei flag, vedere Flag di registrazione interfaccia.

MaxCalls

Numero massimo di richieste di chiamata di routine remota simultanee che il server può accettare in un'interfaccia di ascolto automatico. I parametri MaxCalls sono applicabili solo a un'interfaccia di ascolto automatico e vengono ignorati nelle interfacce che non sono in ascolto automatico. La libreria di runtime RPC esegue il massimo sforzo per garantire che il server non consenta più richieste di chiamata simultanee rispetto al numero di chiamate specificate in MaxCalls. Il numero effettivo può essere maggiore e può variare per ogni sequenza di protocollo.

Le chiamate su altre interfacce sono regolate dal valore del parametro MaxCalls a livello di processo specificato nella chiamata di funzione RpcServerListen .

Se il numero di chiamate simultanee non è un problema, è possibile ottenere prestazioni lato server leggermente migliori specificando il valore predefinito usando RPC_C_LISTEN_MAX_CALLS_DEFAULT. In questo modo, l'ambiente di runtime RPC evita l'applicazione di una restrizione non necessaria.

IfCallback

Funzione di callback di sicurezza o NULL per nessun callback. Ogni interfaccia registrata può avere una funzione di callback diversa. Per altri dettagli, vedere La sezione Osservazioni.

Valore restituito

Restituisce RPC_S_OK in caso di esito positivo.

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

Commenti

I parametri e gli effetti di RpcServerRegisterIfEx presumono quelli di RpcServerRegisterIf. La differenza è la possibilità di registrare un'interfaccia di ascolto automatico e di specificare una funzione di callback di sicurezza.

Il codice dell'applicazione server chiama RpcServerRegisterIfEx per registrare un'interfaccia. Per registrare un'interfaccia, il server fornisce le informazioni seguenti:

Specifica dell'interfaccia
La specifica dell'interfaccia è una struttura di dati generata dal compilatore MIDL.
Tipo di gestore UUID e manager EPV
Il tipo di gestore UUID e il gestore EPV determinano la routine di gestione eseguita quando un server riceve una richiesta di chiamata di procedura remota da un client. Per ogni implementazione di un'interfaccia offerta da un server, deve registrare un EPV di gestione separato.

Si noti che quando si specifica un tipo di gestore diverso da zero, l'UUID del server deve anche chiamare RpcObjectSetType per registrare gli oggetti di questo tipo non nil.

Specificando i flag RPC_IF_AUTOLISTEN contrassegna l'interfaccia come interfaccia di ascolto automatico. Il tempo di esecuzione inizia ad ascoltare le chiamate non appena l'interfaccia viene registrata e interrompe l'ascolto quando l'interfaccia non viene registrata. Una chiamata a RpcServerUnregisterIf per questa interfaccia attenderà il completamento di tutte le chiamate in sospeso su questa interfaccia. Le chiamate a RpcServerListen e RpcMgmtStopServerListening non influiranno sull'interfaccia, né una chiamata a RpcServerUnregisterIf con IfSpec == NULL. In questo modo una DLL può registrare le interfacce RPC o rimuoverle dal Registro di sistema senza modificare lo stato RPC dell'applicazione principale.

Se si specifica una funzione di callback di sicurezza, l'applicazione server può limitare l'accesso alle relative interfacce in base al client. Tenere presente che, per impostazione predefinita, la sicurezza è facoltativa; il tempo di esecuzione del server invierà chiamate non protette anche se il server ha chiamato RpcServerRegisterAuthInfo. Se il server vuole accettare solo client autenticati, una funzione di callback dell'interfaccia deve chiamare la funzione RpcBindingInqAuthClient o RpcGetAuthorizationContextForClient per recuperare il livello di sicurezza o tentare di rappresentare il client con RpcImpersonateClient. Può anche specificare il flag RPC_IF_ALLOW_SECURE_ONLY nei flag di interfaccia.

Quando un'applicazione server specifica una funzione di callback di sicurezza per le relative interfacce, il tempo di esecuzione RPC rifiuta automaticamente le chiamate non autenticate a tale interfaccia. Inoltre, il runtime registra le interfacce usate da ogni client. Quando un client effettua una rpc a un'interfaccia che non è stata usata durante la sessione di comunicazione corrente, la libreria di runtime RPC chiamerà la funzione di callback di sicurezza dell'interfaccia. Se si specifica RPC_IF_ALLOW_CALLBACKS_WITH_NO_AUTH flag, si impedisce il rifiuto automatico dei client non autenticati.

Per la firma per la funzione di callback, vedere RPC_IF_CALLBACK_FN.

La funzione di callback deve restituire RPC_S_OK se il client è autorizzato a chiamare i metodi in questa interfaccia. Qualsiasi altro codice restituito causerà la ricezione dell'eccezione RPC_S_ACCESS_DENIED da parte del client.

In alcuni casi, il tempo di esecuzione RPC può chiamare la funzione di callback di sicurezza più volte per ogni interfaccia client. Assicurarsi che la funzione di callback possa gestire questa possibilità.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	rpcdce.h (include Rpc.h)
Libreria	Rpcrt4.lib
DLL	Rpcrt4.dll