Serial Debug Menu

Platform Builder: Formatting Output with DEBUGMSG and RETAILMSG

Bruce Eitman — Tue, 15 Jul 2008 02:00:58 GMT

For those of you who have done a lot of output using printf the following will be familiar, but I think that there are a lot of programmers who have done most of their user interface code with a GUI. I have been getting questions about the format string in DEBUGMSG and RETAILMSG lately. I will not try to be the full documentation on format strings, but I thought that I would explain a few things about the format string that can be useful.

You may have seen some of my examples using %s, %8s and %-*s and maybe even wondered what the numbers, asterisks and minus sign do. Of course C programmers learn early that %s causes a parameter to be output as a string. You can control the width of the string field by putting a number between the ‘%’ and the ‘s’, so %8s says output the string with at least 8 characters and fill the left side with spaces if the string contains less than 8 characters. That can be handly if you want to output columns of data. If we change that to %-8s, the minus sign means to fill to the right with spaces. But what if you don’t know the width of the field when you write the code, but instead calculate it at run time or want to use a macro to set the width? For more dynamic field width, you can use an asterisk which says that there is a parameter that sets the field width.

Examples:

RETAILMSG( 1, (TEXT(">%s<\n"), DriverName ));

RETAILMSG( 1, (TEXT(">%4s<\n"), DriverName ));

RETAILMSG( 1, (TEXT(">%4.4s<\n"), DriverName ));

RETAILMSG( 1, (TEXT(">%*s<\n"), MaxStringLength, DriverName ));

RETAILMSG( 1, (TEXT(">%-*s<\n"), MaxStringLength,DriverName ));>MyDriver<

Gives the following output, note that I put in > and < to show the string output:

>MyDriver<

>MyDr<

> MyDriver<

>MyDriver <

Notice that I also threw in an extra one, %4.4s which says the string should be 4 characters long, and no longer. So the output was MyDr instead of the full MyDriver.

These same format modifiers can be used with %d and %x as well.

Go to Serial Debug Menu Summary

Tags: RETAILMSG, DEBUGMSG

Windows CE: Loading a Driver with ActivateDeviceEx

Bruce Eitman — Tue, 15 Jul 2008 01:16:42 GMT

In my post about a basic driver shell, I assumed that the driver was built into the system including the registry settings to cause the device manager to load the driver when the system booted. Sometimes there is a reason to load a driver when an application starts. For that there are several functions that can be used including; RegisterDevice, ActivateDevice and ActivateDeviceEx.

RegisterDevice is maintained for backward compatibility, but for future compatibility you probably should start using ActivateDevice or ActivateDeviceEx.

The precondition for using ActiveateDeviceEx is that the registry contains settings for the driver and that the driver is in the system path; for more on the system path see the documentation for LoadLibrary(). Through trial and error, I found that the applications launch directory is not a valid location for the driver when using ActivateDeviceEx().

I want my application to not only load the driver but also unload it when finished, so I will keep a global variable with the driver handle. The following function will load DriverShell.dll:

#define DRIVERSHELL_REG_KEY (TEXT("Drivers\\Builtin\\DriverShell"))

HANDLE hDriverShell = INVALID_HANDLE_VALUE;

BOOL LoadDriverShell()

{

BOOL RetVal = FALSE;

if( hDriverShell == INVALID_HANDLE_VALUE )

{

hDriverShell = ActivateDeviceEx( DRIVERSHELL_REG_KEY,

NULL,

NULL

);

if (hDriverShell != INVALID_HANDLE_VALUE && hDriverShell != 0)

RetVal = TRUE;

else

{

// Note: the driver may have succeded to load if the handle is zero

RETAILMSG( 1, (TEXT("Failed to activate driver %d\n"), GetLastError() ));

}

return RetVal;

}

The documentation states that the return value from ActivateDeviceEx is a valid handle if it succeeds or INVALID_HANDLE_VALUE on failure, but then goes on to discuss that the return could be zero under certain conditions. What I found when I had the driver in a folder that wasn’t in the system path was that the return value is zero for failure.

To then unload the driver:

void UnloadDriverShell()

{

if( hDriverShell != INVALID_HANDLE_VALUE )

{

DeactivateDevice( hDriverShell );

hDriverShell = INVALID_HANDLE_VALUE;

}

I am running this on a headless system, so I found it was much simpler to include the registry settings in my code and put together the following to add the registry settings for the driver:

typedef struct {

TCHAR *ValueName;

DWORD Type;

DWORD DwordValue;

TCHAR *StringValue;

} RegEntry ;

RegEntry RegEntries[] = {

{TEXT("Dll"), REG_SZ, 0, TEXT("DriverShell.dll") },

{TEXT("Prefix"), REG_SZ, 0, TEXT("XXX") },

{TEXT("Order"), REG_DWORD, 4, NULL },

{NULL, 0, 0, NULL}

};

void AddDriverShellToRegistry()

{

HKEY hTargetKey;

DWORD dwDisposition;

DWORD RetVal;

DWORD Index=0;

BYTE * Value;

DWORD uSize;

RetVal = RegCreateKeyEx( HKEY_LOCAL_MACHINE,

DRIVERSHELL_REG_KEY,

NULL,

REG_OPTION_NON_VOLATILE,

KEY_ALL_ACCESS ,

NULL,

&hTargetKey,

&dwDisposition

);

if (RetVal == ERROR_SUCCESS)

{

while( RegEntries[Index].ValueName != NULL )

{

if( RegEntries[Index].Type == REG_DWORD )

{

Value = (BYTE *)&RegEntries[Index].DwordValue;

uSize = sizeof( DWORD );

}

else

{

Value = (BYTE *)RegEntries[Index].StringValue;

uSize = (wcslen( RegEntries[Index].StringValue ) + 1 ) * sizeof( TCHAR );

}

RetVal = RegSetValueEx(hTargetKey,

RegEntries[Index].ValueName,

RegEntries[Index].Type,

(CONST BYTE *)Value,

uSize

);

Index++;

}

So now if you add a call to AddDriverShellToRegistry before calling ActivateDeviceEx the registry settings will be added and ready to use.

You can use the code in Windows CE: Listing Running Drivers to verify that the driver loaded successfully, or you can use ReadFile, WriteFile or DeviceIoControl to test that you can access the driver from your application.

Go to Serial Debug Menu Summary

Tags: Drivers

Windows CE: Watching Folders for Changes

Bruce Eitman — Fri, 27 Jun 2008 02:38:26 GMT

It is not uncommon to need to watch a folder for changes to files. It is possible to monitor for changes using FindFirstChangeNotification() and FindNextChangeNotification(). These functions don’t work like FindFirstFile() does, instead FindFirstChangeNotification() returns a HANDLE that can be used in WaitForSingleObject() and WaitForMultipleObjects(). In this post, I will develop a function that will monitor for changes to a list of folders. The function is FolderWatcherThread().

FolderWatcherThread() takes to parameters, an array of string pointers that point to strings containing folder names, and the number of pointers. It starts by looping through the array calling FindFirstChangeNotification() to get the handles to wait on. It is important to check the results, if the folder doesn’t exist the call will fail.

I found that the second parameter, which is a Boolean indicating if it should notify recursively, isn’t particularly useful. It does work for notifications when set to true, but I couldn’t get the data for the subfolders. A workaround for this would be to use FindFirstFile() and FindNextFile() to create an array of all folders in the tree.

DWORD FolderWatcherThread(TCHAR *Folders[], DWORD NumFolders)

{

DWORD NumFolderWatches = 0;

TCHAR **FolderNames;

HANDLE *Events;

DWORD dwWait;

DWORD Index;

Events = LocalAlloc(LMEM_FIXED, NumFolders * sizeof( HANDLE ) );

FolderNames = LocalAlloc(LMEM_FIXED, NumFolders * sizeof( TCHAR * ) );

for (Index = 0; Index < NumFolders; Index++)

{

Events[NumFolderWatches] = FindFirstChangeNotification(Folders[Index], FALSE,

FILE_NOTIFY_CHANGE_CEGETINFO |

FILE_NOTIFY_CHANGE_FILE_NAME |

FILE_NOTIFY_CHANGE_DIR_NAME |

FILE_NOTIFY_CHANGE_SIZE |

FILE_NOTIFY_CHANGE_LAST_WRITE|

FILE_NOTIFY_CHANGE_ATTRIBUTES|

FILE_NOTIFY_CHANGE_LAST_ACCESS|

FILE_NOTIFY_CHANGE_CREATION|

FILE_NOTIFY_CHANGE_SECURITY);

if (INVALID_HANDLE_VALUE != Events[NumFolderWatches])

{

FolderNames[NumFolderWatches] = Folders[Index];

NumFolderWatches++;

}

if (NumFolderWatches == 0)

return 0;

Now we have an array of HANDLES that we can wait on. When one of the HANDLES is signaled we can use CeGetFileNotificationInfo() to get information about what the change was that occurred. This is the function that doesn’t work for recursive notifications. It does return a data structure, but it doesn’t seem to write data to the structure.

CeGetFileNotificationInfo() is first called to find out how much data it has for us, then allocate a buffer for the data and call it again to get the data. There can be more than one piece of data, so loop through to handle all of the data.

while (TRUE)

{

dwWait = WaitForMultipleObjects(NumFolderWatches, Events, FALSE, INFINITE);

if (NumFolderWatches > dwWait)

{

DWORD RequiredBufferSize = 0;

LPBYTE NotificationData = NULL;

FILE_NOTIFY_INFORMATION * pNotifyData;

DWORD FNIOffset;

if (!CeGetFileNotificationInfo(Events[dwWait],

0, NULL, 0, NULL, &RequiredBufferSize))

{

continue;

}

NotificationData = (LPBYTE) LocalAlloc(LMEM_FIXED, RequiredBufferSize);

if(NotificationData == NULL)

break;

if(!CeGetFileNotificationInfo(Events[dwWait],

0, NotificationData, RequiredBufferSize, NULL, NULL))

{

LocalFree(NotificationData);

continue;

}

Now output information about the change that occurred.

RETAILMSG( 1, (TEXT("Folder: %s\n"), FolderNames[dwWait]));

pNotifyData = NULL;

FNIOffset = 0;

{

pNotifyData = (FILE_NOTIFY_INFORMATION *) (NotificationData+FNIOffset);

RETAILMSG( 1, (TEXT("NextEntryOffset %d\n"), pNotifyData->NextEntryOffset));

RETAILMSG( 1, (TEXT("Action %d\n"), pNotifyData->Action));

RETAILMSG( 1, (TEXT("FileNameLength %d\n"), pNotifyData->FileNameLength));

RETAILMSG( 1, (TEXT("FileName %s\n"), pNotifyData->FileName));

switch (pNotifyData->Action)

{

case FILE_ACTION_CHANGE_COMPLETED:

RETAILMSG( 1, (TEXT("File change complete %s\n"), pNotifyData->FileName ));

break;

case FILE_ACTION_RENAMED_NEW_NAME:

RETAILMSG( 1, (TEXT("File name changed %s\n"), pNotifyData->FileName ));

break;

case FILE_ACTION_REMOVED:

RETAILMSG( 1, (TEXT("File removed %s\n"), pNotifyData->FileName ));

break;

case FILE_ACTION_RENAMED_OLD_NAME:

RETAILMSG( 1, (TEXT("File remaned, old name %s\n"), pNotifyData->FileName ));

break;

case FILE_ACTION_ADDED:

RETAILMSG( 1, (TEXT("File Added %s\n"), pNotifyData->FileName ));

break;

case FILE_ACTION_MODIFIED:

RETAILMSG( 1, (TEXT("File modified %s\n"), pNotifyData->FileName ));

break;

default:

RETAILMSG( 1, (TEXT("File unkown Action %X\n"), pNotifyData->Action ));

break;

}

FNIOffset += pNotifyData->NextEntryOffset;

} while(pNotifyData->NextEntryOffset);

LocalFree(NotificationData);

FindNextChangeNotification( Events[dwWait]);

}

else

{

break;

}

And finally clean up by calling FindCloseChangeNotification() for each HANDLE, free the Events and FolderNames arrays and return.

for (Index = 0; Index < NumFolderWatches; Index++)

{

FindCloseChangeNotification( Events[Index]);

}

LocalFree(Events);

LocalFree( FolderNames );

return 0;

}

FolderWatcherThread() can be called with a simple array of pointers to folder names like:

DWORD DiskWatcher()

{

TCHAR *Folders[] = { TEXT("\\Hard Disk"), TEXT("\\Storage Card"), TEXT("\\Storage Card\\Data") };

return FolderWatcherThread( Folders, sizeof(Folders)/sizeof(*Folders));

}

Or you can get creative with a dynamically created list of folders.

Go to Serial Debug Menu Summary