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

#include <ms_http_helper.hpp>

Inheritance diagram for ms_http_helper:

Collaboration diagram for ms_http_helper:

[legend]

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_settings &	connectionSettings () 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_errs *	getErrorHandler () 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_helper &	operator= (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:

Sending GET commands to an HTTP server and getting the response string.
Sending GET commands to an HTTP server and getting the response as a file.
POSTing a file to an HTTP server.
Sending GET commands to HTTP, FTP or FILE protocol based servers and buffering the response as strings. This is useful for large downloads into memory where the size is not known.

Examples: http_helper_getstring.cpp.

Member Enumeration Documentation

◆ FileMode

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

◆ ms_http_helper() [1/3]

ms_http_helper ( )

C++ STL collection support.

No network activity occurs during the constructor.

◆ ms_http_helper() [2/3]

ms_http_helper ( const ms_http_helper & copy )

Copy constructor.

Required because there is a dynamically added data member.

Parameters

copy	reference to a ms_http_helper object

◆ ms_http_helper() [3/3]

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

baseUrl	The base URL of the target server. For example "http://www.matrixscience.com/cgi/".
settings	Settings that control the behaviour of the network link to the server.

◆ ~ms_http_helper()

~ms_http_helper ( )

Destructor.

Called automatically.

Member Function Documentation

◆ appendErrors()

void appendErrors ( const ms_errors & src )

inherited

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

Parameters

src	The object to copy the errors across from. See Maintaining object references: two rules of thumb.

◆ baseUrl()

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/".

◆ clearAllErrors()

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.

◆ connectionSettings()

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.

◆ copyFrom() [1/2]

void copyFrom ( const ms_errors * right )

inherited

Use this member to make a copy of another instance.

Parameters

right is the source to initialise from

◆ copyFrom() [2/2]

void copyFrom ( const ms_http_helper * right )

Parameters

right is the source to initialise from

◆ getErrorHandler()

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.

◆ getHeaderValue()

std::string getHeaderValue	(	const std::string &	name,
		const std::string &	header
	)

static

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

Parameters

name	Required name key of name value pair in header.
header	The header text seperated by CR LF.

Returns: The value string if it exists otherwise empty.

◆ getLastError()

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.

◆ getLastErrorString()

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()

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.

◆ getProxyConfig()

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

proxyServers	is 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.
proxyUsernames	is 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#.
proxyPasswords	is 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.

◆ httpBufferedClose()

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.

◆ httpBufferedGetString()

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]	httpBuffer	Receives any data read from the connection.
[in]	requiredSize	The 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.

◆ httpBufferedOpen()

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

action The 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.

◆ httpGetFile()

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

action	The action string, appended to the base URL, to be sent to the server.
filename	The name of the file to write the downloaded reply to.
progress	An object to keep up-to-date with the current progress of request. See Maintaining object references: two rules of thumb.
fileMode	The mode (text or binary) in which to write the downloaded reply to the file.

Returns: The final outcome of the HTTP GET request.

◆ httpGetHeader()

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]	action	The action string, appended to the base URL, to be sent to the server.
[out]	httpHeaderInfo	The 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.

◆ httpGetString()

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]	action	The action string, appended to the base URL, to be sent to the server.
[out]	httpGETString	Returns the raw HTTP text received in reply from the server.

Returns: The final outcome of the HTTP GET request.

Examples: http_helper_getstring.cpp.

◆ httpPostFile()

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

action	The action string, appended to the base URL, to be sent to the server.
httpHeader	The HTTP headers passed when creating a new query. Typically this identifies the content type and the MIME separator string.
prologue	Text sent as the first part of the content of the HTTP POST.
filename	The name of a file, the content of which is sent after the prologue text and before the epilogue text.
epilogue	Text sent as the last part of the content of the HTTP POST.
returnHandles	Returns handles that can be used to dowload the response from the server. See Maintaining object references: two rules of thumb.
progress	An 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.

◆ isValid()

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, repeat_search.cpp, resfile_error.cpp, resfile_info.cpp, resfile_input.cpp, resfile_params.cpp, resfile_summary.cpp, and tools_aahelper.cpp.

◆ operator=()

const ms_http_helper & operator= ( const ms_http_helper & copy )

Copy assignment.

Required because there is a dynamically added data member.

Parameters

copy	reference to a ms_http_helper object

Returns: reference to the current object

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

ms_http_helper.hpp
ms_http_helper.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ FileMode

Constructor & Destructor Documentation

◆ ms_http_helper() [1/3]

◆ ms_http_helper() [2/3]

◆ ms_http_helper() [3/3]

◆ ~ms_http_helper()

Member Function Documentation

◆ appendErrors()

◆ baseUrl()

◆ clearAllErrors()

◆ connectionSettings()

◆ copyFrom() [1/2]

◆ copyFrom() [2/2]

◆ getErrorHandler()

◆ getHeaderValue()

◆ getLastError()

◆ getLastErrorString()

◆ getProxyConfig()

◆ httpBufferedClose()

◆ httpBufferedGetString()

◆ httpBufferedOpen()

◆ httpGetFile()

◆ httpGetHeader()

◆ httpGetString()

◆ httpPostFile()

◆ isValid()

◆ operator=()