diff --git a/doc/launch.h.asciidoc b/doc/launch.h.asciidoc new file mode 100644 index 00000000..f876106a --- /dev/null +++ b/doc/launch.h.asciidoc @@ -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 +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; +---- + + + diff --git a/doc/winfsp.h.asciidoc b/doc/winfsp.h.asciidoc index 1a397751..2fae605a 100644 --- a/doc/winfsp.h.asciidoc +++ b/doc/winfsp.h.asciidoc @@ -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] diff --git a/tools/gendoc/apidoc.sh b/tools/gendoc/apidoc.sh new file mode 100644 index 00000000..0b4b4dbe --- /dev/null +++ b/tools/gendoc/apidoc.sh @@ -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 diff --git a/tools/fix-source-copyright b/tools/gensrc/fix-source-copyright similarity index 100% rename from tools/fix-source-copyright rename to tools/gensrc/fix-source-copyright