system_handle attribute
The [system_handle] attribute specifies a system-defined handle type that represents access to a system object.
[system_handle(system-handle-type[,optional-access-mask])]
Parameters
-
system-handle-type
-
Specifies one of the system handle type options.
The valid options are:
- sh_composition - A DirectComposition surface handle
- sh_event - A named or unnamed event object
- sh_file - A file or I/O device
- sh_job - A job object
- sh_mutex - A named or unnamed mutex object
- sh_pipe - An anonymous or named pipe object
- sh_process - A process object
- sh_reg_key - A registry key
- sh_section - A shared memory section
- sh_semaphore - A named or unnamed semaphore object
- sh_socket - A WinSock socket object
- sh_thread - A thread object
- sh_token - An access token object
-
optional-access-mask
-
Optionally requests specific access rights applied to the duplicated handle. By default when this is unspecified, the handle will be duplicated with the same access.
To specify a different level of access, use object specific access rights corresponding to the underlying system object selected.
More information on how access rights are propagated during duplication can be found on the DuplicateHandle documentation.
Links to lists of access rights for each type of object can be found in the DuplicateHandle reference as well as in the See also headings of each
sh_*parameter page.
Remarks
In order to use this attribute, the -target flag must be set to NT100 (or higher) when running midl.exe.
System handles are handles that are defined by the operating system to provide access to a system resource. The specific type of the object behind the handle must be specified when declaring the attribute.
For a handle marked [in], the handle will be duplicated into the remote procedure and remains valid for the duration of that procedure. On return from the remote procedure, the duplicated handle is freed. To maintain access to the underlying object, the remote application must duplicate the handle into its own address space.
By contrast, for a handle marked [out], when a remote procedure returns a handle from a call, the remote procedure will lose ownership of it. To maintain access to the underlying object, the remote procedure should duplicate the handle and return the duplicate. The returned handle then becomes owned by the caller who assumes a responsibility to close it when access to the underlying system object is no longer necessary.
As this is a mechanism for relaying access to a system object, this attribute is only applicable to calls between procedures on the same machine.
The creation and access parameters given to the underlying object behind the system handle on its creation will dictate whether it can be successfully marshalled to the remote procedure context.
An array of system_handle can be passed either in or out with the syntax found in the size_is attribute documentation.
Examples
The following examples several uses of system_handle. For a complete sample, see the SystemHandlePassing sample.
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);
}
Requirements
| Minimum supported client | Windows 10 Anniversary Update (version 1607, build 14393) |
| Minimum supported server | Windows Server 2016 (build 14393) |