Matrix Science header
Public Types | Public Member Functions | Static Public Member Functions

ms_http_helper Class Reference
[Accessing a Mascot Server using HTTP]

The class provides HTTP, FTP and FILE protocol access to a server. More...

#include <ms_http_helper.hpp>

Inheritance diagram for ms_http_helper:
Inheritance graph
[legend]
Collaboration diagram for ms_http_helper:
Collaboration graph
[legend]

List of all members.

Public Types

enum  FileMode {
  FM_binary,
  FM_text
}
 

Definitions for types of file content transfer.

More...

Public Member Functions

 ms_http_helper ()
 C++ STL collection support.
 ms_http_helper (const ms_http_helper &copy)
 Copy constructor.
 ms_http_helper (const std::string &baseUrl, const ms_connection_settings &settings)
 Constructor for a connection to a server.
 ~ms_http_helper ()
 Destructor.
void appendErrors (const ms_errors &src)
 Copies all errors from another instance and appends them at the end of own list.
const std::string & baseUrl () const
 Returns the base URL to the server.
void clearAllErrors ()
 Remove all errors from the current list of errors.
const ms_connection_settingsconnectionSettings () const
 Returns the internet settings used for the HTTP connection.
void copyFrom (const ms_errors *right)
 Use this member to make a copy of another instance.
void copyFrom (const ms_http_helper *right)
const ms_errsgetErrorHandler () const
 Retrive the error object using this function to get access to all errors and error parameters.
int getLastError () const
 Return the error description of the last error that occurred.
std::string getLastErrorString () const
 Return the error description of the last error that occurred.
bool getProxyConfig (std::vector< std::string > &proxyServers, std::vector< std::string > &proxyUsernames, std::vector< std::string > &proxyPasswords)
 Get the proxy server configuration settings.
ms_http_helper_return httpBufferedClose ()
 Closes the current buffered read session.
ms_http_helper_return httpBufferedGetString (std::string &httpBuffer, unsigned long requiredSize)
 Get available data from the open session. Writes data into the supplied buffer up to at least the required size.
ms_http_helper_return httpBufferedOpen (const std::string &action)
 Creates and opens a session for buffered reading from the supplied base URL and action.
ms_http_helper_return httpGetFile (const std::string &action, const std::string &filename, ms_http_helper_progress &progress, FileMode fileMode=FM_binary)
 Sends an HTTP GET message to the server and store the reply in a file.
ms_http_helper_return httpGetHeader (const std::string &action, std::string &httpHeaderInfo)
 Sends an HTTP HEAD message to the server and returns the header information separated with CR LF.
ms_http_helper_return httpGetString (const std::string &action, std::string &httpGETString)
 Sends an HTTP GET message to the server and returns the reply in a string.
ms_http_helper_return httpPostFile (const std::string &action, const std::string &httpHeader, const std::string &prologue, const std::string &filename, const std::string &epilogue, ms_http_helper_handles &handles, ms_http_helper_progress &progress)
 Sends an HTTP POST message to the server and returns handles to allow the HTTP connection to be managed.
bool isValid () const
 Call this function to determine if there have been any errors.
const ms_http_helperoperator= (const ms_http_helper &copy)
 Copy assignment.

Static Public Member Functions

static std::string getHeaderValue (const std::string &name, const std::string &header)
 Returns the value for a name-value pair in an http header.

Detailed Description

The class provides HTTP, FTP and FILE protocol access to a server.

The following tasks are supported:

Examples:

http_helper_getstring.cpp.


Member Enumeration Documentation

enum FileMode

Definitions for types of file content transfer.

See Using enumerated values and static const ints in Perl, Java, Python and C#.

Enumerator:
FM_binary 

Binary - the data is saved in exactly the form as it is received.

FM_text 

Text - the data is translated to a more text friendly form (new lines become cariage return/line feed pairs).


Constructor & Destructor Documentation

C++ STL collection support.

No network activity occurs during the constructor.

ms_http_helper ( const ms_http_helper copy )

Copy constructor.

Required because there is a dynamically added data member.

Parameters:
copyreference to a ms_http_helper object
ms_http_helper ( const std::string &  baseUrl,
const ms_connection_settings settings 
)

Constructor for a connection to a server.

No network activity occurs during the constructor.

Parameters:
baseUrlThe base URL of the target server. For example "http://www.matrixscience.com/cgi/".
settingsSettings that control the behaviour of the network link to the server.

Destructor.

Called automatically.


Member Function Documentation

void appendErrors ( const ms_errors src ) [inherited]

Copies all errors from another instance and appends them at the end of own list.

Parameters:
srcThe object to copy the errors across from. See Maintaining object references: two rules of thumb.
const std::string & baseUrl (  ) const

Returns the base URL to the server.

The base URL cannot be altered once the HTTP connection has been created.

Typically, the base URL will have the form "http://server_name/optional_path/cgi/".

Returns:
The base URL of the target server and file location. For example "http://www.matrixscience.com/cgi/".
void clearAllErrors (  ) [inherited]

Remove all errors from the current list of errors.

The list of 'errors' can include fatal errors, warning messages, information messages and different levels of debugging messages.

All messages are accumulated into a list in this object, until clearAllErrors() is called.

See Error Handling.

See also:
isValid(), getLastError(), getLastErrorString(), getErrorHandler()
Examples:
common_error.cpp, resfile_error.cpp, and resfile_summary.cpp.
const matrix_science::ms_connection_settings & connectionSettings (  ) const

Returns the internet settings used for the HTTP connection.

The settings cannot be altered once the HTTP connection has been created.

Returns:
Settings that control the behaviour of the network link to the server.
void copyFrom ( const ms_http_helper right )
Parameters:
rightis the source to initialise from
void copyFrom ( const ms_errors right ) [inherited]

Use this member to make a copy of another instance.

Parameters:
rightis the source to initialise from
const ms_errs * getErrorHandler (  ) const [inherited]

Retrive the error object using this function to get access to all errors and error parameters.

See Error Handling.

Returns:
Constant pointer to the error handler
See also:
isValid(), getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()
Examples:
common_error.cpp, and http_helper_getstring.cpp.
std::string getHeaderValue ( const std::string &  name,
const std::string &  header 
) [static]

Returns the value for a name-value pair in an http header.

Returns the value for a name-value pair in an http header.

Parameters:
nameRequired name key of name value pair in header.
headerThe header text seperated by CR LF.
Returns:
The value string if it exists otherwise empty.
int getLastError (  ) const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

See Error Handling.

See also:
isValid(), getLastErrorString(), clearAllErrors(), getErrorHandler()
Returns:
the error number of the last error, or 0 if there have been no errors.

Reimplemented in ms_mascotresfile.

std::string getLastErrorString (  ) const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

Returns:
Most recent error, warning, information or debug message

See Error Handling.

See also:
isValid(), getLastError(), clearAllErrors(), getErrorHandler()

Reimplemented in ms_mascotresfile.

Examples:
common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, and tools_aahelper.cpp.
bool getProxyConfig ( std::vector< std::string > &  proxyServers,
std::vector< std::string > &  proxyUsernames,
std::vector< std::string > &  proxyPasswords 
)

Get the proxy server configuration settings.

If unsuccessful, no output parameters are altered.

On Windows and depending on the proxy type in the ms_connection_settings, this uses the WinHttpGetIEProxyConfigForCurrentUser and WinHttpGetProxyForUrl Windows API functions to retrieve the information. For details, see: http://msdn.microsoft.com/en-us/library/windows/desktop/aa384097.aspx and http://msdn.microsoft.com/en-us/library/windows/desktop/aa384096.aspx

On Windows, the proxy server list is typically either set explicitly or retrieved, by the operating system, using Web Proxy Autodiscovery Protocol (WPAD) or Proxy auto-config (PAC). These protocols allow for different proxies to be configured for different domains, paths, ports or schemes (although Windows may imposes restrictions that limit the scope of this functionality - only the domain name should be used to determine the proxy server). Some further information is available at http://findproxyforurl.com/

On Linux, autoconfiguration is of more rudimentary type: proxy settings are pulled from the system environment variables, then from ms_connection_settings::getProxyServer().

Within Parser, Windows only tries the first entry in the proxy server list, and does not 'roll over' to try the next entry when one proxy cannot be reached. On Linux, on the other hand, each proxy server is tried in turn. If they all fail, a no-proxy configuration is tried as the last alternative.

Parameters:
proxyServersis filled in with the list of proxy server URLs. See Using STL vector classes vectori, vectord and VectorString in Perl, Java, Python and C#.

  • The format of the proxy will be, for example, http://proxy:3128
  • On Windows, if the system specifies a direct connection for url, then proxyServers will be an empty array.
  • On Linux, if the system should try a no-proxy configuration, the last item in proxyServers will be the empty string.
  • The array will contain more than one item when a fall back system is in place, in which case the application should try the first proxy, and then if this fails, it should try the next etc.
proxyUsernamesis filled with usernames to be used with proxyServers. If a proxy server does not need authentication, the corresponding element will be the empty string. proxyUsernames.size() equals proxyServers.size(). See Using STL vector classes vectori, vectord and VectorString in Perl, Java, Python and C#.
proxyPasswordsis filled with passwords to be used with proxyUsernames. If a proxy server does not need authentication or if a password is not needed, the corresponding element will be the empty string. proxyPasswords.size() equals proxyServers.size(). See Using STL vector classes vectori, vectord and VectorString in Perl, Java, Python and C#.
Returns:
Returns true if the function completed successfully.
matrix_science::ms_http_helper_return httpBufferedClose (  )

Closes the current buffered read session.

Closes a currently open buffered read session and connection. Refer to httpBufferedOpen() for example code and aditional information.

Returns:
Any errors detected during closing
Examples:
http_helper_getstring.cpp.
matrix_science::ms_http_helper_return httpBufferedGetString ( std::string &  httpBuffer,
unsigned long  requiredSize 
)

Get available data from the open session. Writes data into the supplied buffer up to at least the required size.

Reads to at least the requiredSize (or until empty) from currently open buffered read session. Overwrites data in the supplied buffer. If no data read then the buffer will set to zero length. Refer to httpBufferedOpen() for example code and aditional information.

See Multiple return values in Perl, Java, Python and C#.

Parameters:
[out]httpBufferReceives any data read from the connection.
[in]requiredSizeThe method returns when the buffer is greater than or equal to this size or when no more data available.
Returns:
Any errors detected during reading.
Examples:
http_helper_getstring.cpp.
matrix_science::ms_http_helper_return httpBufferedOpen ( const std::string &  action )

Creates and opens a session for buffered reading from the supplied base URL and action.

Opens a buffered read session using the current URL, action and connection settings. Allows data to be read in chunks and processed by using subsequent calls to httpBufferedGetString().

Support for HTTP, FTP and FILE protocols. HTTPS not currently supported.

Only one session for each ms_http_helper instance is supported at a time. Use the ms_connection_settings instance to setup any required proxy and security settings.

Parameters:
actionThe action string, appended to the base URL, to be sent to the server.

Example URL's:

  • "ftp://username:password@hostname/file.txt"
  • "file://hostname/file.txt"
  • "http://localhost/sitename/file.txt"

Example code:

 ms_connection_settings cs; // This uses default local security settings.
 ms_http_helper helper("http://localhost/sitename/", cs);
 if (helper.httpBufferedOpen("file.txt").isOk())
 {
     // Loop reading chunks of data until no more is available.
     while (true)
     {
         std::string buffer;
         // Reads at least 10000 bytes if available.
         ms_http_helper_return result = helper.httpBufferedGetString(buffer, 10000);
         // If the buffer size is empty then no more data is available.
         if (buffer.length() == 0 || !result.isOk())
             break;
         // Process buffer contents here.
     }
     helper.httpBufferedClose();
 }
 
Returns:
Returns any errors occurring during connection.
Examples:
http_helper_getstring.cpp.
matrix_science::ms_http_helper_return httpGetFile ( const std::string &  action,
const std::string &  filename,
matrix_science::ms_http_helper_progress progress,
FileMode  fileMode = FM_binary 
)

Sends an HTTP GET message to the server and store the reply in a file.

The progress information is updated as the download proceeds. The total amount of data to be returned is not known until the end of the download and so the total field is left at zero. The percentage complete will keep moving upward but is not a valid indicator of how much download is still remaining.

Parameters:
actionThe action string, appended to the base URL, to be sent to the server.
filenameThe name of the file to write the downloaded reply to.
progressAn object to keep up-to-date with the current progress of request. See Maintaining object references: two rules of thumb.
fileModeThe mode (text or binary) in which to write the downloaded reply to the file.
Returns:
The final outcome of the HTTP GET request.
matrix_science::ms_http_helper_return httpGetHeader ( const std::string &  action,
std::string &  httpHeaderInfo 
)

Sends an HTTP HEAD message to the server and returns the header information separated with CR LF.

Retrieves the HTTP header text if present for the current URL, action and connection settings.

See Multiple return values in Perl, Java, Python and C#.

Parameters:
[in]actionThe action string, appended to the base URL, to be sent to the server.
[out]httpHeaderInfoThe string to receive the header text. Each section is seperated with CR LF
Returns:
Returns any errors occurring during connection.
Examples:
http_helper_getstring.cpp.
matrix_science::ms_http_helper_return httpGetString ( const std::string &  action,
std::string &  httpGETString 
)

Sends an HTTP GET message to the server and returns the reply in a string.

Called by many higher level functions.

This will log the ms_errs::ERR_MSP_HTTP_URLSTRING message.

See Multiple return values in Perl, Java, Python and C#.

Parameters:
[in]actionThe action string, appended to the base URL, to be sent to the server.
[out]httpGETStringReturns the raw HTTP text received in reply from the server.
Returns:
The final outcome of the HTTP GET request.
Examples:
http_helper_getstring.cpp.
matrix_science::ms_http_helper_return httpPostFile ( const std::string &  action,
const std::string &  httpHeader,
const std::string &  prologue,
const std::string &  filename,
const std::string &  epilogue,
matrix_science::ms_http_helper_handles returnHandles,
matrix_science::ms_http_helper_progress progress 
)

Sends an HTTP POST message to the server and returns handles to allow the HTTP connection to be managed.

The progress information is updated as the upload proceeds. The total amount of data to be determined before the upload begins and this is placed in the proess total field.

The POST message contains the data from the prologue string, the file contents and then the epilogue string.

This will log the ms_errs::ERR_MSP_HTTP_URLSTRING message.

The function returns when the upload is complete.

Parameters:
actionThe action string, appended to the base URL, to be sent to the server.
httpHeaderThe HTTP headers passed when creating a new query. Typically this identifies the content type and the MIME separator string.
prologueText sent as the first part of the content of the HTTP POST.
filenameThe name of a file, the content of which is sent after the prologue text and before the epilogue text.
epilogueText sent as the last part of the content of the HTTP POST.
returnHandlesReturns handles that can be used to dowload the response from the server. See Maintaining object references: two rules of thumb.
progressAn object to keep up-to-date with the current progress of request. See Maintaining object references: two rules of thumb.
Returns:
Returns true if the function completed successfully.
bool isValid (  ) const [inherited]

Call this function to determine if there have been any errors.

This will return true unless there have been any fatal errors.

See Error Handling.

Returns:
True if no fatal error occured
See also:
getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()
Examples:
common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, peptide_list.cpp, resfile_summary.cpp, and tools_aahelper.cpp.
const ms_http_helper & operator= ( const ms_http_helper copy )

Copy assignment.

Required because there is a dynamically added data member.

Parameters:
copyreference to a ms_http_helper object
Returns:
reference to the current object

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

Copyright © 2022 Matrix Science Ltd.  All Rights Reserved. Generated on Thu Mar 31 2022 01:12:33