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:

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)

Weitere Informationen

/target-Schalter

Bindung und Handles

Handles und Objekte

IDL-Datei (Interface Definition)

DuplicateHandle

Sicherheitsbeschreibungen