Windows Safe String （StrSafe库） 简介

原始MSDN连接：

Url0, System Requirement WXP SP2 or Above, WSVR 2003 SP1 or Above:

http://msdn.microsoft.com/en-us/library/ms647466(v=vs.85) 

Url1, System Requirement WCE 5.0 or Above:

http://msdn.microsoft.com/en-us/library/ms861501.aspx

一、背景

许多系统安全问题都是由于糟糕的缓冲区操作和缓冲区溢出造成的。糟糕的缓冲区操作通常是和字符串操作关联的。C/C++ 运行库提供的标准字符串操作函数（strcat, strcpy, sprintf等等）并不会阻止写缓冲区越界的行为。

基于以上的原因，Windows实现了一个安全的字符串操作库，用以替代C/C++运行库的标准字符串操作库以及Windows自己对应的实现版本（lstrcat，StrCat，StrCatBuff等等）。

二、StrSafe函数库概述

StrSafe库函数的优点包括：

- 目的缓冲区的大小总是作为参数被提供给函数，以确保函数不会写缓冲区越界；

- 缓冲区被保证以null结尾，即便是字符串被截断的情况下；

- 所有的函数返回一个HRESULT值，并且返回值只有唯一的正确码（S_OK）；

- 每个函数都有分别有个一个“以字符个数计数”（“cch”）和一个以字节个数计数（“cb”）的版本。

- 大多数的函数都有一个扩展的版本（“Ex”）提供些更高阶的功能。

使用方法：

（1）首先包含头文件, #include <strsafe>

（2）在包含“strsafe.h”头文件之前，定义宏STRSAFE_LIB,则所有的函数都将从库中导出。如果未定义该宏（以及未定义STRSAFE_LIB_IMPL）
p.s. 这几个函数 StringCbGets, StringCbGetsEx, StringCchGets, 和 StringCchGetsEx 必须使用内联函数版本。

（3）当你包含了“strsafe.h”头文件,那些被strsafe.h取代的函数（C/C++运行库的标准字符串操作库以及Windows自己对应的实现版本）将会被弃用，试图使用这些函数可能会导致编译错误，其提示你去使用新的安全版本的字符串函数。如果关闭这个功能，则在包含“strsafe.h”头文件前，定义宏STRSAFE_NO_DEPRECATE

#define STRSAFE_NO_DEPRECATE

#include <strsafe>

（4）如果只允许以字符个数计数的函数版本，则在包含“strsafe.h”之前，定义宏STRSAFE_NO_CB_FUNCTIONS

#define STRSAFE_NO_CB_FUNCTIONS

#include <strsafe>

（5）如果只允许以字节个数计数的函数版本，则在包含“strsafe.h”之前，定义宏STRSAFE_NO_CCH_FUNCTIONS

#define STRSAFE_NO_CCH_FUNCTIONS

#include <strsafe>

P.S. 不能同时定义宏STRSAFE_NO_CB_FUNCTION和STRSAFE_NO_CCH_FUNCTIONS。

（6）支持的最大字符串长度 2,147,483,647 个字符,不管是ANSI和UNICODE

#define STRSAFE_MAX_CCH    2147483647    // max # of characters we support (same as INT_MAX)

（7）函数的返回值说明

返回值都是一个HRESULT值，有以下三个可能的值：

- S_OK，源字符串的数据都被成功提前，没有截取的行为，目的缓冲区以null结尾。

- STRSAFE_E_INVALID_PARAMETER，参数非法，不同的函数请参照MSDN了解细节。

- STRSAFE_E_INSUFFICIENT_BUFFER，有截断行为，有些情况下，这是可以接受的，可以不算做是失败

建议使用宏SUCCEEDED和FAILED去判断函数的返回值是否成功。

三、StrSafe函数库函数列表

（1）以字符计数的函数版本以及其对应的取代品

Function

Replaces

StringCchCat

StringCchCatEx

strcat, wcscat, _tcsat

lstrcat

StrCat

StrCatBuff

StringCchCatN

StringCchCatNEx

strncat

StrNCat

StringCchCopy

StringCchCopyEx

strcpy, wcscpy, _tcscpy

lstrcpy

StrCpy

StringCchCopyN

StringCchCopyNEx

strncpy, wcsncpy, _tcsncpy

StringCchGets

StringCchGetsEx

gets, _getws, _getts

StringCchPrintf

StringCchPrintfEx

sprintf, swprintf, _stprintf

wsprintf

wnsprintf

_snprintf, _snwprintf, _sntprintf

StringCchVPrintf

StringCchVPrintfEx

vsprintf, vswprintf, _vstprintf

vsnprintf, _vsnwprintf, _vsntprintf

wvsprintf

wvnsprintf

,

StringCchLength

strlen, wcslen, _tcslen

（2）以字节计数的函数版本以及其对应的取代品

Function

Replaces

StringCbCat

StringCbCatEx

strcat, wcscat, _tcsat

lstrcat

StrCat

StrCatBuff

StringCbCatN

StringCbCatNEx

strncat

StrNCat

StringCbCopy

StringCbCopyEx

strcpy, wcscpy, _tcscpy

lstrcpy

StrCpy

StringCbCopyN

StringCbCopyNEx

strncpy, wcsncpy, _tcsncpy

StringCbGets

StringCbGetsEx

gets, _getws, _getts

StringCbPrintf

StringCbPrintfEx

sprintf, swprintf, _stprintf

wsprintf

wnsprintf

_snprintf, _snwprintf, _sntprintf

StringCbVPrintf

StringCbVPrintfEx

vsprintf, vswprintf, _vstprintf

vsnprintf, _vsnwprintf, _vsntprintf

wvsprintf

wvnsprintf

StringCbLength

strlen, wcslen, _tcslen