IHttpCachePolicy::SetVaryByValue Method

Article
03/09/2018

Sets the variable value for the cache policy.

Syntax

virtual HRESULT SetVaryByValue(  
   PCSTR pszValue  
) = 0;

Parameters

pszValue
A pointer to a null-terminated string that contains the custom value 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 the operation was successful.
E_INVALIDARG	Indicates that `pszValue` is NULL.
ERROR_ARITHMETIC_OVERFLOW	Indicates that the length of `pszValue` exceeds a maximum limit.

Remarks

CHttpModule derived classes that register for request or response events receive an IHttpContext pointer as a parameter on the corresponding virtual method. To set the variable value, call the IHttpContext::GetResponse method, the IHttpResponse::GetCachePolicy method, and finally the SetVaryByValue method.

SetVaryByValue 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 data. During the construction of an implementer, this buffer is initialized to empty.
SetVaryByValue returns E_INVALIDARG immediately if the pszValue parameter is NULL. Otherwise, the internal buffer is expanded, if necessary, to hold the contents of pszValue and the null-termination character. Then pszValue, followed by the null-termination character, is copied into this buffer. Any data in the buffer before the call to SetVaryByValue is overwritten, if necessary, during the call to SetVaryByValue.

Notes for Implementers

IHttpCachePolicy implementers are responsible for copying the pszValue parameter into a buffer, because the data associated with the pszValue parameter is not guaranteed to be valid after the call to SetVaryByValue.

Notes for Callers

IHttpCachePolicy clients are responsible for passing a null-terminated string to the SetVaryByValue method. Clients are also responsible for disposing of pszValue after the call to SetVaryByValue, because IHttpCachePolicy implementers copy pszValue into an internal buffer.

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