string.c

Windows CE documentation and examples from the Windows CE development manuals. There are lots of exa

#define STRING_M    ///< To manage exported variables

////////////////////////////////////////////////////////////////////////////////
//                                                                      Includes
////////////////////////////////////////////////////////////////////////////////

// System include
#include <windows.h>
#include <CEDDK.h>

// Local include
#include "string_DbgZones.h"
#include "string_iocontrol.h"
#include "stringdrv.h"

////////////////////////////////////////////////////////////////////////////////
//                                                               Defines & Types
////////////////////////////////////////////////////////////////////////////////

/// Structure which describes the driver context
typedef struct {
	DWORD dwOpenCount;	// keep count of the number of instances of this driver open
} T_DRIVERINIT_STRUCTURE, *PT_DRIVERINIT_STRUCTURE;

/// Structure which describes the opened device context
typedef struct {
	T_DRIVERINIT_STRUCTURE *pDeviceContext; ///< a pointer to the driver context
	DWORD dwAccessCode;						///< access mode for the opened device
	DWORD dwShareMode;						///< share mode for the opened device
	TCHAR szStoredString[STR_MAX_STRING_LENGTH];  ///< holds the current string
	CEDEVICE_POWER_STATE CurrentDx;
} T_DRIVEROPEN_STRUCTURE, *PT_DRIVEROPEN_STRUCTURE;

////////////////////////////////////////////////////////////////////////////////
//                                                                     Variables
////////////////////////////////////////////////////////////////////////////////
// Note : ONLY static

/// Describes the debug zones, this will be visible to people debugging with
/// Visual Studio and KITL
static DBGPARAM dpCurSettings =
{
	TEXT("StringDriver"),
	{
		//Human-readable descriptions of the zones
		TEXT("Init"), TEXT("DeInit"), TEXT("Open"), TEXT("Close"),
		TEXT("Read"), TEXT("Write"), TEXT("Seek"), TEXT("IOCtl"),
		TEXT("na"), TEXT("na"), TEXT("na"), TEXT("na"), TEXT("na"),
		TEXT("DllEntry"), TEXT("Warning"), TEXT("Error")
	}
	//The initial zones that will be enabled
	, MASK_INIT | MASK_DEINIT | MASK_IOCTL | MASK_ERROR
}; 


////////////////////////////////////////////////////////////////////////////////
//                                                 Internal functions prototypes
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
//                                                            Exported functions
////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////
/// This function is the entry point of the Dll driver.
/// This function intializes debug zone when called with the DLL_PROCESS_ATTACH 
/// reason.
///
/// Parameters:
/// \param		hinstDLL	DLL instance
/// \param		dwReason	Reason of the call
/// \param		lpvReserved	Not used
///
/// \return		\e TRUE when all is good
///	\return		\e FALSE when all is bad
/// 
////////////////////////////////////////////////////////////////////////////////
BOOL WINAPI STR_DllEntry(HANDLE hinstDLL, DWORD dwReason, LPVOID lpvReserved)
{
	switch(dwReason)
	{
	case DLL_PROCESS_ATTACH:
		DEBUGREGISTER((HMODULE)hinstDLL);
		DEBUGMSG(ZONE_INFO,(TEXT("STRING: DLL_PROCESS_ATTACH\r\n")));
		break;
	case DLL_THREAD_ATTACH:
		DEBUGMSG(ZONE_INFO,(TEXT("STRING: DLL_THREAD_ATTACH\r\n")));
		break;
	case DLL_THREAD_DETACH:
		DEBUGMSG(ZONE_INFO,(TEXT("STRING: DLL_THREAD_DETACH\r\n")));
		break;
	case DLL_PROCESS_DETACH:
		DEBUGMSG(ZONE_INFO,(TEXT("STRING: DLL_PROCESS_DETACH\r\n")));
		break;
#ifdef UNDER_CE
	case DLL_PROCESS_EXITING:
		DEBUGMSG(ZONE_INFO,(TEXT("STRING: DLL_PROCESS_EXITING\r\n")));
		break;
	case DLL_SYSTEM_STARTED:
		DEBUGMSG(ZONE_INFO,(TEXT("STRING: DLL_SYSTEM_STARTED\r\n")));
		break;
#endif
	}

	return TRUE;
}


////////////////////////////////////////////////////////////////////////////////
/// This function initializes the device.
/// Device Manager calls this function as a result of a call to the ActivateDeviceEx 
/// function. When the user starts using a device, such as inserting a PC Card, 
/// Device Manager calls this function to initialize the device. Applications do not call this function.
///	
/// Parameters:
/// \param		pContext		Pointer to a string containing the registry path to the active key for the stream interface driver.
/// \param		lpvBusContext	Potentially process-mapped pointer passed as the 
///								fourth parameter to ActivateDeviceEx. If this driver 
///								was loaded through legacy mechanisms, then lpvBusContext 
///								is zero. This pointer, if used, has only been mapped 
///								again as it passes through the protected server library (PSL).
///								The <b>STR_Init<b> function is responsible for performing all protection 
///								checking. In addition, any pointers referenced through lpvBusContext 
///								must be remapped with the <b>MapCallerPtr</b> function before they 
///								can be dereferenced.
///
/// \return		Returns a handle to the device context created if successful. 
///	\return		\e zero if not successful.
///
////////////////////////////////////////////////////////////////////////////////
DWORD STR_Init(LPCTSTR pContext, LPCVOID lpvBusContext)
{
	T_DRIVERINIT_STRUCTURE *pDeviceContext = (T_DRIVERINIT_STRUCTURE *) LocalAlloc(LMEM_ZEROINIT|LMEM_FIXED, sizeof(T_DRIVERINIT_STRUCTURE));

	if (pDeviceContext == NULL)
	{
		DEBUGMSG(ZONE_ERROR,(L"STRING: ERROR: Couldn't allocate memory for STRING device context\r\n"));
		return FALSE;
	}

	pDeviceContext->dwOpenCount = 0;

	DEBUGMSG(ZONE_INIT,(L"STRING: STRING driver initialized\r\n"));

	return (DWORD)pDeviceContext;
}


////////////////////////////////////////////////////////////////////////////////
/// This function uninitializes the device..
/// When the user stops using a device, such as when a PC Card is removed from its socket, 
/// Device Manager calls this function. Applications do not call this function. Device Manager 
/// calls the STR_Deinit driver function as a result of a call to the DeactivateDevice function. 
/// Your stream interface driver should free any resources it has allocated, and then terminate.
///
/// Parameters:
/// \param		pContextInit	Pointer to the the device init context. The STR_Init (Device Manager)
///								function creates and returns this pointer.
///
/// \return		\e TRUE indicates success
///	\return		\e FALSE indicates failure
///
////////////////////////////////////////////////////////////////////////////////
BOOL STR_Deinit(void *pDeviceContext)
{
	T_DRIVERINIT_STRUCTURE* pExplicitDeviceContext = (T_DRIVERINIT_STRUCTURE *)pDeviceContext;

	if (pDeviceContext == NULL)
	{
		SetLastError(ERROR_INVALID_HANDLE);
		DEBUGMSG(ZONE_ERROR|ZONE_DEINIT,(L"STRING:ERROR: Invalid device context pointer\r\n"));
		return FALSE;
	}

	if (LocalFree(pDeviceContext) != NULL)
	{
		DEBUGMSG(ZONE_ERROR|ZONE_DEINIT,(L"STRING:ERROR: Unable to free device context\r\n"));
		return FALSE;
	}
	
	DEBUGMSG(ZONE_DEINIT,(L"STRING: Deinit successful\r\n"));

	return TRUE;
}


////////////////////////////////////////////////////////////////////////////////
/// This function opens a device for reading, writing, or both.
/// When this function executes, your device should allocate the resources that it needs for 
/// each open context and prepare for operation. This might involve preparing the device for 
/// reading or writing and initializing data structures it uses for operation.
///
/// Parameters:
/// \param		pDeviceContext	Pointer to the the device context. The <b>STR_Init</b> (Device Manager)
///								function creates and returns this identifier.
/// \param		AccessCode		Access code for the device. The access is a combination
///								of read and write access from <b>CreateFile</b>. 
/// \param		ShareMode		File share mode of the device. The share mode is a combination 
///								of read and write access sharing from <b>CreateFile</b>. 
///
/// \return		This function returns a handle that identifies the open context of the device 
///				to the calling application. If your device can be opened multiple times, use 
///				this handle to identify each open context.
///
////////////////////////////////////////////////////////////////////////////////
DWORD STR_Open(void *pDeviceContext, DWORD AccessCode, DWORD ShareMode)
{
	T_DRIVERINIT_STRUCTURE * pExplicitDeviceContext = (T_DRIVERINIT_STRUCTURE *)pDeviceContext; //typecast version of the device context
	T_DRIVEROPEN_STRUCTURE * pOpenContext = NULL;

	DEBUGMSG(ZONE_OPEN,(L"STRING: Opening a context of the STRING driver\r\n"));

	if (pExplicitDeviceContext == NULL)
	{
		SetLastError(ERROR_INVALID_HANDLE);
		DEBUGMSG(ZONE_OPEN|ZONE_ERROR,(L"STRING:ERROR: Invalid device context pointer\r\n"));
		return FALSE;
	}

	pOpenContext =(PT_DRIVEROPEN_STRUCTURE) LocalAlloc(LMEM_ZEROINIT|LMEM_FIXED, sizeof(T_DRIVEROPEN_STRUCTURE));

	if (pOpenContext == NULL)
	{
		DEBUGMSG(ZONE_OPEN|ZONE_ERROR,(L"STRING:ERROR: Couldn't allocate memory for this context of the device\r\n"));
		return FALSE;
	}

	DEBUGMSG(ZONE_OPEN,(L"STRING: STRING driver context created\r\n"));

	// Store device settings for future use
	pOpenContext->pDeviceContext = pDeviceContext;
	pOpenContext->dwAccessCode = AccessCode;
	pOpenContext->dwShareMode = ShareMode;

	// Increase opened device counter
	pOpenContext->pDeviceContext->dwOpenCount++;	

	return (DWORD)pOpenContext;
}


////////////////////////////////////////////////////////////////////////////////
/// This function closes a device context created by the pOpenContext parameter.
/// An application calls the CloseHandle function to stop using a stream interface driver. 
/// The hFile parameter specifies the handle associated with the device context. In response
/// to <b>CloseHandle</b>, the operating system invokes <b>STR_Close</b>.
///
/// Parameters:
/// \param		pOpenContext	Pointer returned by the <b>STR_Open</b> (Device Manager) function, 
///								which is used to identify the open context of the device. 
///
/// \return		\e TRUE indicates success
///	\return		\e FALSE indicates failure
///
////////////////////////////////////////////////////////////////////////////////
BOOL STR_Close(void *pOpenContext)
{
	T_DRIVEROPEN_STRUCTURE *pExplicitOpenContext;
	T_DRIVERINIT_STRUCTURE *pDeviceContext;

	if (pOpenContext == NULL)
	{
		SetLastError(ERROR_INVALID_HANDLE);
		DEBUGMSG(ZONE_CLOSE|ZONE_ERROR,(L"STRING:ERROR: Invalid Open Context\r\n"));
		return FALSE;
	}

	pExplicitOpenContext = (T_DRIVEROPEN_STRUCTURE *)pOpenContext;

	pDeviceContext = pExplicitOpenContext->pDeviceContext;

	DEBUGMSG(ZONE_CLOSE,(L"STRING: Closing Driver Context #%d\n", pDeviceContext->dwOpenCount));

	// Free memory
	if (LocalFree(pExplicitOpenContext) != NULL)
	{
		DEBUGMSG(ZONE_CLOSE|ZONE_ERROR,(L"STRING:ERROR: Couldn't deallocate memory for this context of the device\r\n"));
		return FALSE;
	}
	else
	{
		// Decrease opened device counter
		pDeviceContext->dwOpenCount --;
		DEBUGMSG(ZONE_CLOSE, (L"STRING: Context #%d closed successfully", pDeviceContext->dwOpenCount+1));
		return TRUE;
	}
}


////////////////////////////////////////////////////////////////////////////////
/// This function reads data from the device identified by the open context.
/// After an application calls the ReadFile function to read from the device, the operating system
/// invokes this function. The <i>hFile</i> parameter is a handle to the device. The <i>pBuffer</i> parameter 
/// points to the buffer that contains the data read from the device. The <i>dwCount</i> parameter indicates 
/// the number of bytes that the application requests to read from the device.
///