StringCchPrintf、StringCchCopy、StringCchCat、StringCchLength

1、StringCchPrintf函数功能：

StringCchPrintf 函数用于把数据格式化写入到指定的缓冲区里，该函数要求提供目标缓冲区的大小，确保不会发生越界访问。
微软推荐使用该函数替代以下函数：

• sprintf，swprintf， _stprintf，wsprintf，wnsprintf，_snprintf， _snwprintf， _sntprintf

API 函数原型：

1. HRESULT StringCchPrintf(  _Out_  LPTSTR pszDest,  _In_   size_t cchDest,  _In_   LPCTSTR pszFormat,  _In_   ...);

参数解析：

参数	含义
pszDest	指定格式化数据将要写入的缓冲区
cchDest	1. 缓冲区大小 2. 应该设置足够大，以容纳字符串和结束标记（'\n'） 3. 最大允许的字符数是 STRSAFE_MAX_CCH
pszFormat	1. 格式化字符串 2. 与 pirntf 的格式化字符串一致
...	可变参数，参数的个数取决 pszFormat 参数

返回值：这个函数返回一个 HRESULT，而不是像 sprintf 一样返回存储在其目标缓冲区的字节数。建议您使用 SUCCEEDED 和 FAILED 宏来测试这个函数的返回值。
返回值可以是以下任意一个值：

返回代码	描述
S_OK	表示有足够的空间将拷贝到 pszDest，没有发生截断
STRSAFE_E_INVALID_PARAMETER	cchDest 的值为 0 或大于 STRSAFE_MAX_CCH
STRSAFE_E_INSUFFICIENT_BUFFER	1. 由于缓冲区空间不足而导致的复制失败 2. 结果被截断，当仍然包含'\0'结尾 3. 如果截断操作可以被接受，则不一定被看作是失败

2、StringCchCopy函数功能：

StringCchCopy 函数的功能是复制一个字符串到缓冲区。StringCchCopy 函数要求提供目标缓冲区的长度，以确保写入数据不会超出缓冲区的末尾。

微软推荐使用该函数替代以下函数：

• strcpy，wcscpy，_tcscpy，lstrcpy，StrCpy

API 函数原型：

1. HRESULT StringCchCopy( _Out_  LPTSTR pszDest,  _In_   size_t cchDest,  _In_   LPCTSTR pszSrc);

参数解析：

参数	含义
pszDest	缓冲区，用于接收拷贝过来的字符串
cchDest	1. 目标缓冲区的大小（字符个数） 2. 该值必须大于或等于 pszSrc + 1（待拷贝字符串的字符+'\0'） 3. 这个数不能超过 STRSAFE_MAX_CCH
pszSrc	待拷贝的字符串

返回值：这个函数返回一个 HRESULT，而不是指向缓冲区的指针。我们强烈建议您使用 SUCCEEDED 和 FAILED 宏来测试这个函数的返回值。
返回值可以是以下任意一个值：

返回代码	描述
S_OK	字符串正常拷贝
STRSAFE_E_INVALID_PARAMETER	1. cchDest 参数的值为 0 2. cchDest 参数的值大于 STRSAFE_MAX_CCH
STRSAFE_E_INSUFFICIENT_BUFFER	1. 因缓冲区空间不足导致失败 2. 结果被截断，当仍然包含'\0'结尾 3. 如果截断操作可以被接受，则不一定被看作是失败

3、StringCchCat函数功能：
StringCchCat 函数的功能是将一个字符串拼接到另一个字符串。StringCchCat 函数要求提供目标缓冲区的长度，以确保写入数据不会超出缓冲区的末尾。
微软推荐使用该函数替代以下函数：

• strcat，wcscat， _tcsat，lstrcat，StrCat，StrCatBuff

API 函数原型：

1. HRESULT StringCchCat(  _Inout_  LPTSTR pszDest,  _In_     size_t cchDest,  _In_     LPCTSTR pszSrc);

参数解析：

参数	含义
pszDest	1. 目标缓冲区，同时包含第一个字符串 2. 该缓冲区必须大于或等于 pszDest + pszSrc + 1（两个字符串的字符总和+'\0'）
cchDest	1. 目标缓冲区的大小（字符个数） 2. 该值必须大于或等于 pszDest + pszSrc + 1（两个字符串的字符总和+'\0'） 3. 这个数不能超过 STRSAFE_MAX_CCH
pszSrc	第二个字符串

返回值：这个函数返回一个 HRESULT，而不是拼接好的字符串指针。强烈建议您使用 SUCCEEDED 和 FAILED 宏来测试这个函数的返回值。
返回值可以是以下任意一个值：

返回代码	描述
S_OK	字符串正常拼接
STRSAFE_E_INVALID_PARAMETER	1. cchDest 参数的值为 0  2. cchDest 参数的值大于 STRSAFE_MAX_CCH 3. 目标缓冲区空间已满
STRSAFE_E_INSUFFICIENT_BUFFER	1. 因缓冲区空间不足导致失败 2. 结果被截断，当仍然包含'\0'结尾 3. 如果截断操作可以被接受，则不一定被看作是失败

4、StringCchLength函数功能：

StringCchLength 函数用于确定字符串是否超过了规定的长度，以字符为计算单位。

微软推荐使用该函数替代以下函数：

• strlen, wcslen, _tcslen

API 函数原型：

1. HRESULT StringCchLength(  _In_   LPCTSTR psz,  _In_   size_t cchMax,  _Out_  size_t *pcch);

参数解析：

参数	含义
psz	指向待检查的字符串
cchMax	1. psz 参数里最大允许的字符数量，包括'\0' 2. 这个数不能超过 STRSAFE_MAX_CCH
pcch	1. psz 参数指向字符串的字符个数，不包括'\0' 2. 这个值只有在 psz 指针不为 NULL，且函数成功时有效

返回值：这个函数返回一个 HRESULT，而不是指定字符串的字符个数。强烈建议您使用 SUCCEEDED 和 FAILED 宏来测试这个函数的返回值。
返回值可以是以下任意一个值：

返回代码	描述
S_OK	psz 指向的字符串不为空，且字符串的长度（包括'\0'）小于等于 cchMax
STRSAFE_E_INVALID_PARAMETER	1. psz 指向空字符串 2. cchMax 的值大于STRSAFE_MAX_CCH 3. psz 指向的字符串的字符个数超过 cchMax

备注：
1. 对比 StringCchLength 所替代的函数，StringCchLength 是可以使你的代码正确处理缓存区的一个附加功能。因为小的缓冲处理会牵连很多安全问题，例如缓存区溢出
2.所有函数需要添加头文件：strsafe.h