# HTTPChannel

from pandac.PandaModules import HTTPChannel

Class : HTTPChannel
Description : A single channel of communication from an HTTPClient. This is similar to the concept of a 'connection', except that HTTP is technically connectionless; in fact, a channel may represent one unbroken connection or it may transparently close and reopen a new connection with each request.
A channel is conceptually a single thread of I/O. One document at a time may be requested using a channel; a new document may (in general) not be requested from the same HTTPChannel until the first document has been fully retrieved.

## Inheritance:

HTTPChannel: VirtualFile
VirtualFile: TypedReferenceCount
TypedReferenceCount: TypedObject ReferenceCount
TypedObject: MemoryBase
MemoryBase:
ReferenceCount: MemoryBase

## Methods of HTTPChannel:

beginConnectTo
beginGetDocument
beginGetHeader
beginGetSubdocument
beginPostForm
clearExtraHeaders
connectTo
deleteDocument
downloadToFile
downloadToRam
getAllowProxy
getBlockingConnect
getBytesDownloaded
getBytesRequested
getClassType
getConnection
getConnectTimeout
getDocument
getDocumentSpec
getDownloadThrottle
getFirstByteDelivered
getFirstByteRequested
getHeader
getHeaderValue
getHttpTimeout
getHttpVersion
getHttpVersionString
getLastByteDelivered
getLastByteRequested
getMaxBytesPerSecond
getMaxUpdatesPerSecond
getNumRedirectTrail
getOptions
getPersistentConnection
getProxyRealm
getProxyTunnel
getRedirect
getRedirectTrail
getStatusCode
getStatusString
getSubdocument
getTrace
getUrl
getWwwRealm
isConnectionReady
isDownloadComplete
isFileSizeKnown
isValid
postForm
preserveStatus
putDocument
readBody
reset
run
sendExtraHeader
setAllowProxy
setBlockingConnect
setConnectTimeout
setDownloadThrottle
setExpectedFileSize
setHttpTimeout
setMaxBytesPerSecond
setMaxUpdatesPerSecond
setPersistentConnection
setProxyTunnel
writeHeaders

## Methods of VirtualFile:

closeReadFile
getClassType
getFilename
getFileSize
getFileSystem
getOriginalFilename
getTimestamp
isDirectory
isRegularFile
ls
lsAll
openReadFile
output
readFile
scanDirectory

## Methods of TypedReferenceCount:

getClassType

## Methods of TypedObject:

getClassType
getType
getTypeIndex
isExactType
isOfType

## Methods of ReferenceCount:

getClassType
getRefCount
ref
testRefCountIntegrity
testRefCountNonzero
unref

## Constants in HTTPChannel:

SCIncomplete | (StatusCode)
SCInternalError | (StatusCode)
SCNoConnection | (StatusCode)
SCTimeout | (StatusCode)
SCLostConnection | (StatusCode)
SCNonHttpResponse | (StatusCode)
SCInvalidHttp | (StatusCode)
SCSocksInvalidVersion | (StatusCode)
SCSocksNoAcceptableLoginMethod | (StatusCode)
SCSocksRefused | (StatusCode)
SCSocksNoConnection | (StatusCode)
SCSslInternalFailure | (StatusCode)
SCSslNoHandshake | (StatusCode)
SCHttpErrorWatermark | (StatusCode)
SCSslInvalidServerCertificate | (StatusCode)
SCSslUnexpectedServer | (StatusCode)
SCDownloadOpenError | (StatusCode)
SCDownloadWriteError | (StatusCode)
SCDownloadInvalidRange | (StatusCode)

beginConnectTo void HTTPChannel::begin_connect_to(DocumentSpec const &url); Description: Begins a non-blocking request to establish a direct connection to the server and port indicated by the URL. No HTTP requests will be issued beyond what is necessary to establish the connection. When run() has finished, you may call is_connection_ready() to determine if the connection was successfully established. If successful, the connection may then be taken to use for whatever purposes you like by calling get_connection(). This establishes a nonblocking I/O socket. Also see connect_to().

beginGetDocument void HTTPChannel::begin_get_document(DocumentSpec const &url); Description: Begins a non-blocking request to retrieve a given document. This method will return immediately, even before a connection to the server has necessarily been established; you must then call run() from time to time until the return value of run() is false. Then you may check is_valid() and get_status_code() to determine the status of your request. If a previous request had been pending, that request is discarded.

beginGetHeader void HTTPChannel::begin_get_header(DocumentSpec const &url); Description: Begins a non-blocking request to retrieve a given header. See begin_get_document() and get_header().

beginGetSubdocument void HTTPChannel::begin_get_subdocument(DocumentSpec const &url, unsigned int first_byte, unsigned int last_byte); Description: Begins a non-blocking request to retrieve only the specified byte range of the indicated document. If last_byte is 0, it stands for the last byte of the document. When a subdocument is requested, get_file_size() and get_bytes_downloaded() will report the number of bytes of the subdocument, not of the complete document.

beginPostForm void HTTPChannel::begin_post_form(DocumentSpec const &url, string const &body); Description: Posts form data to a particular URL and retrieves the response, all using non-blocking I/O. See begin_get_document() and post_form(). It is important to note that you *must* call run() repeatedly after calling this method until run() returns false, and you may not call any other document posting or retrieving methods using the HTTPChannel object in the interim, or your form data may not get posted.

clearExtraHeaders void HTTPChannel::clear_extra_headers(void); Description: Resets the extra headers that were previously added via calls to send_extra_header().

connectTo bool HTTPChannel::connect_to(DocumentSpec const &url); Description: Establish a direct connection to the server and port indicated by the URL, but do not issue any HTTP requests. If successful, the connection may then be taken to use for whatever purposes you like by calling get_connection(). This establishes a blocking I/O socket. Also see begin_connect_to().

deleteDocument bool HTTPChannel::delete_document(DocumentSpec const &url); Description: Requests the server to remove the indicated URL.

downloadToFile bool HTTPChannel::download_to_file(Filename const &filename, bool subdocument_resumes = (1)); Description: Specifies the name of a file to download the resulting document to. This should be called immediately after get_document() or begin_get_document() or related functions. In the case of the blocking I/O methods like get_document(), this function will download the entire document to the file and return true if it was successfully downloaded, false otherwise. In the case of non-blocking I/O methods like begin_get_document(), this function simply indicates an intention to download to the indicated file. It returns true if the file can be opened for writing, false otherwise, but the contents will not be completely downloaded until run() has returned false. At this time, it is possible that a communications error will have left a partial file, so is_download_complete() may be called to test this. If subdocument_resumes is true and the document in question was previously requested as a subdocument (i.e. get_subdocument() with a first_byte value greater than zero), this will automatically seek to the appropriate byte within the file for writing the output. In this case, the file must already exist and must have at least first_byte bytes in it. If subdocument_resumes is false, a subdocument will always be downloaded beginning at the first byte of the file.

downloadToRam bool HTTPChannel::download_to_ram(Ramfile *ramfile, bool subdocument_resumes = (1)); Description: Specifies a Ramfile object to download the resulting document to. This should be called immediately after get_document() or begin_get_document() or related functions. In the case of the blocking I/O methods like get_document(), this function will download the entire document to the Ramfile and return true if it was successfully downloaded, false otherwise. In the case of non-blocking I/O methods like begin_get_document(), this function simply indicates an intention to download to the indicated Ramfile. It returns true if the file can be opened for writing, false otherwise, but the contents will not be completely downloaded until run() has returned false. At this time, it is possible that a communications error will have left a partial file, so is_download_complete() may be called to test this. If subdocument_resumes is true and the document in question was previously requested as a subdocument (i.e. get_subdocument() with a first_byte value greater than zero), this will automatically seek to the appropriate byte within the Ramfile for writing the output. In this case, the Ramfile must already have at least first_byte bytes in it.

getAllowProxy bool HTTPChannel::get_allow_proxy(void) const; Description: If this is true (the normal case), the HTTPClient will be consulted for information about the proxy to be used for each connection via this HTTPChannel. If this has been set to false by the user, then all connections will be made directly, regardless of the proxy settings indicated on the HTTPClient.

getBlockingConnect bool HTTPChannel::get_blocking_connect(void) const; Description: If this flag is true, a socket connect will block even for nonblocking I/O calls like begin_get_document(), begin_connect_to(), etc. If false, a socket connect will not block for nonblocking I/O calls, but will block for blocking I/O calls (get_document(), connect_to(), etc.).

getBytesDownloaded unsigned int HTTPChannel::get_bytes_downloaded(void) const; Description: Returns the number of bytes downloaded during the last (or current) download_to_file() or download_to_ram operation(). This can be used in conjunction with get_file_size() to report the percent complete (but be careful, since get_file_size() may return 0 if the server has not told us the size of the file).

getBytesRequested unsigned int HTTPChannel::get_bytes_requested(void) const; Description: When download throttling is in effect (set_download_throttle() has been set to true) and non-blocking I/O methods (like begin_get_document()) are used, this returns the number of bytes "requested" from the server so far: that is, the theoretical maximum value for get_bytes_downloaded(), if the server has been keeping up with our demand. If this number is less than get_bytes_downloaded(), then the server has not been supplying bytes fast enough to meet our own download throttle rate. When download throttling is not in effect, or when the blocking I/O methods (like get_document(), etc.) are used, this returns 0.

getClassType static TypeHandle HTTPChannel::get_class_type(void); Undocumented function.

getConnection SocketStream *HTTPChannel::get_connection(void); Description: Returns the connection that was established via a previous call to connect_to() or begin_connect_to(), or NULL if the connection attempt failed or if those methods have not recently been called. This stream has been allocated from the free store. It is the user's responsibility to delete this pointer when finished with it.

getConnectTimeout double HTTPChannel::get_connect_timeout(void) const; Description: Returns the length of time, in seconds, to wait for a new nonblocking socket to connect. See set_connect_timeout().

getDocument bool HTTPChannel::get_document(DocumentSpec const &url); Description: Opens the named document for reading, if available. Returns true if successful, false otherwise.

getDocumentSpec DocumentSpec const &HTTPChannel::get_document_spec(void) const; Description: Returns the DocumentSpec associated with the most recent document. This includes its actual URL (following redirects) along with the identity tag and last-modified date, if supplied by the server. This structure may be saved and used to retrieve the same version of the document later, or to conditionally retrieve a newer version if it is available.

getDownloadThrottle bool HTTPChannel::get_download_throttle(void) const; Description: Returns whether the nonblocking downloads will be bandwidth-limited. See set_download_throttle().

getFirstByteDelivered unsigned int HTTPChannel::get_first_byte_delivered(void) const; Description: Returns the first byte of the file (that will be) delivered by the server in response to the current request. Normally, this is the same as get_first_byte_requested(), but some servers will ignore a subdocument request and always return the whole file, in which case this value will be 0, regardless of what was requested to get_subdocument().

getFirstByteRequested unsigned int HTTPChannel::get_first_byte_requested(void) const; Description: Returns the first byte of the file requested by the request. This will normally be 0 to indicate that the file is being requested from the beginning, but if the file was requested via a get_subdocument() call, this will contain the first_byte parameter from that call.

getHeader bool HTTPChannel::get_header(DocumentSpec const &url); Description: Like get_document(), except only the header associated with the document is retrieved. This may be used to test for existence of the document; it might also return the size of the document (if the server gives us this information).

getHeaderValue string HTTPChannel::get_header_value(string const &key) const; Description: Returns the HTML header value associated with the indicated key, or empty string if the key was not defined in the message returned by the server.

getHttpTimeout double HTTPChannel::get_http_timeout(void) const; Description: Returns the length of time, in seconds, to wait for the HTTP server to respond to our request. See set_http_timeout().

getHttpVersion HTTPEnum::HTTPVersion HTTPChannel::get_http_version(void) const; Description: Returns the HTTP version number returned by the server, as one of the HTTPClient enumerated types, e.g. HTTPClient::HV_11.

getHttpVersionString string const &HTTPChannel::get_http_version_string(void) const; Description: Returns the HTTP version number returned by the server, formatted as a string, e.g. "HTTP/1.1".

getLastByteDelivered unsigned int HTTPChannel::get_last_byte_delivered(void) const; Description: Returns the last byte of the file (that will be) delivered by the server in response to the current request. Normally, this is the same as get_last_byte_requested(), but some servers will ignore a subdocument request and always return the whole file, in which case this value will be 0, regardless of what was requested to get_subdocument().

getLastByteRequested unsigned int HTTPChannel::get_last_byte_requested(void) const; Description: Returns the last byte of the file requested by the request. This will normally be 0 to indicate that the file is being requested to its last byte, but if the file was requested via a get_subdocument() call, this will contain the last_byte parameter from that call.

getMaxBytesPerSecond double HTTPChannel::get_max_bytes_per_second(void) const; Description: Returns the maximum number of bytes per second that may be consumed by this channel when get_download_throttle() is true.

getMaxUpdatesPerSecond double HTTPChannel::get_max_updates_per_second(void) const; Description: Returns the maximum number of times per second that run() will do anything at all, when get_download_throttle() is true.

getNumRedirectTrail int HTTPChannel::get_num_redirect_trail(void) const; Description: If the document automatically followed one or more redirects, this will return the number of redirects that were automatically followed. Use get_redirect_trail() to retrieve each URL in sequence.

getOptions bool HTTPChannel::get_options(DocumentSpec const &url); Description: Sends an OPTIONS message to the server, which should query the available options, possibly in relation to a specified URL.

getPersistentConnection bool HTTPChannel::get_persistent_connection(void) const; Description: Returns whether the HTTPChannel should try to keep the connection to the server open and reuse that connection for multiple documents, or whether it should close the connection and open a new one for each request. See set_persistent_connection().

getProxyRealm string const &HTTPChannel::get_proxy_realm(void) const; Description: If the document failed to connect because of a 407 (Proxy authorization required), this method will return the "realm" returned by the proxy. This string may be presented to the user to request an associated username and password (which then should be stored in HTTPClient::set_username()).

getProxyTunnel bool HTTPChannel::get_proxy_tunnel(void) const; Description: Returns true if connections always tunnel through a proxy, or false (the normal case) if we allow the proxy to serve up documents. See set_proxy_tunnel().

getRedirect URLSpec const &HTTPChannel::get_redirect(void) const; Description: If the document failed with a redirect code (300 series), this will generally contain the new URL the server wants us to try. In many cases, the client will automatically follow redirects; if these are succesful the client will return a successful code and get_redirect() will return empty, but get_url() will return the new, redirected URL.

getRedirectTrail URLSpec const &HTTPChannel::get_redirect_trail(int n) const; Description: Use in conjunction with get_num_redirect_trail() to extract the chain of URL's that the channel was automatically redirected through to arrive at the final document.

getStatusCode int HTTPChannel::get_status_code(void) const; Description: Returns the HTML return code from the document retrieval request. This will be in the 200 range if the document is successfully retrieved, or some other value in the case of an error. Some proxy errors during an https-over-proxy request would return the same status code as a different error that occurred on the host server. To differentiate these cases, status codes that are returned by the proxy during the CONNECT phase (except code 407) are incremented by 1000.

getStatusString string HTTPChannel::get_status_string(void) const; Description: Returns the string as returned by the server describing the status code for humans. This may or may not be meaningful.

getSubdocument bool HTTPChannel::get_subdocument(DocumentSpec const &url, unsigned int first_byte, unsigned int last_byte); Description: Retrieves only the specified byte range of the indicated document. If last_byte is 0, it stands for the last byte of the document. When a subdocument is requested, get_file_size() and get_bytes_downloaded() will report the number of bytes of the subdocument, not of the complete document.

getTrace bool HTTPChannel::get_trace(DocumentSpec const &url); Description: Sends a TRACE message to the server, which should return back the same message as the server received it, allowing inspection of proxy hops, etc.

getUrl URLSpec const &HTTPChannel::get_url(void) const; Description: Returns the URL that was used to retrieve the most recent document: whatever URL was last passed to get_document() or get_header(). If a redirect has transparently occurred, this will return the new, redirected URL (the actual URL at which the document was located).

getWwwRealm string const &HTTPChannel::get_www_realm(void) const; Description: If the document failed to connect because of a 401 (Authorization required), this method will return the "realm" returned by the server in which the requested document must be authenticated. This string may be presented to the user to request an associated username and password (which then should be stored in HTTPClient::set_username()).

isConnectionReady bool HTTPChannel::is_connection_ready(void) const; Description: Returns true if a connection has been established to the named server in a previous call to connect_to() or begin_connect_to(), false otherwise.

isDownloadComplete bool HTTPChannel::is_download_complete(void) const; Description: Returns true when a download_to() or download_to_ram() has executed and the file has been fully downloaded. If this still returns false after processing has completed, there was an error in transmission. Note that simply testing is_download_complete() does not prove that the requested document was succesfully retrieved--you might have just downloaded the "404 not found" stub (for instance) that a server would provide in response to some error condition. You should also check is_valid() to prove that the file you expected has been successfully retrieved.

isFileSizeKnown bool HTTPChannel::is_file_size_known(void) const; Description: Returns true if the size of the file we are currently retrieving was told us by the server and thus is reliably known, or false if the size reported by get_file_size() represents an educated guess (possibly as set by set_expected_file_size(), or as inferred from a chunked transfer encoding in progress).

isValid bool HTTPChannel::is_valid(void) const; Filename: httpChannel.I Created by: drose (24Sep02) PANDA 3D SOFTWARE Copyright (c) 2001 - 2004, Disney Enterprises, Inc. All rights reserved All use of this software is subject to the terms of the Panda 3d Software license. You should have received a copy of this license along with this source code; you will also find a current copy of the license at http://etc.cmu.edu/panda3d/docs/license/ . To contact the maintainers of this program write to panda3d-general@lists.sourceforge.net . Description: Returns true if the last-requested document was successfully retrieved and is ready to be read, false otherwise.

postForm bool HTTPChannel::post_form(DocumentSpec const &url, string const &body); Description: Posts form data to a particular URL and retrieves the response.

preserveStatus void HTTPChannel::preserve_status(void); Description: Preserves the previous status code (presumably a failure) from the previous connection attempt. If the subsequent connection attempt also fails, the returned status code will be the better of the previous code and the current code. This can be called to daisy-chain subsequent attempts to download the same document from different servers. After all servers have been attempted, the final status code will reflect the attempt that most nearly succeeded.

putDocument bool HTTPChannel::put_document(DocumentSpec const &url, string const &body); Description: Uploads the indicated body to the server to replace the indicated URL, if the server allows this.

readBody ISocketStream *HTTPChannel::read_body(void); Description: Returns a newly-allocated istream suitable for reading the body of the document. This may only be called immediately after a call to get_document() or post_form(), or after a call to run() has returned false. The user is responsible for deleting the returned istream later.

reset void HTTPChannel::reset(void); Description: Stops whatever file transaction is currently in progress, closes the connection, and resets to begin anew. You shouldn't ever need to call this, since the channel should be able to reset itself cleanly between requests, but it is provided in case you are an especially nervous type. Don't call this after every request unless you set set_persistent_connection() to false, since calling reset() rudely closes the connection regardless of whether we have told the server we intend to keep it open or not.

run bool HTTPChannel::run(void); Description: This must be called from time to time when non-blocking I/O is in use. It checks for data coming in on the socket and writes data out to the socket when possible, and does whatever processing is required towards completing the current task. The return value is true if the task is still pending (and run() will need to be called again in the future), or false if the current task is complete.

sendExtraHeader void HTTPChannel::send_extra_header(string const &key, string const &value); Description: Specifies an additional key: value pair that is added into the header sent to the server with the next request. This is passed along with no interpretation by the HTTPChannel code. You may call this repeatedly to append multiple headers. This is persistent for one request only; it must be set again for each new request.

setAllowProxy void HTTPChannel::set_allow_proxy(bool allow_proxy); Description: If this is true (the normal case), the HTTPClient will be consulted for information about the proxy to be used for each connection via this HTTPChannel. If this has been set to false by the user, then all connections will be made directly, regardless of the proxy settings indicated on the HTTPClient.

setBlockingConnect void HTTPChannel::set_blocking_connect(bool blocking_connect); Description: If this flag is true, a socket connect will block even for nonblocking I/O calls like begin_get_document(), begin_connect_to(), etc. If false, a socket connect will not block for nonblocking I/O calls, but will block for blocking I/O calls (get_document(), connect_to(), etc.). Setting this true is useful when you want to use non-blocking I/O once you have established the connection, but you don't want to bother with polling for the initial connection. It's also useful when you don't particularly care about non-blocking I/O, but you need to respect timeouts like connect_timeout and http_timeout.

setConnectTimeout void HTTPChannel::set_connect_timeout(double timeout_seconds); Description: Sets the maximum length of time, in seconds, that the channel will wait before giving up on establishing a TCP connection. At present, this is used only for the nonblocking interfaces (e.g. begin_get_document(), begin_connect_to()), but it is used whether set_blocking_connect() is true or false.

setDownloadThrottle void HTTPChannel::set_download_throttle(bool download_throttle); Description: Specifies whether nonblocking downloads (via download_to_file() or download_to_ram()) will be limited so as not to use all available bandwidth. If this is true, when a download has been started on this channel it will be invoked no more frequently than get_max_updates_per_second(), and the total bandwidth used by the download will be no more than get_max_bytes_per_second(). If this is false, downloads will proceed as fast as the server can send the data. This only has effect on the nonblocking I/O methods like begin_get_document(), etc. The blocking methods like get_document() always use as much CPU and bandwidth as they can get.

setExpectedFileSize void HTTPChannel::set_expected_file_size(unsigned int file_size); Description: This may be called immediately after a call to get_document() or some related function to specify the expected size of the document we are retrieving, if we happen to know. This is used as the return value to get_file_size() only in the case that the server does not tell us the actual file size.

setHttpTimeout void HTTPChannel::set_http_timeout(double timeout_seconds); Description: Sets the maximum length of time, in seconds, that the channel will wait for the HTTP server to finish sending its response to our request. The timer starts counting after the TCP connection has been established (see set_connect_timeout(), above) and the request has been sent. At present, this is used only for the nonblocking interfaces (e.g. begin_get_document(), begin_connect_to()), but it is used whether set_blocking_connect() is true or false.

setMaxBytesPerSecond void HTTPChannel::set_max_bytes_per_second(double max_bytes_per_second); Description: When bandwidth throttling is in effect (see set_download_throttle()), this specifies the maximum number of bytes per second that may be consumed by this channel.

setMaxUpdatesPerSecond void HTTPChannel::set_max_updates_per_second(double max_updates_per_second); Description: When bandwidth throttling is in effect (see set_download_throttle()), this specifies the maximum number of times per second that run() will attempt to do any downloading at all.

setPersistentConnection void HTTPChannel::set_persistent_connection(bool persistent_connection); Description: Indicates whether the HTTPChannel should try to keep the connection to the server open and reuse that connection for multiple documents, or whether it should close the connection and open a new one for each request. Set this true to keep the connections around when possible, false to recycle them. It makes most sense to set this false when the HTTPChannel will be used only once to retrieve a single document, true when you will be using the same HTTPChannel object to retrieve multiple documents.

setProxyTunnel void HTTPChannel::set_proxy_tunnel(bool proxy_tunnel); Description: Normally, a proxy is itself asked for ordinary URL's, and the proxy decides whether to hand the client a cached version of the document or to contact the server for a fresh version. The proxy may also modify the headers and transfer encoding on the way. If this is set to true, then instead of asking for URL's from the proxy, we will ask the proxy to open a connection to the server (for instance, on port 80); if the proxy honors this request, then we contact the server directly through this connection to retrieve the document. If the proxy does not honor the connect request, then the retrieve operation fails. SSL connections (e.g. https), and connections through a Socks proxy, are always tunneled, regardless of the setting of this flag.

writeHeaders void HTTPChannel::write_headers(ostream &out) const; Description: Outputs a list of all headers defined by the server to the indicated output stream.

closeReadFile void VirtualFile::close_read_file(istream *stream) const; Description: Closes a file opened by a previous call to open_read_file(). This really just deletes the istream pointer, but it is recommended to use this interface instead of deleting it explicitly, to help work around compiler issues.

getClassType static TypeHandle VirtualFile::get_class_type(void); Undocumented function.

getFilename virtual Filename VirtualFile::get_filename(void) const = 0; Undocumented function.

getFileSize virtual int VirtualFile::get_file_size(istream *stream) const; Description: Returns the current size on disk (or wherever it is) of the already-open file. Pass in the stream that was returned by open_read_file(); some implementations may require this stream to determine the size. Description: Returns the current size on disk (or wherever it is) of the file before it has been opened.

getFileSystem virtual VirtualFileSystem *VirtualFile::get_file_system(void) const = 0; Undocumented function.

getOriginalFilename Filename const &VirtualFile::get_original_filename(void) const; Description: Returns the original filename as it was used to locate this VirtualFile. This is usually, but not always, the same string returned by get_filename().

getTimestamp virtual unsigned int VirtualFile::get_timestamp(void) const; Description: Returns a time_t value that represents the time the file was last modified, to within whatever precision the operating system records this information (on a Windows95 system, for instance, this may only be accurate to within 2 seconds). If the timestamp cannot be determined, either because it is not supported by the operating system or because there is some error (such as file not found), returns 0.

isDirectory virtual bool VirtualFile::is_directory(void) const; Description: Returns true if this file represents a directory (and scan_directory() may be called), false otherwise.

isRegularFile virtual bool VirtualFile::is_regular_file(void) const; Description: Returns true if this file represents a regular file (and read_file() may be called), false otherwise.

ls void VirtualFile::ls(ostream &out = (cout)) const; Description: If the file represents a directory, lists its contents.

lsAll void VirtualFile::ls_all(ostream &out = (cout)) const; Description: If the file represents a directory, recursively lists its contents and those of all subdirectories.

openReadFile virtual istream *VirtualFile::open_read_file(bool auto_unwrap) const; Description: Opens the file for reading. Returns a newly allocated istream on success (which you should eventually delete when you are done reading). Returns NULL on failure.

output void VirtualFile::output(ostream &out) const; Description:

readFile string VirtualFile::read_file(bool auto_unwrap) const; Description: Returns the entire contents of the file as a string. Description: Fills up the indicated string with the contents of the file, if it is a regular file. Returns true on success, false otherwise. Description: Fills up the indicated pvector with the contents of the file, if it is a regular file. Returns true on success, false otherwise. Description: Fills up the indicated pvector with the contents of the just-opened file. Returns true on success, false otherwise. If the pvector was not empty on entry, the data read from the file will be appended onto it. Description: As in read_file() with two parameters, above, but only reads up to max_bytes bytes from the file.

scanDirectory PointerTo< VirtualFileList > VirtualFile::scan_directory(void) const; Description: If the file represents a directory (that is, is_directory() returns true), this returns the list of files within the directory at the current time. Returns NULL if the file is not a directory or if the directory cannot be read.

getClassType static TypeHandle TypedReferenceCount::get_class_type(void); Undocumented function.

getClassType static TypeHandle TypedObject::get_class_type(void); Undocumented function.

getType virtual TypeHandle TypedObject::get_type(void) const = 0; Derived classes should override this function to return get_class_type().

getTypeIndex int TypedObject::get_type_index(void) const; Description: Returns the internal index number associated with this object's TypeHandle, a unique number for each different type. This is equivalent to get_type().get_index().

isExactType bool TypedObject::is_exact_type(TypeHandle handle) const; Description: Returns true if the current object is the indicated type exactly.

isOfType bool TypedObject::is_of_type(TypeHandle handle) const; Description: Returns true if the current object is or derives from the indicated type.

getClassType static TypeHandle ReferenceCount::get_class_type(void); Undocumented function.

getRefCount int ReferenceCount::get_ref_count(void) const; Description: Returns the current reference count.

ref void ReferenceCount::ref(void) const; Description: Explicitly increments the reference count. User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically. This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it.

testRefCountIntegrity bool ReferenceCount::test_ref_count_integrity(void) const; Description: Does some easy checks to make sure that the reference count isn't completely bogus. Returns true if ok, false otherwise.

testRefCountNonzero bool ReferenceCount::test_ref_count_nonzero(void) const; Description: Does some easy checks to make sure that the reference count isn't zero, or completely bogus. Returns true if ok, false otherwise.

unref bool ReferenceCount::unref(void) const; Description: Explicitly decrements the reference count. Note that the object will not be implicitly deleted by unref() simply because the reference count drops to zero. (Having a member function delete itself is problematic; plus, we don't have a virtual destructor anyway.) However, see the helper function unref_delete(). User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically. This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it. The return value is true if the new reference count is nonzero, false if it is zero.