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)

See also

/target switch

Binding and Handles

Handles and Objects

Interface Definition (IDL) File

DuplicateHandle

Security Descriptors