CascadeHTTPClient.h

Go to the documentation of this file.

//
// CascadeHTTPClient.h - header file for class CascadeHTTPClient
//
// Copyright (c) 2003, Roku, LLC.  All rights reserved.
//

#ifndef _ROKU_INCLUDE_CASCADE_NET_CASCADEHTTPCLIENT_H
#define _ROKU_INCLUDE_CASCADE_NET_CASCADEHTTPCLIENT_H

#include <cascade/CascadeObject.h>
#include <cascade/util/CascadeString.h>

// ISSUE: Some people like to #define identifiers that are all caps, so
// if you have function calls in a public API that are all caps, they might
// collide with clients' macros / definitions.

#ifdef GET
#pragma message ( "warning: CascadeHTTPClient API masking macro definition (GET)" )
#undef GET
#endif

#ifdef HEAD
#pragma message ( "warning: CascadeHTTPClient API masking macro definition (HEAD)" )
#undef HEAD
#endif

#ifdef POST
#pragma message ( "warning: CascadeHTTPClient API masking macro definition (POST)" )
#undef POST
#endif

#ifdef PUT
#pragma message ( "warning: CascadeHTTPClient API masking macro definition (PUT)" )
#undef PUT
#endif

#ifdef DELETE
#pragma message ( "warning: CascadeHTTPClient API masking macro definition (DELETE)" )
#undef DELETE
#endif

#ifdef TRACE
#pragma message ( "warning: CascadeHTTPClient API masking macro definition (TRACE)" )
#undef TRACE
#endif

class CascadeHTTPClient : public CascadeObject
{
public:
        CascadeHTTPClient(const char * pURL);

        CascadeHTTPClient();

        virtual ~CascadeHTTPClient();

public:
        /* CONFIGURATION METHODS */

        virtual void SetURL(const char * pURL);
        virtual bool GetURL(CascadeString &url) const;
        
        virtual void SetHostname(const char * pHostname);
        virtual bool GetHostname(CascadeString &hostname) const;

        virtual void SetPort(u16 nPort);
        virtual u16 GetPort() const;

        virtual void SetPath(const char * pPath);
        virtual bool GetPath(CascadeString &path) const;

        virtual bool GetPathQuery(CascadeString &pathnquery) const;

        virtual void SetFragment(const char * pFragment);
        virtual bool GetFragment(CascadeString &fragment) const;

        virtual void SetQueryValue(const char * pQuery, const char * pQueryValue); 
        virtual bool GetQueryValue(const char * pQuery, CascadeString &value) const;

        virtual void SetUsername(const char * pUsername);
        virtual bool GetUsername(CascadeString &username) const;

        virtual void SetPassword(const char * pPassword);
        virtual bool GetPassword(CascadeString &password) const;


        virtual void SetKeepAlive(bool bKeepAlive); 
        virtual bool GetKeepAlive() const;

        void UserAgent (const char *user_agent); 
        const char *UserAgent () const; 

        virtual void SetHTTPVersion(const char * pHTTPVersion); 
        virtual bool GetHTTPVersion(CascadeString &version) const;

        virtual void SetPeerHTTPVersion(const char * pPeerHTTPVersion); 
        virtual bool GetPeerHTTPVersion(CascadeString &version) const;

        /*HTML doesn't specify a line length limit or a limit to the number of
header lines.  The CascadeHTTPClient class buffers header lines to
give users an easy interface to the header content if they are
interested.  MaxLineLength and MaxHeaderLines puts limits on the size
of header data that the CascadeHTTPClient actually remembers, which
protects a process from unruly servers.  This is in common with
several different HTTP APIs that are out there.

If a server produces lines that exceed the MaxLineLength or
MaxHeaderLines, the CascadeHTTPClient fills up its storage and drops
the rest on the floor (or overwrites previously stored header lines
--- I haven't decided which behavior is best).  The COMMAND methods
will return an error code to indicate when this happens.  No part of
the HTTP entity body is ever dropped, only parts of header lines.*/
        virtual void SetMaxLineLength(u32 nMaxLineLength); 
        virtual u32 GetMaxLineLength() const;

        virtual void SetMaxHeaderLines(u32 nMaxHeaderLines); 
        virtual u32 GetMaxHeaderLines() const;

        virtual void SetRequestHeader(const char * pHeaderKey, const char * pHeaderValue); 
        virtual bool GetRequestHeader(const char * pHeaderKey, CascadeString &header) const;

        virtual void SetByteRange(u64 nRangeStart, u64 nRangeStop);
        // convience for setting range header info
        // Set nRangeStop to zero to request end of document.
        virtual void GetByteRange(u64 & nRangeStartToSet, u64 & nRangeStopToSet) const;
        // get the range info
        // NOTE: NOT IMPLEMENTED!!!

        /* COMMAND METHODS */
        /* in blocking mode, all commands result in at least HTTP header download */

        u32 GET ();     
        u32 GET (const char *path); 

        u32 HEAD ();    
        u32 HEAD (const char *path); 

        u32 POST (const char *buf, u32 len); 
        u32 POST (const char *path, const char *buf, u32 len); 

        u32 PUT (const char *buf, u32 len); 
        u32 PUT (const char *path, const char *buf, u32 len); 

        u32 DELETE ();  
        u32 DELETE (const char *path); 

        u32 TRACE ();   
        u32 TRACE (const char *path); 

        /* RESPONSE METHODS */
        /* In blocking mode, the header and response code info will be valid AFTER the COMMAND returns. */

        virtual bool GetResponseCode(CascadeString &code) const;
        virtual bool GetResponseText(CascadeString &text) const;
        virtual u32 GetResponseCodeInt () const;

        /* trailer key/value pairs only populated and valid after read() returns end-of-file */
        virtual bool GetResponseHeader(CascadeString &header) const;
        virtual bool GetResponseHeaderAt(u32 nIndex, CascadeString &header) const;
        virtual bool GetResponseHeaderKey(u32 nIndex, CascadeString &key) const;
        virtual bool GetResponseHeaderValue(const char * pResponseHeaderKey, CascadeString &value) const;

        virtual u32 ReadBytes(char * pBuff, u32 nBytes); 

        /* Note about Blocking and Non-Blocking modes:
           There are four places where we can potentially block in this class:
           ::GET       calls connect(), send(), and recv()
           ::ReadBytes calls recv()
           The blocking mode of each of these three different system calls can
           be independently controlled by giving them non-zero timeouts.
          
           The default timeout for connect is zero, which means it will block forever.
           if you give it a non-zero timeout using ::SetConnectTimeout(), the call to
           connect() will only block for as long (in microseconds) as that timeout.

           The same holds for setting the send and receive timeouts with
           ::SetSendTimeout() and ::SetReceiveTimeout() respectively.
         */

        virtual bool SetConnectTimeout(u32 nTimeoutMicroseconds);
        virtual bool SetSendTimeout(u32 nTimeoutMicroseconds);
        virtual bool SetReceiveTimeout(u32 nTimeoutMicroseconds);
        virtual u32 GetConnectTimeout() const;
        virtual u32 GetSendTimeout() const;
        virtual u32 GetReceiveTimeout() const;

        virtual bool SetAutoRedirectLimit(int this_many_times);

        static void URLEncodeString (const CascadeString input, CascadeString &output);

        static bool ErrorString (const u32 get_retval, CascadeString &error_string);

private:
        class PrivateMembers;
        PrivateMembers *m_private;
};

#endif // #ifndef _ROKU_INCLUDE_CASCADE_NET_CASCADEHTTPCLIENT_H

//  LOG
//  12-Feb-04   dwuertele   this is how we shall support HTTP
//  01-Jun-05   dsletten    unify line endings (VDSP confused by mixed-type)
//                          changed Get / SetByteRange params to u64s

---