mirror of
https://github.com/winfsp/winfsp.git
synced 2025-11-02 12:09:15 -06:00
264 lines
7.2 KiB
Plaintext
264 lines
7.2 KiB
Plaintext
= winfsp/launch.h
|
|
:author: (C) 2015-2018 Bill Zissimopoulos
|
|
:toc: preamble
|
|
:toc-title:
|
|
|
|
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.
|
|
|
|
[source,c]
|
|
----
|
|
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.
|
|
|
|
|
|
*FspLaunchGetInfo* - Get information about a service instance.
|
|
|
|
[source,c]
|
|
----
|
|
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.
|
|
|
|
[source,c]
|
|
----
|
|
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.
|
|
|
|
[source,c]
|
|
----
|
|
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.
|
|
|
|
|
|
*FspLaunchStop* - Stop a service instance.
|
|
|
|
[source,c]
|
|
----
|
|
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.
|
|
|
|
[source,c]
|
|
----
|
|
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.
|
|
|
|
[source,c]
|
|
----
|
|
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.
|
|
|
|
[source,c]
|
|
----
|
|
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.
|
|
|
|
[source,c]
|
|
----
|
|
typedef struct _FSP_LAUNCH_REG_RECORD {
|
|
PWSTR Agent;
|
|
PWSTR Executable;
|
|
PWSTR CommandLine;
|
|
PWSTR WorkDirectory;
|
|
PWSTR RunAs;
|
|
PWSTR Security;
|
|
PVOID Reserved0[6];
|
|
ULONG JobControl;
|
|
ULONG Credentials;
|
|
ULONG Reserved1[6];
|
|
UINT8 Buffer[];
|
|
} FSP_LAUNCH_REG_RECORD;
|
|
----
|
|
|
|
|
|
|