驱动开发之 UNICODE_STRING 总结

UNICODE_STRING:
typedef struct _UNICODE_STRING {
  USHORT  Length;     //UNICODE占用的内存字节数，个数*2；
  USHORT  MaximumLength;
  PWSTR  Buffer;
} UNICODE_STRING ,*PUNICODE_STRING;

参数定义：
Length-----buffer的字节长度，不包括终止符“NULL”
MaximumLength---buffer的的总的字节大小。Up to MaximumLength bytes may be written into the                  buffer without trampling memory.
Buffer---Pointer to a wide-character string指向宽字符串的指针

ANSI_STRING：
typedef struct _STRING {
  USHORT  Length;
  USHORT  MaximumLength;
  PCHAR  Buffer;
} STRING, *PANSI_STRING;

实例：
WCAHR temp[] = L"Hello World！";   //定义宽字符串
UNICODE_STRING str ;
str.Buffer = temp;
str.Length  = wcslen(temp)*sizeof(WCHAR)   //这个长度为UNICODE字符串所占用的字节数，即字符的个数乘以每个字符所占的字节数。通常为： 字符个数*2 ； 
    当使用UNICODE_STRING 时，一定要手动设置UNICODE_STRING 的Length和MaximumLength 成员，不要想当然的认为设置了Buffer后，Length和MaximumLength 成员就会根据Buffer被自动设置。由其是当自己写的函数用UNICODE_STRING作为参数返回时，一定要设置Length和MaximumLength 成员，不然很可能得到非预期结果。
 当应用程序与驱动通信时，一般应用程序传入的字符串为ANSI，所以在驱动中应先定义ANSI_STRING，然后再使用RtlAnsiStringToUnicodeString 将其转换成UNICODE_STRING，作为后用。例：
ANSI_STRING  str_a;
UNICODE_STRING  str_u;
WCHAR buf_u[1024] = L"";
str_a.Buffer = InputBuffer ;  //InputBuffer 为输入缓冲区地址
str_a.Length = str_a.MaximumLength = strlen(InputBuffer);
//开辟UNICODE内存空间
str_u.Buffer = buf_u;
str_u.Length = str_u.MaximumLength = strlen(InputBuffer) * sizeof(WCHAR);
RtlAnsiStringToUnicodeString(&str_u, &str_a , TRUE);
........
........
//当RtlAnsiStringToUnicodeString第三个参数为TRUE时，要用RtlFreeUnicodeString释放临时的UNICODE_STRING
RtlFreeUnicodeString(&str_u);
拼接UNICODE_STRING
  当拼接UNICODE_STRING 时，注意目标UNICODE的Length为当前UNICODE中存储字符的字节数。如：
WCHAR str1[] = L"12345";
UNICODE_STRING str2;
str2.Buffer = ExAllocatePool(NonPagedPool, wcslen(str1)*sizeof(WCHAR))
str2.Length = 0;
str2.MaximumLength = wcslen(str1)*sizeof(WCHAR);

RtlAppendUnicodeToString(&str2, str1);

 UNICODE 和 ExAllocatePool

内核在UNICODE拼接或其他临时操作时，经常使用ExAllocatePool动态分配UNICODE的Buffer，简单情况：
UNICODE_STRING str;
str.Buffer = ExAllocatePool(NonPagedPool, 50*sizeof(WCHAR));
str.Length = 0;
str.MaximumLength = 50*sizeof(WCHAR);
但若是定义一个UNICODE的指针，则如何初始化UNICODE ？ 
PUNICODE_STRING pStr;
因为定义了一个指针，但指针目前并没有指向可用的内存地址，故先分配一块内存（NonPagedPool），让pStr指向这块内存。
pStr = ExAllocatePool(NonPagedPool, 50*sizeof(WCHAR));
接着初始化成员：
pStr.Length = 0;

pStr.MaximumLength = ???;

如何初始化Buffer ？
    因为UNICODE_STRING 是一个数据结构，我们申请一块内存来存储这个数据结构，所以这块内存不仅存储了Buffer这个我们最关心的字符串，而且还储存这个数据结构，即Length 、 MaximumLength 和 Buffer （指针）成员。因为pStr是这块内存的起始地址，所以：
&pStr.Length = (USHORT*)pStr
&pStr.MaximumLength = (USHORT*)pStr + 1
&pStr.Buffer = (USHORT*)pStr + 2
所以得：
pStr.Buffer = (WCHAR*)((USHORT*)pStr + 2 + 2 )  因为一个USHORT占2个字节，一个指针占4个字节。这时得出，pStr.MaximumLength =  50*sizeof(WCHAR) - (2+2+4);
（注意，以上是为了方便观察特意写成赋值形式，但在编译器中并不适用，因为=左边得为左值。）

 整体：
PUNICODE_STRING pStr;
pStr = ExAllocatePool(NonPagedPool, 50*sizeof(WCHAR));
pStr.Length = 0;

pStr.Buffer = (WCHAR*)( (USHORT*)pStr + 2 + 2 ) ; 

总结：
    定义UNICODE_STRING 时，编译器在栈上自动分配了存储UNICODE_STRING这个数据结构的空间，我们唯一要做的就是给Buffer这个指针成员（指向）分配内存。
    而定义PUNICODE_STRING时，在堆上分配了一块内存，这块内存不仅存储了Buffer，而且还存储了UNICODE_STRING这个数据结构。所以定义为PUNICODE_STRING时，要比预期的字符串至少多8个字节，就因为此。
pStr.MaximumLength = 50*sizeof(WCHAR) - (2+2+4);
UNICODE_STRING在驱动应用比较多，其操作大致有如下几个：
（1）初始化，常见的初始化有两种方式：
1.调用RtlInitUnicodeString，该函数原型如下：
程序代码
VOID  RtlInitUnicodeString(
    IN OUT PUNICODE_STRING  DestinationString,
    IN PCWSTR  SourceString
);
该方法的实际原理是：将SourceString的宽字符串指针赋值给UNICODE_STRING的Buffer值，同时SourceString的长度值填入结构的Length域，默认的MaximumLength = Length + 2；
如：RtlInitUnicodeString(&ustrRegString,L"Hello");
2.采用动态分配内存的方式初始化，其调用方式如下：
程序代码
UNICODE_STRING ustr;
ustr.Length= 0;
ustr.MaximumLength = 256;
ustr.Buffer = (PWCHAR)ExAllocatePoolWithTag(NonPagedPool,256,MEM_TAG);  //MEM_TAG为自定义
这样就动态分配了一个存储空间给ustr。
（2）字符串连接
连接常见的就是将两个UNICODE_STRING或者将WCHAR_T的字符串连接起来
首先，将两个UNICODE_STRING连接起来，调用RtlAppendUnicodeStringToString函数实现，其原型如下：
程序代码
NTSTATUS  RtlAppendUnicodeStringToString(
    IN OUT PUNICODE_STRING  Destination,
    IN PUNICODE_STRING  Source
);
调用该函数的原理是将两者的字符串Buffer拼接起来，同时，更新对应的Length和MaxLength域。在调用的
过程中要注意Destination的MaxLength域，若MaxLength小于Destination和Source的Length域的和的时候，该函数调用不成功，返回0xC0000023，即缓冲区溢出错误。所以在调用该函数的时候，一定要确定Destination的MaxLength 域。
若将WCHAR_T字符串串接到UNICODE_STRING之后，则需要调用RtlAppendUnicodeToString，函数原型如下：
程序代码
NTSTATUS  RtlAppendUnicodeToString(
IN OUT PUNICODE_STRING  Destination,
IN PCWSTR  Source
);
该函数和上面函数并没有特别多的不一致，但该函数较上一个函数不同的地方就是不会出现缓冲区溢出的错误，也就是即使Destination的MaxLength域为0，也可以执行RtlAppendUnicodeToString的操作。
还有另外一个需要注明的地方，如果UNICODE_STRING是通过RtlInitUnicodeString初始化，那么不管调用什么函数，修改UNICODE_STRING值的时候，初始化使用的PCWSTR数组的值也会发生改变，因为他们指向的是同一个Buffer。
注上一例，备后用：
程序代码
UNICODE_STRING  ustrStr,ustrName;
ustrStr.Length = wcslen(strKey) * 2;
RtlAppendUnicodeToString(&ustrStr,strKey);
ustrStr.MaximumLength = 256;
RtlAppendUnicodeToString(&ustrStr,L"\\");
RtlAppendUnicodeStringToString(&ustrStr,&ustrName);
(3)字符串转换
转换目的可能涉及到中文显示的问题，如果简单的UNICODE_STRING转换为wchar_t或者char的形式，采用RtlCopyMemory的方式，因为UNICODE_STRING字符串并不一定以\0作为结束符，所以需要使用RtlCopyMemory，拷贝定长的字符串。
对于中文显示的问题，采用ANSI_STRING的方式进行输出。从UNICODE_STRING到ANSI_STRING转换，可以通过RtlUnicodeStringToAnsiString实现，其原型如下：
程序代码
NTSTATUS  RtlUnicodeStringToAnsiString(
    IN OUT PANSI_STRING  DestinationString,
    IN PUNICODE_STRING  SourceString,
    IN BOOLEAN  AllocateDestinationString
);
典型例子如下：
程序代码
UNICODE_STRING src;
ANSI_STRING dst;
RtlInitUnicodeString(&src,L”打印汉字”)；
RtlUnicodeStringToAnsiString(&dst,&src,TRUE);
DbgPrint(“%Z”,&dst);

RtlFreeAnsiString(&dst);

RtlInitUnicodeString与UNICODE_STRING的区别

UNICODE_STRING是一个结构.当你声明一个UNICODE_STRING时它的成员未初始化.而RtlInitUnicodeString是一个函数用来初始化一个UNICODE_STRING.
UNICODE_STRING
The UNICODE_STRING structure is used to define Unicode strings.
typedef struct _UNICODE_STRING {
USHORT Length;
USHORT MaximumLength;
PWSTR Buffer;
} UNICODE_STRING *PUNICODE_STRING;
Members
Length 
   The length in bytes of the string stored in Buffer. 
MaximumLength 
   The maximum length in bytes of Buffer. 
Buffer 
   Pointer to a buffer used to contain a string of wide characters. 
Headers
   Defined in ntdef.h. Include wdm.h or ntddk.h. 


Comments
The UNICODE_STRING structure is used to pass Unicode strings. Use RtlInitUnicodeString to initialize a UNICODE_STRING.
If the string is NULL-terminated, Length does not include the trailing NULL.

The MaximumLength is used to indicate the length of Buffer so that if the string is passed to a conversion routine such as RtlAnsiStringToUnicodeString the returned string does not exceed the buffer size.