RegisterAppInstance function (smbclnt.h)

Article
10/13/2021

Registers the AppInstance ID for a process.

Syntax

DWORD RegisterAppInstance(
  [in] HANDLE ProcessHandle,
  [in] GUID   *AppInstanceId,
  [in] BOOL   ChildrenInheritAppInstance
);

Parameters

[in] ProcessHandle

A process handle for the current process or a remote process to be tagged with the AppInstanceId. To tag a remote process, the handle must have PROCESS_TERMINATE access to that process.

[in] AppInstanceId

The application instance ID, which is a GUID.

[in] ChildrenInheritAppInstance

TRUE to tag the child processes spawned by the process specified by ProcessHandle; otherwise, FALSE.

Return value

Return code	Description
ERROR_NOT_ENOUGH_MEMORY	The CCF Filter failed to allocate the proper cache objects to fulfill this operation.
ERROR_ACCESS_DENIED	The current process that's trying to tag the process specified by ProcessHandle doesn't have PROCESS_TERMINATE access to that process.
ERROR_INVALID_PARAMETER	ProcessHandle is not a handle to a process.
ERROR_NOT_FOUND	The CCF mini-filter is not found.
ERROR_OBJECT_ALREADY_EXISTS	Another AppInstanceGUID is provided for the same process, which means that the RegisterAppInstance function was called twice or the application was registered twice.

Remarks

The RegisterAppInstance function issues an IOCTL_CCF_REGISTER_APPINSTANCE call to the CCF mini-filter. The function passes the AppInstance GUID, the process handle, and the tagged child processes to the CCF cache that maps the process handle to the AppInstanceId.

The issued IOCTL for tagging another process checks if the current process has PROCESS_TERMINATE access to the target process.

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows Server 2012
Target Platform	Windows
Header	smbclnt.h
Library	NTLanMan.lib
DLL	NTLanMan.dll