system_handle-Attribut
Das [ ] system_handle-Attribut gibt einen systemdefinierten Handletyp an, der den Zugriff auf ein Systemobjekt darstellt.
[system_handle(system-handle-type[,optional-access-mask])]
Parameter
-
system-handle-type
-
Gibt eine der Optionen des Systemhandpunkttyps an.
Die gültigen Optionen sind:
- sh_composition: Ein DirectComposition-Oberflächenhand handle
- sh_event: Ein benanntes oder unbenannte Ereignisobjekt
- sh_file: Eine Datei oder ein E/A-Gerät
- sh_job: Ein Auftragsobjekt
- sh_mutex: Ein benanntes oder unbenannte Mutex-Objekt
- sh_pipe: Ein anonymes Objekt oder ein Named Pipe-Objekt
- sh_process: Ein Prozessobjekt
- sh_reg_key: Ein Registrierungsschlüssel
- sh_section: Abschnitt "Freigegebener Speicher"
- sh_semaphore: Ein benanntes oder unbenannte Semaphorobjekt
- sh_socket: Ein WinSock-Socketobjekt
- sh_thread: Ein Threadobjekt
- sh_token: Ein Zugriffstokenobjekt
-
optional-access-mask
-
Fordert optional bestimmte Zugriffsrechte an, die auf das duplizierte Handle angewendet werden. Wenn dies nicht angegeben ist, wird das Handle standardmäßig mit demselben Zugriff dupliziert.
Um eine andere Zugriffsebene anzugeben, verwenden Sie objektspezifische Zugriffsrechte, die dem ausgewählten zugrunde liegenden Systemobjekt entspricht.
Weitere Informationen zur Propagierung von Zugriffsrechten während der Duplizierung finden Sie in der DuplicateHandle-Dokumentation.
Links zu Listen mit Zugriffsrechten für jeden Objekttyp finden Sie in der DuplicateHandle-Referenz sowie in den Überschriften der einzelnen
sh_*Parameterseiten.
Hinweise
Um dieses Attribut verwenden zu können, muss das Flag auf (oder höher) festgelegt werden, -target wenn sie NT100 midl.exe.
Systemhandles sind Handles, die vom Betriebssystem definiert werden, um Zugriff auf eine Systemressource zu ermöglichen. Der spezifische Typ des Objekts hinter dem Handle muss beim Deklarieren des Attributs angegeben werden.
Bei einem Handle mit dem Namen wird das Handle in der Remoteprozedur dupliziert und bleibt für die [in] Dauer dieser Prozedur gültig. Bei rückgabe von der Remoteprozedur wird das duplizierte Handle frei. Um den Zugriff auf das zugrunde liegende Objekt zu erhalten, muss die Remoteanwendung das Handle in ihren eigenen Adressraum duplizieren.
Im Gegensatz dazu verliert die Remoteprozedur für ein Handle, das als gekennzeichnet ist, den Besitz, wenn eine Remoteprozedur ein Handle von einem Aufruf [out] zurückgibt. Um den Zugriff auf das zugrunde liegende Objekt zu erhalten, sollte die Remoteprozedur das Handle duplizieren und das Duplikat zurückgeben. Das zurückgegebene Handle gehört dann dem Aufrufer, der die Verantwortung übernimmt, es zu schließen, wenn der Zugriff auf das zugrunde liegende Systemobjekt nicht mehr erforderlich ist.
Da dies ein Mechanismus zum Weiterleiten des Zugriffs auf ein Systemobjekt ist, gilt dieses Attribut nur für Aufrufe zwischen Prozeduren auf demselben Computer.
Die Erstellungs- und Zugriffsparameter, die dem zugrunde liegenden Objekt hinter dem Systemhand handle bei der Erstellung übergeben werden, bestimmen, ob es erfolgreich in den Remoteprozedurkontext marshallt werden kann.
Ein Array von kann entweder in oder mit der Syntax übergeben werden, die in der Dokumentation size_is system_handle Attributs gefunden wird.
Beispiele
In den folgenden Beispielen werden mehrere Verwendungen von system_handle verwendet. Ein vollständiges Beispiel finden Sie im SystemHandlePassing-Beispiel.
interface MyInterface : IUnknown
{
HRESULT Proc1([in, system_handle(sh_file)] HANDLE writeThisFile);
HRESULT Proc2([in, system_handle(sh_pipe, FILE_GENERIC_READ)] HANDLE readThisPipe);
HRESULT Proc3([out, system_handle(sh_composition)] HANDLE* visual);
HRESULT Proc4([in] DWORD cEvents, [out, system_handle(sh_event), size_is(cEvents)] HANDLE* pWatchAllTheseEvents);
}
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 10 Anniversary Update (Version 1607, Build 14393) |
| Unterstützte Mindestversion (Server) | Windows Server 2016 (Build 14393) |