Funzione RpcServerRegisterIf2 (rpcdce.h)

Articolo
03/01/2024

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

Sintassi

RPC_STATUS RpcServerRegisterIf2(
  RPC_IF_HANDLE      IfSpec,
  UUID               *MgrTypeUuid,
  RPC_MGR_EPV        *MgrEpv,
  unsigned int       Flags,
  unsigned int       MaxCalls,
  unsigned int       MaxRpcSize,
  RPC_IF_CALLBACK_FN *IfCallbackFn
);

Parametri

IfSpec

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

MgrTypeUuid

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

MgrEpv

Vettore del punto di ingresso (EPV) della 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 di valori di flag, vedere Flag di registrazione interfaccia.

MaxCalls

Numero massimo di richieste di chiamata alla procedura remota simultanee che il server può accettare in un'interfaccia di ascolto automatico . Il parametro MaxCalls è applicabile solo in un'interfaccia di ascolto automatico e viene ignorato nelle interfacce che non sono in ascolto automatico. La libreria di runtime RPC rende il suo miglior sforzo per garantire che il server non consenta 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 protocolli.

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 consente di applicare una restrizione non necessaria.

MaxRpcSize

Dimensioni massime dei blocchi di dati in ingresso, in byte. Questo parametro può essere usato per impedire attacchi denial-of-service dannosi. Se il blocco dati di una chiamata di routine remota è maggiore di MaxRpcSize, la libreria di runtime RPC rifiuta la chiamata e invia un errore di RPC_S_ACCESS_DENIED al client. Specificando un valore di (senza segno int) -1 per questo parametro rimuove il limite per le dimensioni dei blocchi di dati in ingresso. Questo parametro non ha alcun effetto sulle chiamate effettuate sul protocollo ncalrpc .

IfCallbackFn

Funzione di callback di sicurezza o NULL per nessun callback. Ogni interfaccia registrata può avere una funzione di callback diversa. Vedere la sezione Osservazioni.

Valore restituito

Restituisce RPC_S_OK al termine dell'esito positivo.

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

Commenti

I parametri e gli effetti della funzione RpcServerRegisterIf2 estendono quelli della funzione 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 RpcServerRegisterIf2 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 gestione UUID e gestione EPV
Il tipo di gestione 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 UUID non nil, il server deve chiamare anche RpcObjectSetType per registrare gli oggetti di questo tipo non nil.

Specificando i flag di 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 arresta l'ascolto quando l'interfaccia viene annullata. Una chiamata a RpcServerUnregisterIf per questa interfaccia attende il completamento di tutte le chiamate in sospeso su questa interfaccia. Le chiamate alle funzioni RpcServerListen e RpcMgmtStopServerListening non influiscono sull'interfaccia, né esegue una chiamata alla funzione RpcServerUnregisterIf con IfSpec impostata sul valore NULL. Ciò consente a una DLL di registrare 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 consente all'applicazione server di limitare l'accesso alle interfacce in base a un singolo client. Per impostazione predefinita, la sicurezza è facoltativa; il server run-time invierà chiamate non protette anche se il server ha chiamato la funzione RpcServerRegisterAuthInfo . Se il server vuole accettare solo client autenticati, una funzione di callback dell'interfaccia deve chiamare la funzione RpcBindingInqAuthClient, RpcGetAuthorizationContextForClient o RpcServerInqCallAttributes per recuperare il livello di sicurezza o tentare di rappresentare il client con la funzione RpcImpersonateClient . Può anche specificare il flag RPC_IF_ALLOW_SECURE_ONLY nei flag di interfaccia per rifiutare chiamate non autenticate.

Quando un'applicazione server specifica una funzione di callback di sicurezza per le relative interfacce, il tempo di esecuzione RPC rifiuta automaticamente le chiamate senza informazioni di autenticazione a tale interfaccia. Inoltre, l'esecuzione registra le interfacce usate da ogni client. Quando un client esegue un'interfaccia RPC a un'interfaccia non usata durante la sessione di comunicazione corrente, la libreria di runtime RPC chiama la funzione di callback della sicurezza dell'interfaccia. Se si specifica RPC_IF_ALLOW_CALLBACKS_WITH_NO_AUTH flag, verrà impedito il rifiuto automatico dei client non autenticati. Si noti che le chiamate nella sessione di sicurezza NULL possono avere informazioni di autenticazione, anche se provengono da client anonimi. Pertanto l'esistenza di un callback da solo non è sufficiente per impedire la connessione dei client anonimi. La funzione di callback di sicurezza deve verificarla oppure è necessario usare il flag di RPC_IF_ALLOW_SECURE_ONLY. RPC_IF_ALLOW_SECURE_ONLY rifiuta le chiamate di sessione Null solo in Windows XP e versioni successive di Windows.

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à che il client riceva l'eccezione RPC_S_ACCESS_DENIED.

In alcuni casi, l'ora di esecuzione RPC può chiamare la funzione di callback di sicurezza più di una volta per client, per interfaccia. Assicurarsi che la funzione di callback possa gestire questa possibilità.

Requisiti

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