Skip to content

Latest commit

 

History

History
421 lines (318 loc) · 10.7 KB

WinFsp-API-launch.h.md

File metadata and controls

421 lines (318 loc) · 10.7 KB
Raw

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

FspLaunchCallLauncherPipe - Call launcher pipe. 

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.

FspLaunchCallLauncherPipeEx - Call launcher pipe. 

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

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.

FspLaunchGetInfo - Get information about a service instance. 

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

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

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.

FspLaunchGetNameList - List service instances. 

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

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

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.

FspLaunchStart - Start a service instance. 

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

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.

FspLaunchStartEx - Start a service instance. 

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

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.

FspLaunchStop - Stop a service instance. 

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

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.

SERVICE REGISTRY

Functions

FspLaunchRegFreeRecord - Free a service registry record. 

FSP_API VOID FspLaunchRegFreeRecord( 
    FSP_LAUNCH_REG_RECORD *Record);

Parameters

  • Record - The service record to free.

See Also

  • FspLaunchRegGetRecord
FspLaunchRegGetRecord - Get a service registry record. 

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
FspLaunchRegSetRecord - Add/change/delete a service registry record. 

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.

Typedefs

FSP_LAUNCH_REG_RECORD - Service registry record. 

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

Copyright © 2015-2020 Bill Zissimopoulos
Generated with prettydoc