IHttpCachePolicy::AppendVaryByHeader Method
Appends the header value to the cache policy.
Syntax
virtual HRESULT AppendVaryByHeader(
PCSTR pszHeader
) = 0;
Parameters
pszHeader
A pointer to a null-terminated string that contains the custom header to append.
-or-
NULL.
Return Value
An HRESULT. Possible values include, but are not limited to, those in the following table.
| Value | Description |
|---|---|
| S_OK | Indicates that pszHeader is NULL.-or- Indicates that pszHeader is appended to the variable header list. |
| ERROR_NOT_ENOUGH_MEMORY | Indicates that heap memory is exhausted. |
| E_FAIL | Indicates that the operation failed. |
Remarks
CHttpModule derived classes that register for request or response events receive an IHttpContext pointer as a parameter on the corresponding virtual method. To append a custom header, call the IHttpContext::GetResponse method, the IHttpResponse::GetCachePolicy method, and finally the AppendVaryByHeader method.
AppendVaryByHeader behavior depends on implementation. You should use the following information as a guideline, but it may not be correct in all scenarios:
The current default implementer of the IHttpCachePolicy interface declares a private buffer that contains variable header data. During the construction of an implementer, this buffer is initialized to empty. Every time AppendVaryByHeader is called, AppendVaryByHeader immediately returns S_OK if the pszHeader parameter is NULL. Otherwise, the buffer is expanded to hold a copy of pszHeader, including the null-termination character, plus 1 if the buffer is not currently empty. Then, if the buffer is not empty, the ',' character is appended to the buffer. Finally, the contents of pszHeader, including the null-termination character, are appended to the buffer.
Notes for Implementers
IHttpCachePolicy implementers are responsible for copying the pszHeader parameter into a buffer, because the data associated with pszHeader is not guaranteed to be valid after the call to AppendVaryByHeader.
Notes for Callers
IHttpCachePolicy clients are responsible for passing either a NULL pszHeader parameter or a null-terminated string to the AppendVaryByHeader method. Clients are also responsible for disposing of pszHeader after the call to AppendVaryByHeader, because IHttpCachePolicy implementers copy pszHeader into an internal buffer.
The internal buffer used by the default IHttpCachePolicy implementer is a comma-delimited string of custom headers. Therefore, pszHeader must not include the ',' character.
Requirements
| Type | Description |
|---|---|
| Client | - IIS 7.0 on Windows Vista - IIS 7.5 on Windows 7 - IIS 8.0 on Windows 8 - IIS 10.0 on Windows 10 |
| Server | - IIS 7.0 on Windows Server 2008 - IIS 7.5 on Windows Server 2008 R2 - IIS 8.0 on Windows Server 2012 - IIS 8.5 on Windows Server 2012 R2 - IIS 10.0 on Windows Server 2016 Technical Preview |
| Product | - IIS 7.0, IIS 7.5, IIS 8.0, IIS 8.5, IIS 10.0 - IIS Express 7.5, IIS Express 8.0, IIS Express 10.0 |
| Header | Httpserv.h |