winfsp/launch.h

WinFsp Launch API.

In order to use the WinFsp Launch API a program must include <winfsp/launch.h> and link with the winfsp_x64.dll (or winfsp_x86.dll) library.

LAUNCH CONTROL

Functions

<details> <summary> FspLaunchCallLauncherPipe - Call launcher pipe. </summary> <blockquote>

FSP_API NTSTATUS FspLaunchCallLauncherPipe( 
    WCHAR Command,
    ULONG Argc,
    PWSTR *Argv,
    ULONG *Argl, 
    PWSTR Buffer,
    PULONG PSize, 
    PULONG PLauncherError);

Parameters

Command - Launcher command to send. For example, the 'L' launcher command instructs the launcher to list all running service instances.
Argc - Command argument count. May be 0.
Argv - Command argument array. May be NULL.
Argl - Command argument length array. May be NULL. If this is NULL all command arguments are assumed to be NULL-terminated strings. It is also possible for specific arguments to be NULL-terminated; in this case pass -1 in the corresponding Argl position.
Buffer - Buffer that receives the command response. May be NULL.
PSize - Pointer to a ULONG. On input it contains the size of the Buffer. On output it contains the number of bytes transferred. May be NULL.
PLauncherError - Receives the launcher error if any. This is always a Win32 error code. May not be NULL.

Return Value

STATUS_SUCCESS if the command is sent successfully to the launcher, even if the launcher returns an error. Other status codes indicate a communication error. Launcher errors are reported through PLauncherError.

Discussion

This function is used to send a command to the launcher and receive a response.

</blockquote> </details> <details> <summary> FspLaunchCallLauncherPipeEx - Call launcher pipe. </summary> <blockquote>

FSP_API NTSTATUS FspLaunchCallLauncherPipeEx( 
    WCHAR Command,
    ULONG Argc,
    PWSTR *Argv,
    ULONG *Argl, 
    PWSTR Buffer,
    PULONG PSize, 
    BOOLEAN AllowImpersonation, 
    PULONG PLauncherError);

Parameters

Command - Launcher command to send. For example, the 'L' launcher command instructs the launcher to list all running service instances.
Argc - Command argument count. May be 0.
Argv - Command argument array. May be NULL.
Argl - Command argument length array. May be NULL. If this is NULL all command arguments are assumed to be NULL-terminated strings. It is also possible for specific arguments to be NULL-terminated; in this case pass -1 in the corresponding Argl position.
Buffer - Buffer that receives the command response. May be NULL.
PSize - Pointer to a ULONG. On input it contains the size of the Buffer. On output it contains the number of bytes transferred. May be NULL.
AllowImpersonation - Allow caller to be impersonated by launcher.
PLauncherError - Receives the launcher error if any. This is always a Win32 error code. May not be NULL.

Return Value

Discussion

This function is used to send a command to the launcher and receive a response.

</blockquote> </details> <details> <summary> FspLaunchGetInfo - Get information about a service instance. </summary> <blockquote>

FSP_API NTSTATUS FspLaunchGetInfo( 
    PWSTR ClassName,
    PWSTR InstanceName, 
    PWSTR Buffer,
    PULONG PSize, 
    PULONG PLauncherError);

Parameters

ClassName - Class name of the service instance to stop.
InstanceName - Instance name of the service instance to stop.
Buffer - Buffer that receives the command response. May be NULL.
PSize - Pointer to a ULONG. On input it contains the size of the Buffer. On output it contains the number of bytes transferred. May be NULL.
PLauncherError - Receives the launcher error if any. This is always a Win32 error code. May not be NULL.

Return Value

Discussion

The information is a list of NULL-terminated strings: the class name of the service instance, the instance name of the service instance and the full command line used to start the service instance.

</blockquote> </details> <details> <summary> FspLaunchGetNameList - List service instances. </summary> <blockquote>

FSP_API NTSTATUS FspLaunchGetNameList( 
    PWSTR Buffer,
    PULONG PSize, 
    PULONG PLauncherError);

Parameters

Buffer - Buffer that receives the command response. May be NULL.
PSize - Pointer to a ULONG. On input it contains the size of the Buffer. On output it contains the number of bytes transferred. May be NULL.
PLauncherError - Receives the launcher error if any. This is always a Win32 error code. May not be NULL.

Return Value

Discussion

The information is a list of pairs of NULL-terminated strings. Each pair contains the class name and instance name of a service instance. All currently running service instances are listed.

</blockquote> </details> <details> <summary> FspLaunchStart - Start a service instance. </summary> <blockquote>

FSP_API NTSTATUS FspLaunchStart( 
    PWSTR ClassName,
    PWSTR InstanceName,
    ULONG Argc,
    PWSTR *Argv, 
    BOOLEAN HasSecret, 
    PULONG PLauncherError);

Parameters

ClassName - Class name of the service instance to start.
InstanceName - Instance name of the service instance to start.
Argc - Service instance argument count. May be 0.
Argv - Service instance argument array. May be NULL.
HasSecret - Whether the last argument in Argv is assumed to be a secret (e.g. password) or not. Secrets are passed to service instances through standard input rather than the command line.
PLauncherError - Receives the launcher error if any. This is always a Win32 error code. May not be NULL.

Return Value

</blockquote> </details> <details> <summary> FspLaunchStartEx - Start a service instance. </summary> <blockquote>

FSP_API NTSTATUS FspLaunchStartEx( 
    PWSTR ClassName,
    PWSTR InstanceName,
    ULONG Argc,
    PWSTR *Argv, 
    BOOLEAN HasSecret, 
    BOOLEAN AllowImpersonation, 
    PULONG PLauncherError);

Parameters

ClassName - Class name of the service instance to start.
InstanceName - Instance name of the service instance to start.
Argc - Service instance argument count. May be 0.
Argv - Service instance argument array. May be NULL.
HasSecret - Whether the last argument in Argv is assumed to be a secret (e.g. password) or not. Secrets are passed to service instances through standard input rather than the command line.
AllowImpersonation - Allow caller to be impersonated by launcher.
PLauncherError - Receives the launcher error if any. This is always a Win32 error code. May not be NULL.

Return Value

</blockquote> </details> <details> <summary> FspLaunchStop - Stop a service instance. </summary> <blockquote>

FSP_API NTSTATUS FspLaunchStop( 
    PWSTR ClassName,
    PWSTR InstanceName, 
    PULONG PLauncherError);

Parameters

ClassName - Class name of the service instance to stop.
InstanceName - Instance name of the service instance to stop.
PLauncherError - Receives the launcher error if any. This is always a Win32 error code. May not be NULL.

Return Value

</blockquote> </details>

SERVICE REGISTRY

Functions

<details> <summary> FspLaunchRegFreeRecord - Free a service registry record. </summary> <blockquote>

FSP_API VOID FspLaunchRegFreeRecord( 
    FSP_LAUNCH_REG_RECORD *Record);

Parameters

Record - The service record to free.

See Also

FspLaunchRegGetRecord

</blockquote> </details> <details> <summary> FspLaunchRegGetRecord - Get a service registry record. </summary> <blockquote>

FSP_API NTSTATUS FspLaunchRegGetRecord( 
    PWSTR ClassName,
    PWSTR Agent, 
    FSP_LAUNCH_REG_RECORD **PRecord);

Parameters

ClassName - The service class name.
Agent - The name of the agent that is retrieving the service record. This API matches the supplied Agent against the Agent in the service record and it only returns the record if they match. Pass NULL to match any Agent.
PRecord - Pointer to a record pointer. Memory for the service record will be allocated and a pointer to it will be stored at this address. This memory must be later freed using FspLaunchRegFreeRecord.

Return Value

STATUS_SUCCESS or error code.

See Also

FspLaunchRegFreeRecord

</blockquote> </details> <details> <summary> FspLaunchRegSetRecord - Add/change/delete a service registry record. </summary> <blockquote>

FSP_API NTSTATUS FspLaunchRegSetRecord( 
    PWSTR ClassName, 
    const FSP_LAUNCH_REG_RECORD *Record);

Parameters

ClassName - The service class name.
Record - The record to set in the registry. If NULL, the registry record is deleted.

Return Value

STATUS_SUCCESS or error code.

</blockquote> </details>

Typedefs

<details> <summary> FSP_LAUNCH_REG_RECORD - Service registry record. </summary> <blockquote>

typedef struct _FSP_LAUNCH_REG_RECORD { 
    PWSTR Agent; 
    PWSTR Executable; 
    PWSTR CommandLine; 
    PWSTR WorkDirectory; 
    PWSTR RunAs; 
    PWSTR Security; 
    PWSTR AuthPackage; 
    PWSTR Stderr; 
    PVOID Reserved0[4]; 
    ULONG JobControl; 
    ULONG Credentials; 
    ULONG AuthPackageId; 
    ULONG Recovery; 
    ULONG Reserved1[4]; 
    UINT8 Buffer[]; 
} FSP_LAUNCH_REG_RECORD;

Generated with <a href="https://github.com/billziss-gh/prettydoc">prettydoc</a>