struttura RPC_CALL_ATTRIBUTES_V1_A (rpcasync.h)
La struttura RPC_CALL_ATTRIBUTES_V1 fornisce parametri alla funzione RpcServerInqCallAttributes . Implementata nelle versioni ANSI e UNICODE per i sistemi operativi Windows XP e Windows Server 2003.
Sintassi
typedef struct tagRPC_CALL_ATTRIBUTES_V1_A {
unsigned int Version;
unsigned long Flags;
unsigned long ServerPrincipalNameBufferLength;
unsigned char *ServerPrincipalName;
unsigned long ClientPrincipalNameBufferLength;
unsigned char *ClientPrincipalName;
unsigned long AuthenticationLevel;
unsigned long AuthenticationService;
BOOL NullSession;
} RPC_CALL_ATTRIBUTES_V1_A;
Members
Version
Versione della funzione RpcServerInqCallAttributes usata dall'applicazione chiamante. Vedere la sezione Osservazioni.
Flags
Maschera di bit che specifica flag validi per richiedere RPC_QUERY_SERVER_PRINCIPAL_NAME o RPC_QUERY_CLIENT_PRINCIPAL_NAME. Vedere la sezione Osservazioni.
ServerPrincipalNameBufferLength
Lunghezza di ServerPrincipalName, in byte. Se non è sufficiente, ServerPrincipalName rimane invariato e ServerPrincipalNameBufferLength indica la lunghezza del buffer necessaria, incluso il carattere NULL di terminazione e viene restituito ERROR_MORE_DATA. Se ServerPrincipalNameBufferLength è più lungo del necessario, al momento della restituzione viene impostato sulla lunghezza effettiva utilizzata, in byte, incluso il carattere NULL di terminazione. Vedere la sezione Osservazioni.
Se la sequenza di protocollo non supporta il recupero di un nome dell'entità server, ServerPrincipalNameBufferLength viene impostato su zero in caso di restituzione e il buffer a cui punta ServerPrincipalName non viene modificato. Windows XP: Solo il gruppo di sequenze di protocolli ncacn_* supporta il recupero del nome dell'entità server.
Se il flag RPC_QUERY_SERVER_PRINCIPAL_NAME non viene specificato, ServerPrincipalNameBufferLength viene ignorato. Se ServerPrincipalNameBufferLength è diverso da zero e ServerPrincipalName è NULL, viene restituito ERROR_INVALID_PARAMETER.
ServerPrincipalName
Puntatore al nome dell'entità server, se richiesto in Flag e supportato dalla sequenza di protocollo. Dopo qualsiasi valore restituito diverso da RPC_S_OK o ERROR_MORE_DATA, il contenuto di ServerPrincipalName non è definito e potrebbe essere stato modificato da RPC.
ClientPrincipalNameBufferLength
Lunghezza del buffer a cui punta ClientPrincipalName, in byte. Se non è sufficiente, ClientPrincipalName è invariato e ClientPrincipalNameBufferLength indica la lunghezza del buffer necessaria, incluso il carattere NULL di terminazione, e ERROR_MORE_DATA viene restituito. Se ClientPrincipalNameBufferLength è più lungo del necessario, al momento della restituzione viene impostato sulla lunghezza effettiva utilizzata, in byte, incluso il carattere NULL di terminazione.
Se la sequenza di protocollo non supporta il recupero di un nome dell'entità client, ClientPrincipalNameBufferLength viene impostato su zero in caso di restituzione e il buffer a cui punta ClientPrincipalName non viene modificato. Windows XP: Solo la sequenza di protocollo ncalrpc supporta il recupero del nome dell'entità client.
Se il flag RPC_QUERY_CLIENT_PRINCIPAL_NAME non viene specificato, ClientPrincipalNameBufferLength viene ignorato. Se ClientPrincipalNameBufferLength è diverso da zero e ClientPrincipalName è NULL, viene restituito ERROR_INVALID_PARAMETER.
ClientPrincipalName
Puntatore al nome dell'entità client, se richiesto nel membro Flags e supportato dalla sequenza di protocollo. Dopo qualsiasi valore restituito diverso da RPC_S_OK o ERROR_MORE_DATA, il contenuto di ClientPrincipalName non è definito e potrebbe essere stato modificato da RPC.
AuthenticationLevel
Livello di autenticazione per la chiamata. Vedere Costanti a livello di autenticazione per i livelli di autenticazione supportati da RPC.
AuthenticationService
Servizio di autenticazione, o provider di sicurezza, usato per effettuare la chiamata alla procedura remota.
NullSession
Specifica se viene utilizzata una sessione Null . Zero indica che la chiamata non viene eseguita su una sessione Null ; qualsiasi altro valore indica una sessione Null .
Commenti
La struttura RPC_CALL_ATTRIBUTES usa uno schema di controllo delle versioni per consentire alla funzione RpcServerInqCallAttributes di incorporare nuove funzionalità senza dover introdurre nuove funzioni con identificatori di suffisso. Ad esempio, una seconda versione del RPC_CALL_ATTRIBUTES, identificata con un semplice #define nell'intestazione, può aggiungere nuovi membri per facilitare nuove funzionalità incorporate nelle versioni future della funzione RpcServerInqCallAttributes , senza dover rilasciare una funzione alternativa corrispondente.
Il membro Version indica la versione della struttura RPC_CALL_ATTRIBUTES (attualmente RPC_CALL_ATTRIBUTES_V1 o RPC_CALL_ATTRIBUTES_V2) usata dall'applicazione chiamante. Questa identificazione consente al runtime RPC di garantire la compatibilità con le versioni precedenti per le applicazioni che non usano la versione più recente della struttura.
Se si specifica RPC_QUERY_SERVER_PRINCIPAL_NAME nel membro Flags, rpcServerInqCallAttributes viene restituito il nome dell'entità server in ServerPrincipalName. Se non viene specificato RPC_QUERY_SERVER_PRINCIPAL_NAME, RpcServerInqCallAttributes non modifica il puntatore passato in ServerPrincipalName e non archivia nulla in tale percorso di memoria. Specificando RPC_QUERY_CLIENT_PRINCIPAL_NAME nel membro Flags indica a RpcServerInqCallAttributes di restituire il nome dell'entità client in ClientPrincipalName. Se non viene specificato RPC_QUERY_CLIENT_PRINCIPAL_NAME, RpcServerInqCallAttributes non modifica il puntatore passato in ClientPrincipalName e non archivia nulla in tale percorso di memoria.
Il meccanismo di elaborazione migliore quando vengono recuperati sia i nomi di entità client che server consiste nell'archiviare la lunghezza di ClientPrincipalNameBufferLength e ServerPrincipalNameBufferLength e, se viene restituito ERROR_MORE_DATA, confrontare le lunghezze archiviate con le lunghezze restituite in tali membri. Il membro con un valore archiviato minore o uguale al valore restituito è stato restituito correttamente, a indicare che l'altro membro aveva un buffer insufficiente. Nella chiamata successiva omettere il flag per il nome dell'entità restituito correttamente; In questo modo si evita l'elaborazione associata a un altro recupero e a un'altra copia del nome dell'entità restituita correttamente.
La struttura RPC_CALL_ATTRIBUTES_V1 viene in genere chiamata in due modi:
- Primo approccio: zero viene specificato per il membro ServerPrincipalNameBufferLength o ClientPrincipalNameBufferLength nella prima chiamata di funzione RpcServerInqCallAttributes per recuperare la lunghezza del buffer richiesta oppure per determinare se il protocollo supporta la restituzione del nome dell'entità. Al momento del recupero della lunghezza del buffer necessaria, viene allocato un buffer della lunghezza richiesta e viene effettuata una seconda chiamata per ottenere la lunghezza reale del buffer.
- Secondo approccio: il chiamante inizia con un buffer ragionevole, spesso allocato nello stack e, se viene restituito ERROR_MORE_DATA, viene allocato un buffer della lunghezza richiesta e viene chiamata nuovamente la funzione RpcServerInqCallAttributes .
Esempio
RPC_CALL_ATTRIBUTES CallAttributes; // this maps to RPC_CALL_ATTRIBUTES_V1
memset(&CallAttributes, 0, sizeof(CallAttributes));
CallAttributes.Version = RPC_CALL_ATTRIBUTES_VERSION; // maps to 1
CallAttributes.Flags = ;//....
Status = RpcServerInqCallAttributes(0, &CallAttributes);
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Intestazione | rpcasync.h (include Rpc.h) |