Service Configuration Program Tasks

Opening an SCManager Database

Many operations require an open handle to an SCManager object. The following example demonstrates how to obtain the handle.

Different operations on the SCM database require different levels of access, and you should only request the minimum access required. If SC_MANAGER_ALL_ACCESS is requested, the function fails if the calling process does not have Administrator privileges. The following example shows how to request full access to the ServicesActive database on the local computer.

#include <windows.h>
#include <stdio.h>

SC_HANDLE schSCManager;

// Open a handle to the SC Manager database.

 
schSCManager = OpenSCManager(
    NULL, // local machine

    NULL, // ServicesActive database

    SC_MANAGER_ALL_ACCESS); // full access rights

 
if (NULL == schSCManager)
    printf("OpenSCManager failed (%d)\n", GetLastError());


 

Installing a Service

A service configuration program uses the function to install a service in a SCM database. The following example shows how to install a service. The application-defined schSCManager handle must have SC_MANAGER_CREATE_SERVICE access to the SCManager object. For an example of how to do this, see .

 

#include <windows.h>
#include <stdio.h>

BOOL CreateSampleService()
{
    TCHAR szPath[MAX_PATH];
    
    if( !GetModuleFileName( NULL, szPath, MAX_PATH ) )
    {
        printf("GetModuleFileName failed (%d)\n", GetLastError());
        return FALSE;
    }
 
    schService = CreateService(
        schSCManager, // SCManager database

        TEXT("Sample_Srv"), // name of service

        lpszDisplayName, // service name to display

        SERVICE_ALL_ACCESS, // desired access

        SERVICE_WIN32_OWN_PROCESS, // service type

        SERVICE_DEMAND_START, // start type

        SERVICE_ERROR_NORMAL, // error control type

        szPath, // path to service's binary

        NULL, // no load ordering group

        NULL, // no tag identifier

        NULL, // no dependencies

        NULL, // LocalSystem account

        NULL); // no password

 
    if (schService == NULL)
    {
        printf("CreateService failed (%d)\n", GetLastError());
        return FALSE;
    }
    else
    {
        CloseServiceHandle(schService);
        return TRUE;
    }
}


 

 

Deleting a Service
In the following example, a service configuration program uses the OpenService function to get a handle with DELETE access to an installed service object. The program then uses the service object handle in the DeleteService function to remove the service from the SCM database.



BOOL DeleteSampleService()
{
    schService = OpenService(
        schSCManager, // SCManager database

        TEXT("Sample_Srv"), // name of service

        DELETE); // only need DELETE access

 
    if (schService == NULL)
    {
        printf("OpenService failed (%d)\n", GetLastError());
        return FALSE;
    }
 
    if (! DeleteService(schService) )
    {
        printf("DeleteService failed (%d)\n", GetLastError());
        return FALSE;
    }
    else
        printf("DeleteService succeeded\n");
 
    CloseServiceHandle(schService);
    return TRUE;
}


 

Changing a Service Configuration

In the following example, a service configuration program uses the and functions to change the configuration parameters of an installed service. The program first tries to lock the database, to prevent the SCM from starting a service while it is being reconfigured. If it successfully locks the database, the program opens a handle to the service object, modifies its configuration, unlocks the database, and then closes the service object handle. If the program does not successfully in lock the database, it uses the function to retrieve information about the lock.

#include <windows.h>
#include <stdio.h>

BOOL ReconfigureSampleService(BOOL fDisable, LPSTR lpDesc)
{
    SC_LOCK sclLock;
    LPQUERY_SERVICE_LOCK_STATUS lpqslsBuf;
    SERVICE_DESCRIPTION sdBuf;
    DWORD dwBytesNeeded, dwStartType;
    BOOL bSuccess=TRUE;
 
    // Need to acquire database lock before reconfiguring.

 
    sclLock = LockServiceDatabase(schSCManager);
 
    // If the database cannot be locked, report the details.

 
    if (sclLock == NULL)
    {
        // Exit if the database is not locked by another process.

 
        if (GetLastError() != ERROR_SERVICE_DATABASE_LOCKED)
        {
            printf("Database lock failed (%d)\n", GetLastError());
            return FALSE;
        }
 
        // Allocate a buffer to get details about the lock.

 
        lpqslsBuf = (LPQUERY_SERVICE_LOCK_STATUS) LocalAlloc(
            LPTR, sizeof(QUERY_SERVICE_LOCK_STATUS)+256);
        if (lpqslsBuf == NULL)
        {
            printf("LocalAlloc failed (%d)\n", GetLastError());
            return FALSE;
        }
 
        // Get and print the lock status information.

 
        if (!QueryServiceLockStatus(
            schSCManager,
            lpqslsBuf,
            sizeof(QUERY_SERVICE_LOCK_STATUS)+256,
            &dwBytesNeeded) )
        {
            printf("Query lock status failed (%d)", GetLastError());
            return FALSE;
        }
 
        if (lpqslsBuf->fIsLocked)
            printf("Locked by: %s, duration: %d seconds\n",
                lpqslsBuf->lpLockOwner,
                lpqslsBuf->dwLockDuration);
        else
            printf("No longer locked\n");
 
        LocalFree(lpqslsBuf);
    }
 
    // The database is locked, so it is safe to make changes.

 
    // Open a handle to the service.

 
    schService = OpenService(
        schSCManager, // SCManager database

        "Sample_Srv", // name of service

        SERVICE_CHANGE_CONFIG); // need CHANGE access

    if (schService == NULL)
    {
        printf("OpenService failed (%d)\n", GetLastError());
        return FALSE;
    }

    dwStartType = (fDisable) ? SERVICE_DISABLED :
                            SERVICE_DEMAND_START;
 
    // Make the changes.


    if (! ChangeServiceConfig(
        schService, // handle of service

        SERVICE_NO_CHANGE, // service type: no change

        dwStartType, // change service start type

        SERVICE_NO_CHANGE, // error control: no change

        NULL, // binary path: no change

        NULL, // load order group: no change

        NULL, // tag ID: no change

        NULL, // dependencies: no change

        NULL, // account name: no change

        NULL, // password: no change

        NULL) ) // display name: no change

    {
        printf("ChangeServiceConfig failed (%d)\n", GetLastError());
        bSuccess = FALSE;
    }
    else
        printf("ChangeServiceConfig succeeded.\n");
 
    sdBuf.lpDescription = lpDesc;

    if( !ChangeServiceConfig2(
        schService, // handle to service

        SERVICE_CONFIG_DESCRIPTION, // change: description

        &sdBuf) ) // value: new description

    {
        printf("ChangeServiceConfig2 failed\n");
        bSuccess = FALSE;
    }
    else
        printf("ChangeServiceConfig2 succeeded\n");

    // Release the database lock.

 
    UnlockServiceDatabase(sclLock);
 
    // Close the handle to the service.

 
    CloseServiceHandle(schService);
    return bSuccess;
}


 

 

Querying a Service's Configuration

In the following example, a service configuration program uses the function to get a handle with SERVICE_QUERY_CONFIG access to an installed service object. Then the program uses the service object handle in the function to retrieve the current configuration of the service.

#include 
#include 

BOOL GetSampleServiceConfig() 
{ 
    LPQUERY_SERVICE_CONFIG lpqscBuf; 
    LPSERVICE_DESCRIPTION lpqscBuf2;
    DWORD dwBytesNeeded; 
    BOOL bSuccess=TRUE;
 
    // Open a handle to the service. 
 
    schService = OpenService( 
        schSCManager,           // SCManager database 
        TEXT("Sample_Srv"),     // name of service 
        SERVICE_QUERY_CONFIG);  // need QUERY access 
    if (schService == NULL)
    { 
        printf("OpenService failed (%d)", GetLastError());
        return FALSE;
    }
 
    // Allocate a buffer for the configuration information.
 
    lpqscBuf = (LPQUERY_SERVICE_CONFIG) LocalAlloc( 
        LPTR, 4096); 
    if (lpqscBuf == NULL) 
    {
        return FALSE;
    }
 
    lpqscBuf2 = (LPSERVICE_DESCRIPTION) LocalAlloc( 
        LPTR, 4096); 
    if (lpqscBuf2 == NULL) 
    {
        return FALSE;
    }
 
    // Get the configuration information. 
 
    if (! QueryServiceConfig( 
        schService, 
        lpqscBuf, 
        4096, 
        &dwBytesNeeded) ) 
    {
        printf("QueryServiceConfig failed (%d)", GetLastError());
        bSuccess = FALSE; 
    }
 
    if (! QueryServiceConfig2( 
        schService, 
        SERVICE_CONFIG_DESCRIPTION,
        lpqscBuf2, 
        4096, 
        &dwBytesNeeded) ) 
    {
        printf("QueryServiceConfig2 failed (%d)", GetLastError());
        bSuccess = FALSE;
    }
 
    // Print the configuration information.
 
    printf("\nSample_Srv configuration: \n");
    printf(" Type: 0x%x\n", lpqscBuf->dwServiceType);
    printf(" Start Type: 0x%x\n", lpqscBuf->dwStartType);
    printf(" Error Control: 0x%x\n", lpqscBuf->dwErrorControl);
    printf(" Binary path: %s\n", lpqscBuf->lpBinaryPathName);

    if (lpqscBuf->lpLoadOrderGroup != NULL)
        printf(" Load order group: %s\n", lpqscBuf->lpLoadOrderGroup);
    if (lpqscBuf->dwTagId != 0)
        printf(" Tag ID: %d\n", lpqscBuf->dwTagId);
    if (lpqscBuf->lpDependencies != NULL)
        printf(" Dependencies: %s\n", lpqscBuf->lpDependencies);
    if (lpqscBuf->lpServiceStartName != NULL)
        printf(" Start Name: %s\n", lpqscBuf->lpServiceStartName);
    if (lpqscBuf2->lpDescription != NULL)
        printf(" Description: %s\n", lpqscBuf2->lpDescription);
 
    LocalFree(lpqscBuf); 
    LocalFree(lpqscBuf2); 

    return bSuccess;
}