Settings required to make an HTTP connection to a Mascot server. More...

#include <ms_connection_settings.hpp>

Public Types
enum	HTTP_PROTOCOL { HTTP_1_0 = 0x0000 , HTTP_1_1 = 0x0001 , HTTP_SYSTEM_DEFAULT = 0x0002 }

enum	PROXY_TYPE { PROXY_TYPE_NO_PROXY = 0x0000 , PROXY_TYPE_FROM_REGISTRY = 0x0001 , PROXY_TYPE_SPECIFY = 0x0002 , PROXY_TYPE_WPAD = 0x0003 , PROXY_TYPE_ENVIRONMENT = 0x0004 , PROXY_TYPE_AUTO = 0x0005 }
	Definitions for types of setting. More...

enum	REDIRECT_POLICY { REDIRECT_POLICY_ALWAYS = 0x0000 , REDIRECT_POLICY_DISALLOW_HTTPS_TO_HTTP = 0x0001 , REDIRECT_POLICY_NEVER = 0x0002 }

Public Member Functions
	ms_connection_settings ()
	Default constructor used to create an ms_connection_settings object.

	ms_connection_settings (const std::string sessionID, const std::string proxyServer, const std::string proxyUserName, const std::string proxyUserPassword)
	Constructor to set some parameters.

	~ms_connection_settings ()
	Destructor.

void	copyFrom (const ms_connection_settings *right)
	Call this member to copy all the information from another instance.

void	defaultValues ()
	Called by the default constructor and may be called to re-initialise all values.

int	getConnectionTimeout () const
	Returns the HTTP connection timeout.

std::string	getHttpPassword () const
	Gets the password for an authenticated web server.

ms_connection_settings::HTTP_PROTOCOL	getHttpProtocol () const
	Returns the version of HTTP protocol to be used.

std::string	getHttpUsername () const
	Gets the username for an authenticated web server.

std::string	getProxyPassword () const
	Gets the password for an authenticated proxy server.

std::string	getProxyServer () const
	Gets the name of the proxy server.

ms_connection_settings::PROXY_TYPE	getProxyServerType () const
	Returns how proxy server information will be obtained.

std::string	getProxyUserAndPassword () const
	Get the combined username and password – if any.

std::string	getProxyUsername () const
	Gets the user name for an authenticated proxy server.

ms_connection_settings::REDIRECT_POLICY	getRedirectPolicy () const
	Gets the policy for HTTP redirection.

std::string	getSessionID () const
	Gets the sessionID to be used for the connection.

std::string	getUserAgent () const
	Get the user agent string.

bool	isUseHTTPProxyForFTP () const
	Return true if HTTP proxy settings should be used for FTP.

bool	isUseHTTPProxyForHTTPS () const
	Return true if HTTP proxy settings should be used for HTTPS.

ms_connection_settings &	operator= (const ms_connection_settings &right)
	C++ style assignment operator.

void	setConnectionTimeout (int timeout)
	Sets the HTTP connection timeout.

void	setHttpPassword (const std::string httpPassword)
	Sets the password for an authenticated web server.

void	setHttpProtocol (ms_connection_settings::HTTP_PROTOCOL httpProtocol)
	Sets the version of the HTTP protocol to be used.

void	setHttpUsername (const std::string httpUsername)
	Sets the username for an authenticated web server.

void	setProxyPassword (const std::string proxyUserPassword)
	Sets the password for an authenticated proxy server.

void	setProxyServer (const std::string proxyServer)
	Sets the name of the proxy server.

void	setProxyServerType (ms_connection_settings::PROXY_TYPE proxyType)
	Specifies how proxy server information will be obtained.

void	setProxyUsername (const std::string proxyUserName)
	Sets the user name for an authenticated proxy server.

void	setRedirectPolicy (ms_connection_settings::REDIRECT_POLICY redirectPolicy)
	Sets the policy for HTTP redirection.

void	setSessionID (const std::string sessionID)
	Sets the Mascot security sessionID to be used for the connection.

void	setUseHTTPProxyForFTP (bool value)
	Enable or disable use of an HTTP proxy server for an FTP request.

void	setUseHTTPProxyForHTTPS (bool value)
	Enable or disable use of an HTTP proxy server for an HTTPS request.

void	setUserAgent (const std::string userAgent)
	Set the user agent string.

Static Public Member Functions
static int	proxyTypeStringToEnum (std::string str)
	Convert proxy type string to PROXY_TYPE.

static std::string	proxyTypeToString (int type)
	Convert PROXY_TYPE to canonical string.

Detailed Description

Settings required to make an HTTP connection to a Mascot server.

A sessionID parameter may be required if Mascot security is enabled.

This class holds these settings and is used from:

ms_datfile::ms_datfile(const char *filename, const int timeoutSec, const ms_connection_settings *cs)
ms_umod_configfile::ms_umod_configfile(const char *filename, const char *schemaFileName, const ms_connection_settings *cs)
ms_modfile::ms_modfile(const char *filename, const ms_masses *massFile, const bool fromSubstitutions, const ms_connection_settings *cs)
ms_masses::ms_masses(const char* filename, const ms_connection_settings *cs)
ms_fragrulesfile::ms_fragrulesfile(const char *filename, const ms_connection_settings *cs)
ms_taxonomyfile::ms_taxonomyfile(const char *filename, const ms_connection_settings *cs)
ms_enzymefile::ms_enzymefile(const char *filename, const ms_connection_settings *cs)

Examples: config_enzymes.cpp, config_fragrules.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_quantitation.cpp, config_taxonomy.cpp, and http_helper_getstring.cpp.

Member Enumeration Documentation

◆ HTTP_PROTOCOL

enum HTTP_PROTOCOL

Definitions for HTTP protocol to use.

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

Enumerator
HTTP_1_0	Use HTTP 1.0.
HTTP_1_1	Use HTTP 1.1.
HTTP_SYSTEM_DEFAULT	Use system default. For Windows, this is set in Internet Explorer or the Control Panel.

◆ PROXY_TYPE

enum PROXY_TYPE

Definitions for types of setting.

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

Enumerator
PROXY_TYPE_NO_PROXY	No proxy server will be used. For Windows, the INTERNET_OPEN_TYPE_DIRECT flag is specified in the InternetOpen call.
PROXY_TYPE_FROM_REGISTRY	Windows version of Mascot Parser only. The proxy server will be discovered using the WinHttpGetIEProxyConfigForCurrentUser call (the no proxy is used if no proxy is set in Internet Explorer).
PROXY_TYPE_SPECIFY	The proxy server must be specified using setProxyServer(). The INTERNET_OPEN_TYPE_PROXY flag is specified in the InternetOpen call.
PROXY_TYPE_WPAD	Windows version of Mascot Parser only. The proxy server will be discovered using the WinHttpGetProxyForUrl call (the default proxy is used if no proxy can be auto-discovered).
PROXY_TYPE_ENVIRONMENT	Proxy settings will be loaded from the system environment variables `http_proxy` and `https_proxy`, depending on protocol.
PROXY_TYPE_AUTO	The proxy server will be discovered automatically. This is the default. On Windows the order is PROXY_TYPE_FROM_REGISTRY, then PROXY_TYPE_WPAD and finally the system default proxy. On Linux, the order is PROXY_TYPE_ENVIRONMENT, PROXY_TYPE_SPECIFY and PROXY_TYPE_NONE.

◆ REDIRECT_POLICY

enum REDIRECT_POLICY

Definitions for HTTP redirection policy.

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

Enumerator
REDIRECT_POLICY_ALWAYS	All redirects are followed automatically.
REDIRECT_POLICY_DISALLOW_HTTPS_TO_HTTP	All redirects are followed, except those that originate from a secure (https) URL to an unsecure (http) URL. This is the default setting.
REDIRECT_POLICY_NEVER	Redirects are never followed.

Constructor & Destructor Documentation

◆ ms_connection_settings() [1/2]

ms_connection_settings ( )

Default constructor used to create an ms_connection_settings object.

The values are all set to the defaults as detailed in defaultValues().

To set up the object correctly, it may be necessary to call one or more of the following functions, depending on the network environment.

◆ ms_connection_settings() [2/2]

ms_connection_settings	(	const std::string	sessionID,
		const std::string	proxyServer,
		const std::string	proxyUserName,
		const std::string	proxyUserPassword
	)

Constructor to set some parameters.

It is generally easier and clearer to create an object using the default constructor and then set all of the required values.

For this constructor, values not passed are set by calling defaultValues())

Parameters

sessionID	is the session ID string retrieved either from login.pl or from ms_session::ms_session().
proxyServer	is the URL of the proxy server, if any.
proxyUserName	is the user name for an authenticated proxy server.
proxyUserPassword	is the password for an authenticated proxy server.

◆ ~ms_connection_settings()

~ms_connection_settings ( )

Destructor.

Called automatically.

Member Function Documentation

◆ copyFrom()

void copyFrom ( const ms_connection_settings * right )

Call this member to copy all the information from another instance.

Useful in cases where the language doesn't support copying objects.

Parameters

right Valid pointer to a ms_connection_settings object

◆ defaultValues()

void defaultValues ( )

Called by the default constructor and may be called to re-initialise all values.

Sets all members to their default values:

sessionID is cleared.
connection timeout is set to 60 seconds.
proxy server settings are cleared.
proxy server type is set to ms_connection_settings::PROXY_TYPE_AUTO
For Windows, the http protocol is set to ms_connection_settings::HTTP_SYSTEM_DEFAULT
For Linux, the http protocol is set to ms_connection_settings::HTTP_1_1
For Windows, the user agent string is set to "MascotParser/[parser_version] winhttp/5.1".
For Linux, the user agent string is set to "MascotParser/[parser_version] curl/[curl version]."
The redirect policy is set to ms_connection_settings::REDIRECT_POLICY_DISALLOW_HTTPS_TO_HTTP

◆ getConnectionTimeout()

int getConnectionTimeout ( ) const

Returns the HTTP connection timeout.

The default value is 60 seconds.

Returns: The timeout in seconds before a connection will fail.

◆ getHttpPassword()

std::string getHttpPassword ( ) const

Gets the password for an authenticated web server.

Returns: The HTTP password.

◆ getHttpProtocol()

ms_connection_settings::HTTP_PROTOCOL getHttpProtocol ( ) const

Returns the version of HTTP protocol to be used.

The default value for Windows is HTTP_SYSTEM_DEFAULT and the default type for all the Unix platforms is HTTP_1_1.

Returns: An enumerated value which specifies whether HTTP 1.0, 1.1 or the system default is used when connecting via HTTP to a Mascot Server.

◆ getHttpUsername()

std::string getHttpUsername ( ) const

Gets the username for an authenticated web server.

Returns: The HTTP user name.

◆ getProxyPassword()

std::string getProxyPassword ( ) const

Gets the password for an authenticated proxy server.

When, for example ms_enzymefile::ms_enzymefile(const char* filename, const ms_connection_settings * cs) is called, that function will use the proxy server details when connecting to the Mascot server to retrieve the enzymes definitions.

Returns: The Proxy server password.

◆ getProxyServer()

std::string getProxyServer ( ) const

Gets the name of the proxy server.

When, for example ms_enzymefile::ms_enzymefile(const char* filename, const ms_connection_settings * cs) is called, that function will use the proxy server details when connecting to the Mascot server to retrieve the enzymes definitions.

This is the proxy server name specified to setProxyServer(). This is only valid if the proxy server type is PROXY_TYPE_SPECIFY. If the proxy server type is something other value then getProxyList() should be used.

Returns: The specified proxy server name.

◆ getProxyServerType()

ms_connection_settings::PROXY_TYPE getProxyServerType ( ) const

Returns how proxy server information will be obtained.

The default value is PROXY_TYPE_AUTO. If setProxyServer() is called with a non zero length string, then this type is automatically set to PROXY_TYPE_SPECIFY.

See also: setProxyServer()

Returns: An enumerated value PROXY_TYPE which specifies the way in which information about the proxy server can be obtained.

◆ getProxyUserAndPassword()

std::string getProxyUserAndPassword ( ) const

Get the combined username and password – if any.

Returns: A string in the format username:password.

◆ getProxyUsername()

std::string getProxyUsername ( ) const

Gets the user name for an authenticated proxy server.

When, for example ms_enzymefile::ms_enzymefile(const char* filename, const ms_connection_settings * cs) is called, that function will use the proxy server details when connecting to the Mascot server to retrieve the enzymes definitions.

Returns: The Proxy server user name.

◆ getRedirectPolicy()

ms_connection_settings::REDIRECT_POLICY getRedirectPolicy ( ) const

Gets the policy for HTTP redirection.

The default value for Windows is REDIRECT_POLICY_DISALLOW_HTTPS_TO_HTTP.

Returns: An enumerated value controls what types of redirection request are allowed.

◆ getSessionID()

std::string getSessionID ( ) const

Gets the sessionID to be used for the connection.

A session ID is used if Mascot Security is enabled; see Mascot security and authentication module. The sessionID is originally retrieved by the calling application either from login.pl or from ms_session::ms_session(). This is then set using setSessionID(). When, for example ms_enzymefile::ms_enzymefile(const char* filename, const ms_connection_settings * cs) is called, that function will get the sessionID and use it to retrieve the enzymes definitions from the Mascot server.

Returns: The session ID string that has been set by calling setSessionID().

◆ getUserAgent()

std::string getUserAgent ( ) const

Get the user agent string.

With HTTP, the identity of a client application is transmitted to the server via the User-Agent request header, as described by RFC 1945. For a browser, this might be:

  "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1; GTB6.6)"

For other applications, the unofficial 'standard' is to use pairs of space separated ApplicationName/version values. The default value for Mascot Parser version 2.3.4 and later is

"MascotParser/version wininet/version" for Windows and
"MascotParser/version curl/version" for Linux.

The default value for Mascot Parser version 2.3.3 and earlier is

"msparser wininet 1.0" for Windows and
"ms-parser (curllib) V1.0" for all the Unix platforms.

It is normally more useful to prepend this with the the name and version of the client application. For example, for Mascot Distiller, suitable code might be:

   setUserAgent("Mascot Distiller/2.3.0 " + getUserAgent());

Returns: the current agent string.

Examples: http_helper_getstring.cpp.

◆ isUseHTTPProxyForFTP()

bool isUseHTTPProxyForFTP ( ) const

Return true if HTTP proxy settings should be used for FTP.

This setting allows making FTP requests through the HTTP proxy. Note that the HTTP proxy server must explicitly support such "tunneling".

Returns: Enabled (true) or disabled (false).

◆ isUseHTTPProxyForHTTPS()

bool isUseHTTPProxyForHTTPS ( ) const

Return true if HTTP proxy settings should be used for HTTPS.

This setting allows making HTTPS requests through the HTTP proxy. Note that the HTTP proxy server must explicitly support such "tunneling".

Returns: Enabled (true) or disabled (false).

◆ operator=()

ms_connection_settings & operator= ( const ms_connection_settings & right )

C++ style assignment operator.

Note: Only used by C++ programs, and internally.

Parameters

right An ms_connection_settings object

Returns: Reference to the ms_connection_settings instance.

◆ proxyTypeStringToEnum()

int proxyTypeStringToEnum ( std::string str )

static

Convert proxy type string to PROXY_TYPE.

Parameters

str	Case-insensitive proxy type, one of "none", "auto", "specify", "registry", "wpad", "environment".

Returns: The matching value in PROXY_TYPE, or -1 if str matches no known proxy type.

◆ proxyTypeToString()

std::string proxyTypeToString ( int type )

static

Convert PROXY_TYPE to canonical string.

Parameters

type	One of the PROXY_TYPE values.

Returns: String representation of the value, one of None, Auto, Registry, Specify, WPAD, Environment. If type does not match any known value, the function returns the empty string.

◆ setConnectionTimeout()

void setConnectionTimeout ( int timeout )

Sets the HTTP connection timeout.

The default value is 60 seconds.

Parameters

timeout is the timeout in seconds before a connection will fail.

◆ setHttpPassword()

void setHttpPassword ( const std::string httpPassword )

Sets the password for an authenticated web server.

Parameters

httpPassword is the password required to access an authenticated web server.

Examples: http_helper_getstring.cpp.

◆ setHttpProtocol()

void setHttpProtocol ( ms_connection_settings::HTTP_PROTOCOL httpProtocol )

Sets the version of the HTTP protocol to be used.

The default value for Windows is HTTP_SYSTEM_DEFAULT and the default type for all the Unix platforms is HTTP_1_1.

Parameters

httpProtocol Specifies whether HTTP 1.0, 1.1 or the system default is used when connecting via HTTP to a Mascot Server.

◆ setHttpUsername()

void setHttpUsername ( const std::string httpUsername )

Sets the username for an authenticated web server.

Parameters

httpUsername is the user name required to access an authenticated web server.

Examples: http_helper_getstring.cpp.

◆ setProxyPassword()

void setProxyPassword ( const std::string proxyUserPassword )

Sets the password for an authenticated proxy server.

Parameters

proxyUserPassword is the password required to access an authenticated proxy server.

◆ setProxyServer()

void setProxyServer ( const std::string proxyServer )

Sets the name of the proxy server.

Calling this function with a non-zero length string will also set the proxy type to ms_connection_settings::PROXY_TYPE_SPECIFY.

See also: setProxyServerType()

Parameters

proxyServer is the URL of the proxy server.

◆ setProxyServerType()

void setProxyServerType ( ms_connection_settings::PROXY_TYPE proxyType )

Specifies how proxy server information will be obtained.

The default value is PROXY_TYPE_AUTO. If setProxyServer() is called with a non zero length string, then this type is automatically set to PROXY_TYPE_SPECIFY.

See also: setProxyServer()

Parameters

proxyType is the way in which information about the proxy server can be obtained.

◆ setProxyUsername()

void setProxyUsername ( const std::string proxyUserName )

Sets the user name for an authenticated proxy server.

Parameters

proxyUserName is the user name required to access an authenticated proxy server.

◆ setRedirectPolicy()

void setRedirectPolicy ( ms_connection_settings::REDIRECT_POLICY redirectPolicy )

Sets the policy for HTTP redirection.

The default value for Windows is REDIRECT_POLICY_DISALLOW_HTTPS_TO_HTTP.

Parameters

redirectPolicy controls what types of redirection request are allowed.

◆ setSessionID()

void setSessionID ( const std::string sessionID )

Sets the Mascot security sessionID to be used for the connection.

A session ID is used if Mascot Security is enabled; see Mascot security and authentication module.

Parameters

sessionID is the session ID string which can be retrieved using ms_session::ms_session() when running on the Mascot Server or, for an application using http, by calling ms_http_client::userLogin (which in turn calls the login.pl script on the Mascot Server.

Examples: config_enzymes.cpp, config_fragrules.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_quantitation.cpp, and config_taxonomy.cpp.

◆ setUseHTTPProxyForFTP()

void setUseHTTPProxyForFTP ( bool value )

Enable or disable use of an HTTP proxy server for an FTP request.

This setting allows making FTP requests through the HTTP proxy. Note that the HTTP proxy server must explicitly support such "tunneling".

Parameters

value Enable (true) or disable (false).

◆ setUseHTTPProxyForHTTPS()

void setUseHTTPProxyForHTTPS ( bool value )

Enable or disable use of an HTTP proxy server for an HTTPS request.

This setting allows making HTTPS requests through the HTTP proxy. Note that the HTTP proxy server must explicitly support such "tunneling".

Parameters

value Enable (true) or disable (false).

◆ setUserAgent()

void setUserAgent ( const std::string userAgent )

Set the user agent string.

With HTTP, the identity of a client application is transmitted to the server via the User-Agent request header, as described by RFC 1945. For a browser, this might be:

  "Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1; GTB6.6)"

For other applications, the unofficial 'standard' is to use pairs of space separated ApplicationName/version values.

The default value for Mascot Parser version 2.5.0 and later is

"MascotParser/version winhttp/5.1" for Windows and
"MascotParser/version curl/version" for Linux.

The default value for Mascot Parser version 2.3.4 to 2.4.x is

"MascotParser/version wininet/version" for Windows and
"MascotParser/version curl/version" for Linux.

The default value for Mascot Parser version 2.3.3 and earlier is

"msparser wininet 1.0" for Windows and
"ms-parser (curllib) V1.0" for all the Unix platforms.

It is normally more useful to prepend this with the the name and version of the client application. For example, for Mascot Distiller, suitable code might be:

   setUserAgent("Mascot Distiller/2.3.0 " + getUserAgent());

Parameters

userAgent is the new agent string.

Examples: http_helper_getstring.cpp.

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

ms_connection_settings.hpp
ms_connection_settings.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ HTTP_PROTOCOL

◆ PROXY_TYPE

◆ REDIRECT_POLICY

Constructor & Destructor Documentation

◆ ms_connection_settings() [1/2]

◆ ms_connection_settings() [2/2]

◆ ~ms_connection_settings()

Member Function Documentation

◆ copyFrom()

◆ defaultValues()

◆ getConnectionTimeout()

◆ getHttpPassword()

◆ getHttpProtocol()

◆ getHttpUsername()

◆ getProxyPassword()

◆ getProxyServer()

◆ getProxyServerType()

◆ getProxyUserAndPassword()

◆ getProxyUsername()

◆ getRedirectPolicy()

◆ getSessionID()

◆ getUserAgent()

◆ isUseHTTPProxyForFTP()

◆ isUseHTTPProxyForHTTPS()

◆ operator=()

◆ proxyTypeStringToEnum()

◆ proxyTypeToString()

◆ setConnectionTimeout()

◆ setHttpPassword()

◆ setHttpProtocol()

◆ setHttpUsername()

◆ setProxyPassword()

◆ setProxyServer()

◆ setProxyServerType()

◆ setProxyUsername()

◆ setRedirectPolicy()

◆ setSessionID()

◆ setUseHTTPProxyForFTP()

◆ setUseHTTPProxyForHTTPS()

◆ setUserAgent()