mirror of
https://github.com/winfsp/winfsp.git
synced 2025-04-22 08:23:05 -05:00
tools: apidoc
doc: launch.h
This commit is contained in:
Bill Zissimopoulos
parent
309827860f
commit
b4f5707e4e
263
doc/launch.h.asciidoc
Normal file
263
doc/launch.h.asciidoc
Normal file
@ -0,0 +1,263 @@
|
||||
= 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;
|
||||
----
|
||||
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
= winfsp/winfsp.h
|
||||
:author: (C) 2015-2017 Bill Zissimopoulos
|
||||
:author: (C) 2015-2018 Bill Zissimopoulos
|
||||
:toc: preamble
|
||||
:toc-title:
|
||||
|
||||
@ -278,6 +278,33 @@ STATUS$$_$$SUCCESS or error code.
|
||||
Note that the FSD will also flush all file/volume caches prior to invoking this operation.
|
||||
|
||||
|
||||
*GetDirInfoByName* - Get directory information for a single file or directory within a parent directory.
|
||||
|
||||
[source,c]
|
||||
----
|
||||
NTSTATUS ( *GetDirInfoByName)(
|
||||
FSP_FILE_SYSTEM *FileSystem,
|
||||
PVOID FileContext,
|
||||
PWSTR FileName,
|
||||
FSP_FSCTL_DIR_INFO *DirInfo);
|
||||
----
|
||||
|
||||
*Parameters*
|
||||
|
||||
- _FileSystem_ - The file system on which this request is posted.
|
||||
- _FileContext_ - The file context of the parent directory.
|
||||
- _FileName_ - The name of the file or directory to get information for. This name is relative
|
||||
to the parent directory and is a single path component.
|
||||
- _DirInfo_ - [out]
|
||||
Pointer to a structure that will receive the directory information on successful
|
||||
return from this call. This information includes the file name, but also file
|
||||
attributes, file times, etc.
|
||||
|
||||
*Return Value*
|
||||
|
||||
STATUS$$_$$SUCCESS or error code.
|
||||
|
||||
|
||||
*GetFileInfo* - Get file or directory information.
|
||||
|
||||
[source,c]
|
||||
@ -1185,6 +1212,19 @@ The current operation context is stored in thread local storage. It allows acces
|
||||
Request and Response associated with this operation.
|
||||
|
||||
|
||||
*FspFileSystemOperationProcessId* - Gets the originating process ID.
|
||||
|
||||
[source,c]
|
||||
----
|
||||
static inline UINT32 FspFileSystemOperationProcessId(
|
||||
VOID)
|
||||
----
|
||||
|
||||
*Discussion*
|
||||
|
||||
Valid only during Create, Open and Rename requests when the target exists.
|
||||
|
||||
|
||||
*FspFileSystemPreflight* - Check whether creating a file system object is possible.
|
||||
|
||||
[source,c]
|
||||
@ -1535,6 +1575,27 @@ call. The WinFsp Launcher is a Windows service that can be configured to launch
|
||||
multiple instances of a user mode file system.
|
||||
|
||||
|
||||
*FspServiceContextCheck* - Check if the supplied token is from the service context.
|
||||
|
||||
[source,c]
|
||||
----
|
||||
FSP_API NTSTATUS FspServiceContextCheck(
|
||||
HANDLE Token,
|
||||
PBOOLEAN PIsLocalSystem);
|
||||
----
|
||||
|
||||
*Parameters*
|
||||
|
||||
- _Token_ - Token to check. Pass NULL to check the current process token.
|
||||
- _PIsLocalSystem_ - Pointer to a boolean that will receive a TRUE value if the token belongs to LocalSystem
|
||||
and FALSE otherwise. May be NULL.
|
||||
|
||||
*Return Value*
|
||||
|
||||
STATUS$$_$$SUCCESS if the token is from the service context. STATUS$$_$$ACCESS$$_$$DENIED if it is not.
|
||||
Other error codes are possible.
|
||||
|
||||
|
||||
*FspServiceCreate* - Create a service object.
|
||||
|
||||
[source,c]
|
||||
|
||||
12
tools/gendoc/apidoc.sh
Normal file
12
tools/gendoc/apidoc.sh
Normal file
@ -0,0 +1,12 @@
|
||||
#!/bin/bash
|
||||
|
||||
cd $(dirname "$0")/../..
|
||||
|
||||
PRETTYDOC="$PWD/../prettydoc/prettydoc"
|
||||
|
||||
if [[ $# -eq 0 ]]; then
|
||||
echo "usage: $(basename $0) {asciidoc|html}" 1>&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
"$PRETTYDOC" -f $1 -t -H=--outer-names-only -o doc inc/winfsp/winfsp.h inc/winfsp/launch.h
|
||||
Loading…
x
Reference in New Issue
Block a user