描述
WinHttpAddRequestHeaders函数向HTTP请求句柄添加一个或多个HTTP请求标头。
C / C ++语法
BOOL WinHttpAddRequestHeaders( HINTERNET hRequest, LPCWSTR pwszHeaders, DWORD dwHeadersLength, DWORD dwModifiers ); |
PowerBASIC 语法
FUNCTION WinHttpAddRequestHeaders ( _ BYVAL hRequest AS DWORD, _ BYREF pwszHeaders AS WSTRINGZ, _ BYVAL dwHeadersLength AS DWORD, _ BYVAL dwModifiers AS DWORD _ ) AS LONG |
参数
hRequest
[in]通过调用WinHttpOpenRequest函数返回的HINTERNET句柄。
pwszHeaders
[in]指向一个以null结尾的Unicode字符串的指针,该字符串包含附加到请求的标题。每个标题必须由回车/换行符(CR / LF)终止。
dwHeadersLength
[in]一个无符号长整数值,包含pwszHeaders的字符长度。如果此参数为-1 &(&HFFFFFFFF),则该函数假定pwszHeaders为零终止(ASCIIZ),并计算长度。
dwModifiers
[in]一个无符号长整数值,包含用于修改此函数语义的标志。可以是以下一个或多个标志。
WINHTTP_ADDREQ_FLAG_ADD
如果标题不存在,则添加标题。与WINHTTP_ADDREQ_FLAG_REPLACE一起使用。
WINHTTP_ADDREQ_FLAG_ADD_IF_NEW
仅当标题不存在时添加标题;否则返回错误。
WINHTTP_ADDREQ_FLAG_COALESCE
合并同名的标题。
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA
使用逗号合并相同名称的标题。例如,使用此标志添加“Accept:text / *”,后跟“Accept:audio / *”会导致单个标题“Accept:text / *,audio / *”。这导致找到的第一个标题被合并。调用应用程序必须确保关于合并和单独标头的内聚方案。
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON
使用分号合并相同名称的标题。
WINHTTP_ADDREQ_FLAG_REPLACE
替换或删除标题。如果标头值为空,并找到标题,则将其删除。如果值不为空,则将被替换。
返回值
如果成功返回TRUE,否则返回FALSE。有关扩展错误信息,请调用GetLastError.返回的错误代码有:
错误代码 |
描述 |
ERROR_WINHTTP_INCORRECT_HANDLE_STATE |
所请求的操作不能执行,因为提供的句柄不在正确的状态。 |
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE |
提供的手柄类型对于此操作是不正确的。 |
ERROR_WINHTTP_INTERNAL_ERROR |
发生内部错误。 |
ERROR_NOT_ENOUGH_MEMORY |
没有足够的内存来完成请求的操作。(Windows错误代码) |
备注
标头会跨重定向传输。这可能是一个安全问题。为避免在发生重定向时传送标题,请在重定向发生时使用WINHTTP_STATUS_CALLBACK回调来更正特定的标题。
即使在异步模式下使用WinHTTP(即,当WinHttpOpen中设置了WINHTTP_FLAG_ASYNC时),此函数同步运行。返回值表示成功或失败。要获取扩展错误信息,请调用GetLastError.
WinHttpAddRequestHeaders函数将附加的免费格式标头附加到HTTP请求句柄中,并由需要对发送到HTTP服务器的确切请求进行详细控制的复杂客户端使用。
使用此函数添加的请求标头的名称和值将被验证。标题必须形成良好。有关有效的HTTP标头的更多信息,请参阅RFC 2616.如果使用无效头,则此函数失败,GetLastError返回ERROR_INVALID_PARAMETER.无法添加无效标题。
对于基本的WinHttpAddRequestHeaders,应用程序可以在单个缓冲区中传入多个头文件。如果应用程序删除或替换标题,则pwszHeaders中只能提供一个标头。
在发送请求之前,应用程序还可以使用WinHttpSendRequest向HTTP请求句柄添加附加标头。