Panda3D
Public Types | Public Member Functions | List of all members
DocumentSpec Class Reference

A descriptor that refers to a particular version of a document. More...

#include "documentSpec.h"

Public Types

enum  CacheControl { CC_allow_cache, CC_revalidate, CC_no_cache }
 
enum  RequestMode { RM_any, RM_equal, RM_newer, RM_equal_or_newer }
 

Public Member Functions

 DocumentSpec (const string &url)
 
 DocumentSpec (const URLSpec &url)
 
 DocumentSpec (const DocumentSpec &copy)
 
void clear_date ()
 Removes the last-modified date associated with the DocumentSpec, if there is one. More...
 
void clear_tag ()
 Removes the identity tag associated with the DocumentSpec, if there is one. More...
 
int compare_to (const DocumentSpec &other) const
 
CacheControl get_cache_control () const
 Returns the request mode of this DocumentSpec. More...
 
const HTTPDateget_date () const
 Returns the last-modified date associated with the DocumentSpec, if there is one. More...
 
RequestMode get_request_mode () const
 Returns the request mode of this DocumentSpec. More...
 
const HTTPEntityTagget_tag () const
 Returns the identity tag associated with the DocumentSpec, if there is one. More...
 
const URLSpecget_url () const
 Retrieves the URL of the DocumentSpec. More...
 
bool has_date () const
 Returns true if a last-modified date is associated with the DocumentSpec. More...
 
bool has_tag () const
 Returns true if an identity tag is associated with the DocumentSpec. More...
 
bool input (istream &in)
 Can be used to read in the DocumentSpec from a stream generated either by output() or write(). More...
 
bool operator!= (const DocumentSpec &other) const
 
bool operator< (const DocumentSpec &other) const
 
void operator= (const DocumentSpec &copy)
 
bool operator== (const DocumentSpec &other) const
 
void output (ostream &out) const
 
void set_cache_control (CacheControl cache_control)
 Specifies what kind of cached value is acceptable for this document. More...
 
void set_date (const HTTPDate &date)
 Changes the last-modified date associated with the DocumentSpec. More...
 
void set_request_mode (RequestMode request_mode)
 Sets the request mode of this DocumentSpec. More...
 
void set_tag (const HTTPEntityTag &tag)
 Changes the identity tag associated with the DocumentSpec. More...
 
void set_url (const URLSpec &url)
 Changes the URL of the DocumentSpec without modifying its other properties. More...
 
void write (ostream &out, int indent_level=0) const
 

Detailed Description

A descriptor that refers to a particular version of a document.

This includes the URL of the document and its identity tag and last-modified dates.

The DocumentSpec may also be used to request a newer document than a particular one if available, for instance to refresh a cached document.

Definition at line 33 of file documentSpec.h.

Member Function Documentation

◆ clear_date()

void DocumentSpec::clear_date ( )
inline

Removes the last-modified date associated with the DocumentSpec, if there is one.

Definition at line 235 of file documentSpec.I.

References set_request_mode().

Referenced by get_date().

◆ clear_tag()

void DocumentSpec::clear_tag ( )
inline

Removes the identity tag associated with the DocumentSpec, if there is one.

Definition at line 188 of file documentSpec.I.

References set_date().

Referenced by get_tag().

◆ get_cache_control()

DocumentSpec::CacheControl DocumentSpec::get_cache_control ( ) const
inline

Returns the request mode of this DocumentSpec.

See set_cache_control().

Definition at line 328 of file documentSpec.I.

References input().

Referenced by set_cache_control().

◆ get_date()

const HTTPDate & DocumentSpec::get_date ( ) const
inline

Returns the last-modified date associated with the DocumentSpec, if there is one.

It is an error to call this if has_date() returns false.

Definition at line 223 of file documentSpec.I.

References clear_date(), and has_date().

Referenced by has_date(), and input().

◆ get_request_mode()

DocumentSpec::RequestMode DocumentSpec::get_request_mode ( ) const
inline

Returns the request mode of this DocumentSpec.

See set_request_mode().

Definition at line 290 of file documentSpec.I.

References set_cache_control().

Referenced by set_request_mode().

◆ get_tag()

const HTTPEntityTag & DocumentSpec::get_tag ( ) const
inline

Returns the identity tag associated with the DocumentSpec, if there is one.

It is an error to call this if has_tag() returns false.

The identity tag is set by the HTTP server to uniquely refer to a particular version of a document.

Definition at line 176 of file documentSpec.I.

References clear_tag(), and has_tag().

Referenced by has_tag(), and input().

◆ get_url()

const URLSpec & DocumentSpec::get_url ( ) const
inline

Retrieves the URL of the DocumentSpec.

Definition at line 138 of file documentSpec.I.

References set_tag().

Referenced by input(), and set_url().

◆ has_date()

bool DocumentSpec::has_date ( ) const
inline

Returns true if a last-modified date is associated with the DocumentSpec.

Definition at line 211 of file documentSpec.I.

References get_date().

Referenced by get_date(), input(), and set_date().

◆ has_tag()

bool DocumentSpec::has_tag ( ) const
inline

Returns true if an identity tag is associated with the DocumentSpec.

Definition at line 161 of file documentSpec.I.

References get_tag().

Referenced by get_tag(), input(), and set_tag().

◆ input()

bool DocumentSpec::input ( istream &  in)

Can be used to read in the DocumentSpec from a stream generated either by output() or write().

Returns true on success, false on failure.

Definition at line 60 of file documentSpec.cxx.

References get_date(), get_tag(), get_url(), has_date(), has_tag(), set_date(), and set_tag().

Referenced by get_cache_control().

◆ set_cache_control()

void DocumentSpec::set_cache_control ( DocumentSpec::CacheControl  cache_control)
inline

Specifies what kind of cached value is acceptable for this document.

Warning: some HTTP proxies may not respect this setting and may return a cached result anyway.

CC_allow_cache: the normal HTTP behavior; the server may return a cached value if it believes it is valid.

CC_revalidate: a proxy is forced to contact the origin server and verify that is cached value is in fact still valid before it returns it.

CC_no_cache: a proxy must not return its cached value at all, but is forced to go all the way back to the origin server for the official document.

The default mode is CC_allow_cache.

Definition at line 317 of file documentSpec.I.

References get_cache_control().

Referenced by get_request_mode().

◆ set_date()

void DocumentSpec::set_date ( const HTTPDate date)
inline

Changes the last-modified date associated with the DocumentSpec.

Definition at line 199 of file documentSpec.I.

References has_date().

Referenced by clear_tag(), and input().

◆ set_request_mode()

void DocumentSpec::set_request_mode ( DocumentSpec::RequestMode  request_mode)
inline

Sets the request mode of this DocumentSpec.

This is only relevant when using the DocumentSpec to generate a request (for instance, in HTTPChannel). This specifies whether the document request will ask the server for a newer version than the indicated version, or the exact version, neither, or either.

The possible values are:

RM_any: ignore date and tag (if specified), and retrieve any document that matches the URL. For a subrange request, if the document matches the version indicated exactly, retrieve the subrange only; otherwise, retrieve the entire document.

RM_equal: request only the precise version of the document that matches the particular date and/or tag exactly, if specified; fail if this version is not available.

RM_newer: request any document that is newer than the version indicated by the particular date and/or tag; fail if only that version (or older versions) are available.

RM_newer_or_equal: request any document that matches the version indicated by the particular date and/or tag, or is a newer version; fail if only older versions are available.

In any of the above, you may specify either or both of the last-modified date and the identity tag, whichever is known to the client.

The default mode is RM_any.

Definition at line 279 of file documentSpec.I.

References get_request_mode().

Referenced by clear_date().

◆ set_tag()

void DocumentSpec::set_tag ( const HTTPEntityTag tag)
inline

Changes the identity tag associated with the DocumentSpec.

Definition at line 149 of file documentSpec.I.

References has_tag().

Referenced by get_url(), and input().

◆ set_url()

void DocumentSpec::set_url ( const URLSpec url)
inline

Changes the URL of the DocumentSpec without modifying its other properties.

Normally this would be a strange thing to do, because the tag and date are usually strongly associated with the URL. To get a DocumentSpec pointing to a new URL, you would normally create a new DocumentSpec object.

Definition at line 128 of file documentSpec.I.

References get_url().


The documentation for this class was generated from the following files: