Skip to content

ihttpcachepolicy-getvarybyquerystrings-method.md

Latest commit

 

History

History
64 lines (45 loc) · 5.42 KB

ihttpcachepolicy-getvarybyquerystrings-method.md

File metadata and controls

64 lines (45 loc) · 5.42 KB
title IHttpCachePolicy::GetVaryByQueryStrings Method
description Describes the IHttpCachePolicy::GetVaryByQueryStrings method and details its syntax, parameters, return value, remarks, examples, and requirements.
ms.date 10/07/2016
ms.assetid 44714859-9692-7881-1978-662089aed17a

IHttpCachePolicy::GetVaryByQueryStrings Method

Returns the custom query values for the cache policy.

Syntax

virtual PCSTR GetVaryByQueryStrings(  
   VOID  
) const = 0;

Parameters

This method takes no parameters.

Return Value

A null-terminated PCSTR that contains a comma-delimited list of custom query values.

Remarks

CHttpModule derived classes that register for request or response events receive an IHttpContext pointer as a parameter on the corresponding virtual method. Call the IHttpContext::GetResponse method, then the IHttpResponse::GetCachePolicy method, and finally the GetVaryByQueryStrings method to retrieve the custom query values.

GetVaryByQueryStrings 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 query data. During the construction of an implementer, this buffer is initialized to empty. If the supplied parameter is NULL, the AppendVaryByQueryString method immediately returns S_OK. Otherwise, the buffer is expanded to hold a copy of the parameter, including the null-termination character, plus 1 if the buffer is not currently empty. If the buffer is not empty, the "," character is appended to the buffer. Finally, the contents of the parameter, including the null-termination character, are appended to the buffer.

  • GetVaryByQueryStrings returns the comma-delimited list of custom query values set through successive calls to AppendVaryByQueryString.

Notes for Implementers

IHttpCachePolicy implementers are responsible for memory management with this data; therefore, IHttpCachePolicy implementers that use dynamic memory allocation must release or call delete on the PCSTR pointer when it is no longer needed.

Notes for Callers

IHttpCachePolicy implementers are responsible for memory management with this data; therefore, IHttpCachePolicy clients must not release or call delete on the returned PCSTR pointer when this data is no longer needed. Furthermore, clients must not cast this data to a pointer that is not a const or change the state of the memory referenced by this PCSTR, because an access violation will be thrown or the data will become invalid.

Example

The following code example demonstrates how to create a global module that listens for RQ_BEGIN_REQUEST and RQ_SEND_RESPONSE events. The module then retrieves an IHttpCachePolicy pointer and writes variable query information to the response stream.

[!code-cppIHttpCachePolicy#8]

For more information about how to create and deploy a native DLL module, see Walkthrough: Creating a Request-Level HTTP Module By Using Native Code.

The above code writes data that is similar to the following to the response stream:

Vary-by-Query:

You can optionally compile the code by using the __stdcall (/Gz) calling convention instead of explicitly declaring the calling convention for each function.

Requirements

Type Description
Client - IIS 7.0 on [!INCLUDEwinvista]
- IIS 7.5 on Windows 7
- IIS 8.0 on Windows 8
- IIS 10.0 on Windows 10
Server - IIS 7.0 on [!INCLUDEwinsrv2008]
- 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
Product - IIS 7.0, IIS 7.5, IIS 8.0, IIS 8.5, IIS 10.0
- [!INCLUDEiisexp75], [!INCLUDEiisexp80], [!INCLUDEiisexp100]
Header Httpserv.h

See Also

IHttpCachePolicy Interface