1、StringCchPrintf函数功能:
StringCchPrintf 函数用于把数据格式化写入到指定的缓冲区里,该函数要求提供目标缓冲区的大小,确保不会发生越界访问。
微软推荐使用该函数替代以下函数:
- sprintf,swprintf, _stprintf,wsprintf,wnsprintf,_snprintf, _snwprintf, _sntprintf
API 函数原型:
- 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 函数原型:
- 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 函数原型:
- 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 函数原型:
- 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