GetSharedServiceDirectory function (winsvc.h)

Article
04/14/2022

Returns a path for a per-service filesystem location for a service and associated programs to read and/or write state to.

Syntax

DWORD GetSharedServiceDirectory(
  SC_HANDLE                     ServiceHandle,
  SERVICE_SHARED_DIRECTORY_TYPE DirectoryType,
  PWCHAR                        PathBuffer,
  DWORD                         PathBufferLength,
  DWORD                         *RequiredBufferLength
);

Parameters

ServiceHandle

A handle to the service. This handle is returned by the OpenService function.

DirectoryType

A member of the SERVICE_SHARED_DIRECTORY_TYPE enumeration that identifies the type of per-service shared directory path to retrieve.

PathBuffer

A caller-allocated buffer into which the path string will be copied. If NULL, the function call will fail with ERROR_INSUFFICIENT_BUFFER and return the required buffer length, in WCHARs, in RequiredBufferLength. If non-NULL, the length of the buffer should be specified in PathBufferLength. The path, if written, will be NULL terminated.

PathBufferLength

The length of the buffer supplied in PathBuffer, in units of WCHARS. This argument is ignored if PathBuffer is NULL.

RequiredBufferLength

This value is set to the required length of the buffer in units of WCHARs. This length includes the terminating NULL character.

Return value

Returns ERROR_SUCCESS when all operations complete successfully and the NULL-terminated state path is written to PathBuffer. Returns ERROR_INSUFFICIENT_BUFFER if PathBuffer was not large enough to contain the state path, or if PathBuffer was NULL. In this case the required buffer length in WCHARs is returned via RequiredBufferLength. If some other failure occurs, a Win32 error code is returned.

Remarks

For ServiceSharedDirectoryPersistentState, the security of the directory is set to only provide write access to the local system account, the service SID, and to local administrators. Ensure service SIDs are enabled for any service that calls this API. For more information, see SERVICE_SID_INFO.

For a similar API that provides service state exclusively for use by the service itself, see GetServiceDirectory.

All service state directories are deleted by the service control manager once the service is uninstalled.

Requirements

Requirement	Value
Minimum supported client	Windows 11 (Build 22000)
Minimum supported server	Windows Server 2022 (Build 20348)
Header	winsvc.h
Library	Onecore.lib