ncbicgi.hpp

ncbi源码

              unsigned int position)
            : m_Value(value), m_Filename(filename), m_Position(position) { }
        SData(const SData& data)
            : m_Value(data.m_Value), m_Filename(data.m_Filename),
            m_Position(data.m_Position){ }

        string       m_Value, m_Filename;
        unsigned int m_Position;
    };

public:
    CCgiEntry(const string& value, const string& filename = kEmptyStr,
              unsigned int position = 0)
        : m_Data(new SData(value, filename, position)) { }
    CCgiEntry(const char* value, const string& filename = kEmptyStr,
              unsigned int position = 0)
        : m_Data(new SData(value, filename, position)) { }
    CCgiEntry(const CCgiEntry& e) : m_Data(e.m_Data) { }

    const string& GetValue() const
        { return m_Data->m_Value; }
    string&       SetValue()
        { x_ForceUnique(); return m_Data->m_Value; }
    void          SetValue(const string& v)
        { x_ForceUnique(); m_Data->m_Value = v; }

    const string& GetFilename() const
        { return m_Data->m_Filename; }
    string&       SetFilename()
        { x_ForceUnique(); return m_Data->m_Filename; }
    void          SetFilename(const string& f)
        { x_ForceUnique(); m_Data->m_Filename = f; }

    // CGI parameter number -- automatic image name parameter is #0,
    // explicit parameters start at #1
    unsigned int  GetPosition() const
        { return m_Data->m_Position; }
    unsigned int& SetPosition()
        { x_ForceUnique(); return m_Data->m_Position; }
    void          SetPosition(int p)
        { x_ForceUnique(); m_Data->m_Position = p; }

    operator const string&() const     { return GetValue(); }
    operator       string&()           { return SetValue(); }
    // commonly-requested string:: operations...
    SIZE_TYPE size() const             { return GetValue().size(); }
    bool empty() const                 { return GetValue().empty(); }
    const char* c_str() const          { return GetValue().c_str(); }
    int compare(const string& s) const { return GetValue().compare(s); }
    int compare(const char* s) const   { return GetValue().compare(s); }
    string substr(SIZE_TYPE i = 0, SIZE_TYPE n = NPOS) const
        { return GetValue().substr(i, n); }
    SIZE_TYPE find(const char* s, SIZE_TYPE pos = 0) const
        { return GetValue().find(s, pos); }
    SIZE_TYPE find(const string& s, SIZE_TYPE pos = 0) const
        { return GetValue().find(s, pos); }
    SIZE_TYPE find(char c, SIZE_TYPE pos = 0) const
        { return GetValue().find(c, pos); }
    SIZE_TYPE find_first_of(const string& s, SIZE_TYPE pos = 0) const
        { return GetValue().find_first_of(s, pos); }
    SIZE_TYPE find_first_of(const char* s, SIZE_TYPE pos = 0) const
        { return GetValue().find_first_of(s, pos); }

private:
    void x_ForceUnique()
        { if (!m_Data->ReferencedOnlyOnce()) { m_Data = new SData(*m_Data); } }

    CRef<SData> m_Data;
};


/* @} */


inline
bool operator ==(const CCgiEntry& e1, const CCgiEntry& e2)
{
    return (e1.GetValue() == e2.GetValue() 
            &&  e1.GetFilename() == e2.GetFilename());
}

inline
bool operator !=(const CCgiEntry& e1, const CCgiEntry& e2)
{
    return !(e1 == e2);
}

inline
bool operator ==(const CCgiEntry& e, const string& s)
{
    return e.GetValue() == s;
}

inline
bool operator ==(const CCgiEntry& e, const char* s)
{
    return e.GetValue() == s;
}

inline
string operator +(const CCgiEntry& e, const string& s)
{
    return e.GetValue() + s;
}

inline
string operator +(const string& s, const CCgiEntry& e)
{
    return s + e.GetValue();
}

inline
CNcbiOstream& operator <<(CNcbiOstream& o, const CCgiEntry& e)
{
    return o << e.GetValue();
    // filename omitted in case anything depends on just getting the value
}


/** @addtogroup CGIReqRes
 *
 * @{
 */


// Typedefs
typedef map<string, string>         TCgiProperties;
typedef multimap<string, CCgiEntry> TCgiEntries;
typedef TCgiEntries::iterator       TCgiEntriesI;
typedef TCgiEntries::const_iterator TCgiEntriesCI;
typedef list<string>                TCgiIndexes;

// Forward class declarations
class CNcbiArguments;
class CNcbiEnvironment;


//
class NCBI_XCGI_EXPORT CCgiRequest
{
public:
    // Startup initialization:
    //   retrieve request's properties and cookies from environment;
    //   retrieve request's entries from "$QUERY_STRING".
    // If "$REQUEST_METHOD" == "POST" and "$CONTENT_TYPE" is empty or either
    // "application/x-www-form-urlencoded" or "multipart/form-data",
    // and "fDoNotParseContent" flag is not set,
    // then retrieve and parse entries from the input stream "istr".
    // If "$REQUEST_METHOD" is undefined then try to retrieve the request's
    // entries from the 1st cmd.-line argument, and do not use "$QUERY_STRING"
    // and "istr" at all.
    typedef int TFlags;
    enum Flags {
        // do not handle indexes as regular FORM entries with empty value
        fIndexesNotEntries  = 0x1,
        // do not parse $QUERY_STRING
        fIgnoreQueryString  = 0x2,
        // own the passed "env" (and destroy it in the destructor)
        fOwnEnvironment     = 0x4,
        // do not automatically parse the request's content body (from "istr")
        fDoNotParseContent  = 0x8
    };
    CCgiRequest(const         CNcbiArguments*   args = 0,
                const         CNcbiEnvironment* env  = 0,
                CNcbiIstream* istr  = 0 /*NcbiCin*/,
                TFlags        flags = 0,
                int           ifd   = -1,
                size_t        errbuf_size = 256);
    // args := CNcbiArguments(argc,argv), env := CNcbiEnvironment(envp)
    CCgiRequest(int                argc,
                const char* const* argv,
                const char* const* envp  = 0,
                CNcbiIstream*      istr  = 0,
                TFlags             flags = 0,
                int                ifd   = -1,
                size_t             errbuf_size = 256);

    // Destructor
    ~CCgiRequest(void);

    // Get name(not value!) of a "standard" property
    static const string& GetPropertyName(ECgiProp prop);

    // Get value of a "standard" property (return empty string if not defined)
    const string& GetProperty(ECgiProp prop) const;

    // Get value of a random client property;  if "http" is TRUE then add
    // prefix "HTTP_" to the property name.
    // NOTE:  usually, the value is extracted from the environment variable
    //        named "$[HTTP]_<key>". Be advised, however, that in the case of
    //        FastCGI application, the set (and values) of env.variables change
    //        from request to request, and they differ from those returned
    //        by CNcbiApplication::GetEnvironment()!
    const string& GetRandomProperty(const string& key, bool http = true) const;

    // Get content length using value of the property 'eCgi_ContentLength'.
    // Return "kContentLengthUnknown" if Content-Length header is missing.
    static const size_t kContentLengthUnknown;
    size_t GetContentLength(void) const;

    // Retrieve the request cookies
    const CCgiCookies& GetCookies(void) const;
    CCgiCookies& GetCookies(void);

    // Get a set of entries(decoded) received from the client.
    // Also includes "indexes" if "indexes_as_entries" in the
    // constructor was "true"(default).
    const TCgiEntries& GetEntries(void) const;
    TCgiEntries& GetEntries(void);

    // Get entry value by name
    // NOTE:  There can be more than one entry with the same name;
    //        only one of these entry will be returned.
    // To get all matches, use GetEntries() and "multimap::" member functions.
    const CCgiEntry& GetEntry(const string& name, bool* is_found = 0) const;
    

    // Get a set of indexes(decoded) received from the client.
    // It will always be empty if "indexes_as_entries" in the constructor
    // was "true"(default).
    const TCgiIndexes& GetIndexes(void) const;
    TCgiIndexes& GetIndexes(void);

    // Return pointer to the input stream.
    // Return NULL if the input stream is absent, or if it has been
    // automagically read and parsed already (the "POST" method, and empty or
    // "application/x-www-form-urlencoded" or "multipart/form-data" type,
    // and "fDoNotParseContent" flag was not passed to the constructor).
    CNcbiIstream* GetInputStream(void) const;
    // Returns file descriptor of input stream, or -1 if unavailable.
    int           GetInputFD(void) const;

    // Set input stream to "is".
    // If "own" is set to TRUE then this stream will be destroyed
    // as soon as SetInputStream() gets called with another stream pointer.
    // NOTE: SetInputStream(0) will be called in ::~CCgiRequest().
    void SetInputStream(CNcbiIstream* is, bool own = false, int fd = -1);

    // Decode the URL-encoded(FORM or ISINDEX) string "str" into a set of
    // entries <"name", "value"> and add them to the "entries" set.
    // The new entries are added without overriding the original ones, even
    // if they have the same names.
    // FORM    format:  "name1=value1&.....", ('=' and 'value' are optional)
    // ISINDEX format:  "val1+val2+val3+....."
    // If the "str" is in ISINDEX format then the entry "value" will be empty.
    // On success, return zero;  otherwise return location(1-based) of error
    static SIZE_TYPE ParseEntries(const string& str, TCgiEntries& entries);

    // Decode the URL-encoded string "str" into a set of ISINDEX-like entries
    // and add them to the "indexes" set
    // On success, return zero, otherwise return location(1-based) of error
    static SIZE_TYPE ParseIndexes(const string& str, TCgiIndexes& indexes);

private:
    // set of environment variables
    const CNcbiEnvironment*    m_Env;
    auto_ptr<CNcbiEnvironment> m_OwnEnv;
    // set of the request FORM-like entries(already retrieved; cached)
    TCgiEntries m_Entries;
    // set of the request ISINDEX-like indexes(already retrieved; cached)
    TCgiIndexes m_Indexes;
    // set of the request cookies(already retrieved; cached)
    CCgiCookies m_Cookies;
    // input stream
    CNcbiIstream* m_Input; 
    // input file descriptor, if available.
    int           m_InputFD;
    bool          m_OwnInput;
    // Request initialization error buffer size;
    // when initialization code hits unexpected EOF it will try to 
    // add diagnostics and print out accumulated request buffer 
    // 0 in this variable means no buffer diagnostics
    size_t        m_ErrBufSize;

    // the real constructor code
    void x_Init(const CNcbiArguments*   args,
                const CNcbiEnvironment* env,
                CNcbiIstream*           istr,
                TFlags                  flags,
                int                     ifd);

    // retrieve(and cache) a property of given name
    const string& x_GetPropertyByName(const string& name) const;

    // prohibit default initialization and assignment
    CCgiRequest(const CCgiRequest&);
    CCgiRequest& operator= (const CCgiRequest&);
};  // CCgiRequest


// URL encode flags
enum EUrlEncode {
    eUrlEncode_SkipMarkChars,
    eUrlEncode_ProcessMarkChars
};

// Decode the URL-encoded string "str";  return the result of decoding
// If "str" format is invalid then throw CParseException
NCBI_XCGI_EXPORT
extern string URL_DecodeString(const string& str);


// URL-encode a string "str" to the "x-www-form-urlencoded" form;
// return the result of encoding. If 
NCBI_XCGI_EXPORT
extern string URL_EncodeString
    (const      string& str,
     EUrlEncode encode_mark_chars = eUrlEncode_SkipMarkChars
     );


/* @} */


/////////////////////////////////////////////////////////////////////////////

/////////////////////////////////////////////////////////////////////////////
//  IMPLEMENTATION of INLINE functions
/////////////////////////////////////////////////////////////////////////////