service.h

windows ce 程序设计书 的源代码

//
// Copyright (c) Microsoft Corporation.  All rights reserved.
//
//
// Use of this source code is subject to the terms of the Microsoft end-user
// license agreement (EULA) under which you licensed this SOFTWARE PRODUCT.
// If you did not accept the terms of the EULA, you are not authorized to use
// this source code. For a copy of the EULA, please see the LICENSE.RTF on your
// install media.
//
/*++
THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE.

Module Name:  

service.h

Abstract:  
	Defines programming model for Windows CE Services
	
Notes: 


--*/
#if ! defined (__service_H__)
#define __service_H__		1

#include <winioctl.h>

//
//	Return codes
//
#define SERVICE_SUCCESS				0

//
//	Service states
//
#define SERVICE_STATE_OFF           0
#define SERVICE_STATE_ON            1
#define SERVICE_STATE_STARTING_UP   2
#define SERVICE_STATE_SHUTTING_DOWN 3
#define SERVICE_STATE_UNLOADING     4
#define SERVICE_STATE_UNINITIALIZED 5
#define SERVICE_STATE_UNKNOWN       0xffffffff

//
// Service startup state (value passed on xxx_Init())
//
#define SERVICE_INIT_STARTED	0x00000000
// Service is a super-service, should not spin its own accept() threads.
#define SERVICE_INIT_STOPPED	0x00000001
// Service is being run in an isolated services.exe.  Interprocess communication 
// via IOCTLs or streaming interface is not supported in this configuration.
#define SERVICE_INIT_STANDALONE 0x00000002

// 
// Service may need to know whether it was called from device.exe or services.exe or elsewhere.
//
#define SERVICE_CALLER_PROCESS_SERVICES_EXE      1
#define SERVICE_CALLER_PROCESS_DEVICE_EXE        2
#define	SERVICE_CALLER_PROCESS_OTHER_EXE         100

#define SERVICE_SERVICES_EXE_PROCNAME            L"services.exe"
#define SERVICE_DEVICE_EXE_PROCNAME              L"device.exe"


typedef struct _ServiceEnumInfo {
	WCHAR   szPrefix[6];     
	WCHAR   *szDllName;
	HANDLE  hServiceHandle;
	DWORD   dwServiceState;   // one of SERVICE_STATE_XXX values above.
} ServiceEnumInfo;

// Called from service on initialization to determine where it's running from
#define SERVICE_FIND_CALLER(callerProc) { \
		WCHAR szCallerModName[MAX_PATH]; \
		if (GetModuleFileName((HINSTANCE)GetCurrentProcess(),szCallerModName,sizeof(szCallerModName)/sizeof(WCHAR)))  { \
			if (wcsstr(szCallerModName,SERVICE_DEVICE_EXE_PROCNAME))  { \
				(callerProc) = SERVICE_CALLER_PROCESS_DEVICE_EXE; \
			} \
			else if (wcsstr(szCallerModName,SERVICE_SERVICES_EXE_PROCNAME)) { \
				(callerProc) = SERVICE_CALLER_PROCESS_SERVICES_EXE; \
			} \
			else { \
				(callerProc) = SERVICE_CALLER_PROCESS_OTHER_EXE; \
			} \
		} \
		else \
			(callerProc) = SERVICE_CALLER_PROCESS_OTHER_EXE; \
	}

//
//	Service is interfaced via series of IOCTL calls that define service life cycle.
//	Actual implementation is service-specific.
//

//
//	Start the service that has been in inactive state. Return code: SERVICE_SUCCESS or error code.
//
#define IOCTL_SERVICE_START		CTL_CODE(FILE_DEVICE_SERVICE, 1, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
//	Stop service, but do not unload service's DLL
//
#define IOCTL_SERVICE_STOP		CTL_CODE(FILE_DEVICE_SERVICE, 2, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
//	Refresh service's state from registry or other configuration storage
//
#define IOCTL_SERVICE_REFRESH	CTL_CODE(FILE_DEVICE_SERVICE, 3, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
//	Have service configure its registry for auto-load
//
#define IOCTL_SERVICE_INSTALL	CTL_CODE(FILE_DEVICE_SERVICE, 4, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
//	Remove registry configuration
//
#define IOCTL_SERVICE_UNINSTALL	CTL_CODE(FILE_DEVICE_SERVICE, 5, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
//	Unload the service which should be stopped.
//
#define IOCTL_SERVICE_UNLOAD	CTL_CODE(FILE_DEVICE_SERVICE, 6, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
//	Supply a configuration or command string and code to the service.
//
#define IOCTL_SERVICE_CONTROL	CTL_CODE(FILE_DEVICE_SERVICE, 7, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
//	Return service status.
//
#define IOCTL_SERVICE_STATUS	CTL_CODE(FILE_DEVICE_SERVICE, 8, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
//	Set service's debug zone mask (parameter is sizeof(DWORD) and contains the mask)
//
#define IOCTL_SERVICE_DEBUG	CTL_CODE(FILE_DEVICE_SERVICE, 9, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
//	Toggle service's console on/off (string "on" on no parameters is ON, "off" means off)
//
#define IOCTL_SERVICE_CONSOLE	CTL_CODE(FILE_DEVICE_SERVICE, 10, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
// Notify service a service request has arrived.  Input contains connected socket.
//
#define IOCTL_SERVICE_REGISTER_SOCKADDR   CTL_CODE(FILE_DEVICE_SERVICE, 11, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
// Notify service a service request has arrived.  For now all sockets associated with service will be closed at once.
//
#define IOCTL_SERVICE_DEREGISTER_SOCKADDR   CTL_CODE(FILE_DEVICE_SERVICE, 12, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
// Notify service a another socket has bound to it.  Input contains an accepted socket.
//
#define IOCTL_SERVICE_CONNECTION   CTL_CODE(FILE_DEVICE_SERVICE, 13, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
// Service has finished initial control setup.  Ready to start.
//
#define IOCTL_SERVICE_STARTED      CTL_CODE(FILE_DEVICE_SERVICE, 14, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
// Service is called with IOCTL_SERVICE_CAN_DEINIT immediatly before xxx_Deinit is called during DeregisterService.  
// If xxx_IOControl returns TRUE and sets buffer in pBufOut to zero, service instance will remain loaded and 
// xxx_Deinit will not be called.
//
#define IOCTL_SERVICE_QUERY_CAN_DEINIT   CTL_CODE(FILE_DEVICE_SERVICE, 15, METHOD_BUFFERED, FILE_ANY_ACCESS)

//
// If iphlpapi is present, services receive this notification when table that 
// maps IP addresses changes.
// Input contains PIP_ADAPTER_ADDRESSES retrieved from a call to GetAdaptersAddresses().
// This buffer is guaranteed to be valid only during the length of the call to xxx_IOControl.
//
#define IOCTL_SERVICE_NOTIFY_ADDR_CHANGE  CTL_CODE(FILE_DEVICE_SERVICE, 16, METHOD_BUFFERED, FILE_ANY_ACCESS)


//
// Services.exe supports a set of callbacks that can only be called from a running service (not API).
// pBufIn data structure contains a pointer to ServiceCallbackFunctions data structure
// IOCTL_SERVICE_CALLBACKS will sent to service during its initial load, and only if there
// are supported callbacks for service's mode of operation.
//
#define IOCTL_SERVICE_CALLBACK_FUNCTIONS  CTL_CODE(FILE_DEVICE_SERVICE, 17, METHOD_BUFFERED, FILE_ANY_ACCESS)


//
// Service returns a DWORD containing a set of flags that specify what options it supports.
// The meaning of the flags is service specific.
//
#define IOCTL_SERVICE_SUPPORTED_OPTIONS   CTL_CODE(FILE_DEVICE_SERVICE, 18, METHOD_BUFFERED, FILE_ANY_ACCESS)



// A service will be called with IOCTL_SERVICE_CALLBACKS and a pointer to this struct
// on startup potentially.  Note that only functions that are supported for a service's
// mode of operation will be set.  It is possible that function pointers will be NULL.

typedef void (WINAPI *PFN_SERVICE_SHUTDOWN)(void);


typedef struct _ServicesExeCallbackFunctions {
	// Only set when service is running in context SERVICE_INIT_STANDALONE, i.e.
	// in its own copy of services.exe.  Service calls this function to request itself
	// to be unloaded and the services.exe process to exit.  For typical scenario
	// (no SERVICE_INIT_STANDALONE), use DeregisterService() API to cause service to be unloaded.
	PFN_SERVICE_SHUTDOWN       pfnServiceShutdown;
} ServicesExeCallbackFunctions;



#if defined(WINCEOEM) && defined(UNDER_CE)
#include "pservice.h"
#ifdef WINCEMACRO
#include "mservice.h"
#endif
#endif


#endif	/* __service_H__ */