Table 1 lists the character count string safe functions provided in "strsafe.h" and the c-runtime functions (CRT) functions they are intended to replace.

Let us assume for the moment that you need to write a function to generate the full name of a file from an input full directory path and the handle to a file. Furthermore, we will also assume that we will never see a long path name, because everyone must be like us and hate to have long file names. Thus the function that you may write to handle this could be as shown in Figure 1.

wchar* GenerateFullPath(wchar* fulldirPath,HANDLE File)
{
 static wchar dirname[100];  // assume you think all paths are small
 wchar* fileName = NULL;
 
 ASSERT(fulldirPath);
 ASSERT(File);
 
 fileName = GetFileName(File); // Get the name of the input file
 strcpy(dirname,fulldirPath);  // copy the input dir name
 strcat(dirname,L"\\");  // append a \ to the name
 strcat(dirname,fileName); // concatenate the filename
 
 return dirname;        // return the full path to the caller.
}

If you analyze this code, I am sure that you can see a great many faults that could occur in this code. Most of them center around overrunning the dirname buffer since we forgot to look at the string lengths of the buffers we were concatenating from. A better solution to this function could be either Figure 2 or Figure 3, one illustrating the use of the Cch version of the string safe functions (Figure 2)and the other using the Cb version (Figure 3).

wchar* GenerateFullPath(wchar* fulldirPath,HANDLE File)
{
 static wchar dirname[MAX_PATH];
 wchar*   fileName = NULL;
 NTSTATUS  status;
 
 ASSERT(fulldirPath);
 ASSERT(File);
 
 ASSERT(MAX_PATH <= STRSAFE_MAX_CCH);
 
 fileName = GetFileName(File);  // Get the name of the input file
 
 status = RtlStringCchCopyW(dirname,MAX_PATH,fulldirPath);
 if(!NT_SUCCESS(status) {
  return NULL;
 }
 status = RtlStringCchCatW(dirname,MAX_PATH,L"\\");
 if(!NT_SUCCESS(status) {
  return NULL;
 }
 status = RtlStringCchCatW(dirname,MAX_PATH,fileName);
 if(!NT_SUCCESS(status) {
  return NULL;
 } 
 return dirname;  // return the full path to the caller.
}

Figure 2 - Cch String Safe Usage

wchar* GenerateFullPath(wchar* fulldirPath,HANDLE File)
{
 static wchar dirname[MAX_PATH];
 wchar*   fileName = NULL;
 NTSTATUS  status;
 
 ASSERT(fulldirPath);
 ASSERT(File);
 
 ASSERT(MAX_PATH <= STRSAFE_MAX_CCH);
 
 fileName = GetFileName(File);  // Get the name of the input file
 
 status = RtlStringCbCopyW(dirname,MAX_PATH*sizeof(WCHAR),fulldirPath);
 if(!NT_SUCCESS(status) {
  return NULL;
 }
 status = RtlStringCbCatW(dirname,MAX_PATH*sizeof(WCHAR),L"\\");
 if(!NT_SUCCESS(status) {
  return NULL;
 }
 status = RtlStringCbCatW(dirname,MAX_PATH*sizeof(WCHAR),fileName);
 if(!NT_SUCCESS(status) {
  return NULL;
 }
 return dirname;  // return the full path to the caller.
} 

Figure 3 - Cb String Safe Usage

In order to build your code correctly, you may want to know about the compile time variables that you can define to allow you to optimize how you use the string safe functions.

If you want to use the string safe functions in library form then define STRSAFE_LIB before including "strsafe.h" in your code. In addition, you will need to insure that you link your code against "$(SDK_LIB_PATH)\strsafe.lib". Why do this? Well, instead of including the string safe routines that you use in your binary, this allows your driver to dynamically bind to the string safe functions when it loads, hopefully allowing you to be running against the latest most improved implementations of these functions. This can be both good and bad.

#define STRSAFE_LIB
#include <strsafe.h>

If you don't define STRSAFE_LIB in your code, the current revision of the string safe functions will be compiled as part of your driver code (i.e., the implementations of the routines will be compiled as part of "strsafe.h"), and you do not need to link against strsafe.lib

Normally when you include "strsafe.h" all older functions (c-runtime functions) that are replaced by "strsafe.h" defined functions are deprecated, i.e. you are given warnings that that the functions are not to be used and you are urged to use their string safe equivalents.   If for some unknown reason you have to use one of these functions, you should define STRSAFE_NO_DEPRECATE.  This definition will suppress the warnings and allow you to compile your driver.

#define STRSAFE_NO_DEPRECATE
#include <strsafe.h>

If for some reason you want to limit your code to only use character count related string safe functions, then you should define STRSAFE_NO_CB_FUNCTIONS. This definition will then limit your code to the use of the RtlStringCchxxx functions.

#define STRSAFE_NO_CB_FUNCTIONS
#include <strsafe.h>

Similarly, the STRSAFE_NO_CCH_FUNCTIONS define allows you to limit your code to only use byte count related string functions. Using this definition will then limit your code to use of the RtlStringCbxxx functions.

#define STRSAFE_NO_CCH_FUNCTIONS
#include <strsafe.h>

While it may seem like a hassle to learn a new set of functions to replace the old c-runtime functions that we have grown to love, it really is in your best interest to change.   The string safe functions provided in "strsafe.h" provide you with a robust set of functions which will make your driver safer from buffer overruns and silly string mistakes that we all tend to make.