| Previous | Main | Next | Site Index | Download | Disclaimer | Privacy |

---

 

 

 

 

 

 

MORE WINDOWS SERVICES: A SUPPLEMENTARY NOTE

 

 

 

 

 

 

 

 

Windows Service: Functions used in program examples of Windows Services 1 and Windows Services 2 wherever applicable. To learn about function you can jump to C & C++ function tutorials.   The Index: QueryServiceStatus() QueryServiceStatusEx() GetTickCount() EnumDependentServices() HeapAlloc() HeapFree() GetProcessHeap() ControlService()     QueryServiceStatus()   Item Description Function QueryServiceStatus(). Use Retrieves the current status of the specified service. This function has been superseded by the QueryServiceStatusEx() function. QueryServiceStatusEx() returns the same information QueryServiceStatus() returns, with the addition of the process identifier and additional information for the service. Prototype BOOL QueryServiceStatus(SC_HANDLE  hService, LPSERVICE_STATUS  lpServiceStatus); Parameters hService - [in] Handle to the service. This handle is returned by the OpenService() or the CreateService() function, and it must have the SERVICE_QUERY_STATUS access right. lpServiceStatus - [out] Pointer to a SERVICE_STATUS structure that receives the status information. Return value If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). The following error codes can be set by the service control manager. Other error codes can be set by the registry functions that are called by the service control manager. ERROR_ACCESS_DENIED - The handle does not have the SERVICE_QUERY_STATUS access right. ERROR_INVALID_HANDLE - The handle is invalid. Include file <windows.h> Remark The QueryServiceStatus() function returns the most recent service status information reported to the service control manager. If the service just changed its status, it may not have updated the service control manager yet. Applications can find out the current service status by interrogating the service directly using the ControlService() function with the SERVICE_CONTROL_INTERROGATE control code.   Table 1.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

QueryServiceStatusEx()

 

 

Return Values

 

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). The following errors can be returned.

 

 

GetTickCount()

 

 

Example Code

 

The following example demonstrates how to use this function to wait for a time interval to pass. Due to the nature of unsigned arithmetic, this code works correctly if the return value wraps one time. If the difference between the two calls to GetTickCount() is more than 49.7 days, the return value could wrap more than one time and this code will not work; use the system time instead.

DWORD dwStart = GetTickCount();

// Stop if this has taken too long

if (GetTickCount() - dwStart >= TIMELIMIT)

    Cancel();

Note that TIMELIMIT is defined as the time interval of interest to the application, in milliseconds.

 

EnumDependentServices()

 

 

Parameters

 

hService - [in] Handle to the service. This handle is returned by the OpenService() or CreateService() function, and it must have the SERVICE_ENUMERATE_DEPENDENTS access right.

dwServiceState - [in] Services to enumerate based on their state. This parameter can be one of the following values.

 

 

lpServices - [out] Pointer to an array of ENUM_SERVICE_STATUS structures that receives the name and service status information for each dependent service in the database. The buffer must be large enough to hold the structures, plus the strings to which their members point. The order of the services in this array is the reverse of the start order of the services. In other words, the first service in the array is the one that would be started last, and the last service in the array is the one that would be started first. The maximum size of this array is 64,000 bytes. To determine the required size, specify NULL for this parameter and 0 for the cbBufSize parameter. The function will fail and GetLastError() will return ERROR_MORE_DATA. The pcbBytesNeeded parameter will receive the required size. cbBufSize - [in] Size of the buffer pointed to by the lpServices parameter, in bytes. pcbBytesNeeded - [out] Pointer to a variable that receives the number of bytes needed to store the array of service entries. The variable only receives this value if the buffer pointed to by lpServices is too small, indicated by function failure and the ERROR_MORE_DATA error; otherwise, the contents of pcbBytesNeeded are undefined. lpServicesReturned - [out] Pointer to a variable that receives the number of service entries returned.

 

Return Values

 

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

 

 

HeapAlloc()

 

 

Parameters

 

hHeap - [in] Handle to the heap from which the memory will be allocated. This handle is returned by the HeapCreate() or GetProcessHeap() function.

dwFlags - [in] Heap allocation control. Specifying any of these values will override the corresponding value specified when the heap was created with HeapCreate(). This parameter can be one or more of the following values.

 

 

dwBytes - [in] Number of bytes to be allocated. If the heap specified by the hHeap parameter is a "non-growable" heap, dwBytes must be less than 0x7FFF8. You create a non-growable heap by calling the HeapCreate() function with a nonzero value.

 

Return Values

 

If the function succeeds, the return value is a pointer to the allocated memory block. If the function fails and you have not specified HEAP_GENERATE_EXCEPTIONS, the return value is NULL. If the function fails and you have specified HEAP_GENERATE_EXCEPTIONS, the function may generate the following exceptions.

 

 

Note:  Heap corruption can lead to either exception. It depends upon the nature of the heap corruption.

If the function fails, it does not call SetLastError(). An application cannot call GetLastError() for extended error information.

 

Some Remarks

 

If HeapAlloc() succeeds, it allocates at least the amount of memory requested. To determine the actual size of the allocated block, use the HeapSize() function. To free a block of memory allocated by HeapAlloc(), use the HeapFree() function. Memory allocated by HeapAlloc() is not movable. The address returned by HeapAlloc() is valid until the memory block is freed or reallocated; the memory block does not need to be locked. Because the system cannot compact a private heap, it can become fragmented. Applications that allocate large amounts of memory in various allocation sizes can use the low-fragmentation heap to reduce heap fragmentation. Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap. There is a small performance cost to serialization, but it must be used whenever multiple threads allocate and free memory from the same heap. Setting the HEAP_NO_SERIALIZE value eliminates mutual exclusion on the heap. Without serialization, two or more threads that use the same heap handle might attempt to allocate or free memory simultaneously, likely causing corruption in the heap. The HEAP_NO_SERIALIZE value can, therefore, be safely used only in the following situations:

1. The process has only one thread.

2. The process has multiple threads, but only one thread calls the heap functions for a specific heap.

3. The process has multiple threads, and the application provides its own mechanism for mutual exclusion to a specific heap.

 

Windows Me/98/95:  The heap managers are designed for memory blocks smaller than four megabytes. If you expect your memory blocks to be larger than one or two megabytes, you can avoid significant performance degradation by using the VirtualAlloc() or VirtualAllocEx() function instead.

 

HeapFree()

 

 

Parameters

 

hHeap - [in] Handle to the heap whose memory block is to be freed. This handle is a returned by either the HeapCreate() or GetProcessHeap() function.

dwFlags - [in] Heap free options. Specifying the following value overrides the corresponding value specified in the flOptions parameter when the heap was created by using the HeapCreate() function.

 

 

lpMem - [in] Pointer to the memory block to be freed. This pointer is returned by the HeapAlloc() or HeapReAlloc() function.

 

Some Remarks

 

You should not refer in any way to memory that has been freed by HeapFree(). After that memory is freed, any information that may have been in it is gone forever. If you require information, do not free memory containing the information. Function calls that return information about memory (such as HeapSize()) may not be used with freed memory, as they may return bogus data. Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap. There is a small performance cost to serialization, but it must be used whenever multiple threads allocate and free memory from the same heap. Setting the HEAP_NO_SERIALIZE value eliminates mutual exclusion on the heap. Without serialization, two or more threads that use the same heap handle might attempt to allocate or free memory simultaneously, likely causing corruption in the heap. The HEAP_NO_SERIALIZE value can, therefore, be safely used only in the following situations:

1. The process has only one thread.

2. The process has multiple threads, but only one thread calls the heap functions for a specific heap.

3. The process has multiple threads, and the application provides its own mechanism for mutual exclusion to a specific heap.

 

GetProcessHeap()

 

 

ControlService()

 

 

Parameters

 

hService - [in] Handle to the service. This handle is returned by the OpenService() or CreateService() function. The access rights required for this handle depend on the dwControl code requested.

dwControl - [in] This parameter can be one of the following control codes.

 

 

This value can also be a user-defined control code, as described in the following table.

 

 

lpServiceStatus - [out] Pointer to a SERVICE_STATUS structure that receives the latest service status information. The information returned reflects the most recent status that the service reported to the service control manager. The service control manager fills in the structure only when ControlService() returns one of the following error codes: NO_ERROR, ERROR_INVALID_SERVICE_CONTROL, ERROR_SERVICE_CANNOT_ACCEPT_CTRL, or ERROR_SERVICE_NOT_ACTIVE. Otherwise, the structure is not filled in.

 

Return Values

 

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). The following error codes can be set by the service control manager. Other error codes can be set by the registry functions that are called by the service control manager.

 

 

Some Remarks

 

The ControlService() function asks the Service Control Manager (SCM) to send the requested control code to the service. The SCM sends the code if the service has specified that it will accept the code, and is in a state in which a control code can be sent to it. The SCM processes service control notifications in a serial fashion, it will wait for one service to complete processing a service control notification before sending the next one. Because of this, a call to ControlService() will block for 30 seconds if any service is busy handling a control code. If the busy service still has not returned from its handler function when the timeout expires, ControlService() fails with ERROR_SERVICE_REQUEST_TIMEOUT. To stop and start a service requires a security descriptor that allows you to do so. The default security descriptor allows the LocalSystem account, and members of the Administrators and Power Users groups to stop and start services. The QueryServiceStatus() or function returns a SERVICE_STATUS structure whose dwCurrentState and dwControlsAccepted members indicate the current state and controls accepted by a running service. All running services accept the SERVICE_CONTROL_INTERROGATE control code by default. Drivers do not accept control codes other than SERVICE_CONTROL_STOP and SERVICE_CONTROL_INTERROGATE. Each service specifies the other control codes that it accepts when it calls the SetServiceStatus() function to report its status. A service should always accept these codes when it is running, no matter what it is doing. The following table shows the action of the SCM in each of the possible service states.

 

 

 

----------------------------------------End Part 4/4----------------------------------------

 

Further reading and digging:

 

1. Microsoft Visual C++, on line MSDN.

2. Structure, enum, union and typedef story can be found at C enum, typedef, define etc..

3. For Multi bytes, Unicode characters and Localization please refer to Unicode & Multi-byte 1 (Story) and Unicode & Multi byte 2 (Implementation).

4. Windows data type information is in Windows data type.

5. Check the best selling C / C++ and Windows books at Amazon.com.

 

 

 

 

| Previous | Main | Next | Site Index | Download | Disclaimer | Privacy |

---