Windows CE Services Douglas Boling President Boling Consulting Inc.

M anagement T ools C ommunications & M essaging Device Update Agent Software Update Services Live Communications Server Exchange Server Internet Security and Acceleration Server Speech Server Image Update L ocation S ervices M ultimedia MapPoint DirectX Windows Media Visual Studio 2005 D evelopment T ools MFC 8.0, ATL 8.0 Win32 N ative M anaged S erver S ide L ightweight R elational SQL Server 2005 Express EditionEDB D ata P rogramming M odel D evice B uilding T ools D evice B uilding T ools H ardware/ D rivers Windows XP DDK Windows Embedded Studio Platform Builder OEM/IHV Supplied BSP (ARM, SH4, MIPS) OEM Hardware and Standard Drivers Standard PC Hardware and Drivers SQL Server 2005SQL Server 2005 Mobile Edition ASP.NET Mobile ControlsASP.NET.NET Compact Framework.NET Framework Microsoft Operations Manager Systems Management Server

Speaker Douglas Boling bolingconsulting.com Author – “Programming Microsoft Windows CE 3 rd Edition” Trainer – Classes on Windows CE App Development Windows CE OAL Development Consultant – Work with companies to help their application and platform development efforts

Agenda Introducing Windows CE Services What it is Why it’s here The anatomy of a service The Super Service The service API Stand alone services

Why Use A Service? Windows CE has a 32 process limit Too many processes can cause problems Processes can be terminated Processes have to do their own TCP/IP serving

Background Windows CE originally didn’t have the concept of a service Developers wrote “Device Drivers” that would run in the background Bugs in a service could bring down device.exe Which could bring down the system

Background Services Manager solves this problem Challenge: Simple porting of “legacy” services Answer: Match the device driver interface

What is a Service? It’s a DLL Loaded by the Services Manager Adds threads without adding a process Reduces the need for background processes Harder for the user to shut down accidentally

The Lifetime of a Service A service is loaded into memory The service is started The service can be auto-started on load The service performs the work The service can be stopped and restarted programmatically The service can be unloaded if desired

Agenda Introducing Windows CE Services The anatomy of a service Entry points IOCTL commands The Super Service The service API Stand alone services

Implementing a Service Create a Windows CE DLL Expose a stream API like drivers Xxx_Init, xxx_Deinit, etc. Add registry entries to load at boot [HKLM]\Services Subkeys organized like device driver keys DLL, Prefix, Index, Keep, Order, and so forth

Service Entry Points Windows CE Service xxx_Init xxx_Deinit xxx_Open xxx_Close xxx_Read xxx_Write xxx_Seek xxx_IoControl Driver like entry points CategoriesInitialization File IO IOCTL

Service DLL Entry Points Required xxx_Init, xxx_Deinit, xxx_IOControl Necessary for access by File API xxx_Open, xxx_Close xxx_IOControl provides primary interface

Service IOCTL Commands Primary interface to services IOCTL commands divided into two parts CommandsQueriesNotifications Some IOCTLs optional Debugging Super Service support

Service IOCTL Commands IOCTL_SERVICE_START Service should start If service stopped on load, this command will automatically start any port monitoring IOCTL_SERVICE_STOP Service should stop

Service IOCTL Commands IOCTL_SERVICE_INSTALL Service should write its initialization data to the registry under [HKLM]\Services IOCTL_SERVICE_UNINSTALL Service should remove any registry information under [HKLM]\Services IOCTL_SERVICE_REFRESH Service should reload any configuration information in the registry

Service IOCTL Commands IOCTL_SERVICE_CONTROL IOCTL of IOCTLs! IOCTL_SERVICE_CONSOLE Service should enable or disable its console Input buffer set to string “on” or “off” indicating request

Service IOCTL Commands IOCTL_SERVICE_DEBUG Service should set its debug zones from the DWORD in input buffer IOCTL_SERVICE_COMMANDLINE_PARAMS Support for help text in Services cmd line New to Windows CE 5

Service IOCTL Queries IOCTL_SERVICE_STATUS Service should return its current state The service maintainins its own state Windows CE provides a documented set of states but service can implement others

Service States SERVICE_STATE_UNINITIALIZEDSERVICE_STATE_OFFSERVICE_STATE_STARTING_UPSERVICE_STATE_ONSERVICE_STATE_SHUTTING_DOWNSERVICE_STATE_UNLOADINGSERVICE_STATE_UNKNOWN

Service IOCTL Notifications IOCTL_SERVICE_NOTIFY_ADDR_CHANGE Sent to notify the service that an IP address change has occurred in the system IOCTL_SERVICE_QUERY_CAN_DEINIT Sent to query if the service can be unloaded

Agenda Introducing Windows CE Services The anatomy of a service The Super Service What it is How to use it The service API Stand alone services

Super Service Support Many services are TCP/IP servers HTTP server, FTP server, Telnet server, others… Service manager provides support for monitoring ports Service indicates port by registry value or programmatically Service notified when client connects Socket handle passed to service

Super Service When notification occurs service communicates with socket provided The service must close socket when communication complete Service can tell Super Service to stop monitoring port programmatically

Super Service at Boot If the service is initially stopped, and an Accept subkey is present, the super service will automatically be started The sockaddr value contains a sockaddr structure indicating the target IP address to monitor

Adding a Port Services can ask for port monitoring hServiceHandle of the service pSockAddrStructure indicating port cbSockAddrSize of the structure iProtocolProtocol of the socket szRegWritePathRegistry path ServiceAddPort (HANDLE hService, SOCKADDR pSockAddr, INT cbSockAddr, INT iProtocol, WCHAR szRegWritePath);

Closing a Port Service can stop monitoring by calling hServiceHandle of the service pSockAddrsockaddr structure cbSockAddrSize of the structure iProtocolSocket protocol fRemoveFromRegistryIndicates reg to be cleaned BOOL ServiceClosePort (HANDLE hService, SOCKADDR* pSockAddr,int cbSockAddr, int iProtocol, BOOL fRemoveFromRegistry);

Closing All Ports To close all ports hServiceHandle of the service BOOL ServiceUnbindPorts (HANDLE hService);

Super Service Notifications IOCTL_SERVICE_STARTED Sent to notify the service that all ports requested in the registry are being monitored

Super Service Notifications IOCTL_SERVICE_REGISTER_SOCKADDR Sent by the super service twice to notify the driver that a port is about to be monitored. The first time, the input buffer is null to query if the service wants super service support The second time, the input buffer will contain a sockaddr structure identifying the port about to be monitored

Super Service Notifications IOCTL_SERVICE_CONNECTION Sent to notify the service that a port being monitored for the service has been connected to. The Input buffer contains the socket handle The service must close the socket handle even if it fails the IOCTL

Super Service Notifications IOCTL_SERVICE_DEREGISTER_SOCKADDR Sent by the super service to notify the driver that a port is no longer going to be monitored. If a specific port is to be dropped, the input buffer will contain a sockaddr structure identifying the port about to be monitored If all ports are to be dropped, the input buffer will be null

Agenda Introducing Windows CE Services The anatomy of a service The Super Service The service API ControllingEnumerating Stand alone services

Loading a Service at Boot System loads the services listed in [HKLM]\Services Each subkey describes a service Subkey format similar to device driver keys DLL, Name, Order, Index, … Context value has special meaning Indicates if service should start immediately Indicates if the service should be loaded by a stand-alone copy of the services manager

Loading a Service ActivateService loads a service from registry information lpszDevKeyName of key under [HKLM]\Services dwClientInfoReserved, set to 0 HANDLE ActivateService (LPCWSTR lpszDevKey, DWORD dwClientInfo);

Loading a Service RegisterService provides all relevant information lpszType3 character name of service dwIndexAvailable index value lpszLibName of the DLL dwInfoContext passed to Init HANDLE RegisterService(LPCWSTR lpszType, DWORD dwIndex, LPCWSTR lpszLib, DWORD dwInfo);

Unloading a Service Normally, services stay in memory and are simply started and stopped. To unload a service call DeregisterService BOOL DeregisterService (HANDLE hDevice);

Unloading a Service If an application doesn’t have the service handle it can be queried szPrefixContains the prefix and instance (TEL0:) szDllNameReturns the DLL name pdwDllBufBuffer size HANDLE GetServiceHandle (LPWSTR szPrefix, LPWSTR szDllName, DWORD pdwDllBuf);

Enumerating Services Services can be enumerated with pBufferBuffer to be filled ServiceEnumInfo structures pdwServiceEntriesNumber of structures pdwBufferLenSize of the buffer BOOL EnumServices (PBYTE pBuffer, DWORD *pdwServiceEntries, DWORD pdwBufferLen);

Enumerating Services szPrefixService name (TEL1:) szDllNameThe name of the DLL hServiceHandleService handle dwServiceStateCurrent state typedef struct_ServiceEnumInfo { WCHAR szPrefix[6]; WCHAR szDllName; HANDLE hServiceHandle; DWORD dwServiceState; } ServiceEnumInfo;

Controlling a Service Applications can talk to a service without the File API The parameters are similar to DeviceIoControl BOOL ServiceIoControl (HANDLE hService, DWORD dwIoControlCode, LPVOID lpInBuf, DWORD nInBufSize, LPVOID lpOutBuf, DWORD nOutBufSize, LPDWORD lpBytesReturned, LPOVERLAPPED lpOverlapped);

Agenda Introducing Windows CE Services The anatomy of a service The Super Service The service API Stand alone services Why are these useful

Stand-Alone Services Services can be loaded with a unique copy of the Services manager Advantages: Debugging – A service will not corrupt other services running on the machine Memory space – A separate copy will have more virtual space Disadvantages: Stand-Alone services aren’t enumerated Stand-Alone services can’t be accessed with File IO

Stand-alone Service IOCTL IOCTL_SERVICE_CALLBACK_FUNCTIONS Sent after the Init function is called to provide a pointer to the Service Manager’s shutdown function. This is only used when the service is running in stand- alone mode Service should call the function passed when it wants to unload

User Control of Services Services application has a command line interface Allows control over the start, stop, load, and register of services Output can be redirected to files or the debug serial port

Services Command Line

Summary Use Services! Services are actually quite simple It’s almost identical to a stream driver The service must maintain the state Understand the difference between a IOCTL commands, queries and notifications Use the examples in Platform Builder as the true documentation

Questions bolingconsulting.com

While at MEDC 2005… Fill out an evaluation for this session Randomly selected instant WIN prizes! Randomly selected instant WIN prizes! Use real technology in a lab Instructor led Reef E/F & Breakers L Self-paced Reef B/C Self-paced Reef B/C Visit the Microsoft Product Pavilion in the Exhibit Hall Shorelines B in the Exhibit Hall Shorelines B

After The Conference… Develop Build InstallBuildJoin Install Enter Enter Join Full-featured trial versions of Windows CE and/or Windows XP Embedded Cool stuff & tell us about it: msdn.microsoft.com/embedded/community msdn.microsoft.com/embedded/community Windows Embedded Partner Program: Windows Mobile 5.0 Eval Kit including Visual Studio 2005 Beta 2 Mobile2Market Contest and win up to $25000: mobile2marketcontest.com mobile2marketcontest.com Microsoft Solutions Partner Program: partner.microsoft.com partner.microsoft.com

Tools & Resources msdn.microsoft.com/ embedded microsoft.public. windowsxp.embedded windowsce.platbuilder windowsce.platbuilder windowsce.embedded.vc windowsce.embedded.vc blogs.msdn.com/ mikehall Windows CE 5.0 Eval Kit Windows XP Embedded Eval Kit msdn.microsoft.com/ mobility microsoft.public. pocketpc.developer smartphone.developer dotnet.framework.compactframework blogs.msdn.com/ windowsmobile vsdteam netcfteam Windows Mobile 5.0 Eval Kit Websites Newsgroups Blogs Tools Build Develop

© 2005 Microsoft Corporation. All rights reserved. This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.