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

ms_connection_settings Class Reference
[Accessing a Mascot Server using HTTP]

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

#include <ms_connection_settings.hpp>

List of all members.

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_settingsoperator= (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:

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

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.

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.

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

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 ( 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:
sessionIDis the session ID string retrieved either from login.pl or from ms_session::ms_session().
proxyServeris the URL of the proxy server, if any.
proxyUserNameis the user name for an authenticated proxy server.
proxyUserPasswordis the password for an authenticated proxy server.

Destructor.

Called automatically.


Member Function Documentation

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:
rightValid pointer to a ms_connection_settings object
void defaultValues (  )

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

Sets all members to their default values:

int getConnectionTimeout (  ) const

Returns the HTTP connection timeout.

The default value is 60 seconds.

Returns:
The timeout in seconds before a connection will fail.
std::string getHttpPassword (  ) const

Gets the password for an authenticated web server.

Returns:
The HTTP password.
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.
std::string getHttpUsername (  ) const

Gets the username for an authenticated web server.

Returns:
The HTTP user name.
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.
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.
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.
std::string getProxyUserAndPassword (  ) const

Get the combined username and password -- if any.

Returns:
A string in the format username:password.
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.
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.
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().
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.
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).
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).
ms_connection_settings & operator= ( const ms_connection_settings right )

C++ style assignment operator.

Note:
Only used by C++ programs, and internally.
Parameters:
rightAn ms_connection_settings object
Returns:
Reference to the ms_connection_settings instance.
int proxyTypeStringToEnum ( std::string  str ) [static]

Convert proxy type string to PROXY_TYPE.

Parameters:
strCase-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.
std::string proxyTypeToString ( int  type ) [static]

Convert PROXY_TYPE to canonical string.

Parameters:
typeOne 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.
void setConnectionTimeout ( int  timeout )

Sets the HTTP connection timeout.

The default value is 60 seconds.

Parameters:
timeoutis the timeout in seconds before a connection will fail.
void setHttpPassword ( const std::string  httpPassword )

Sets the password for an authenticated web server.

Parameters:
httpPasswordis the password required to access an authenticated web server.
Examples:
http_helper_getstring.cpp.
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:
httpProtocolSpecifies whether HTTP 1.0, 1.1 or the system default is used when connecting via HTTP to a Mascot Server.
void setHttpUsername ( const std::string  httpUsername )

Sets the username for an authenticated web server.

Parameters:
httpUsernameis the user name required to access an authenticated web server.
Examples:
http_helper_getstring.cpp.
void setProxyPassword ( const std::string  proxyUserPassword )

Sets the password for an authenticated proxy server.

Parameters:
proxyUserPasswordis the password required to access an authenticated proxy server.
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:
proxyServeris the URL of the proxy server.
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:
proxyTypeis the way in which information about the proxy server can be obtained.
void setProxyUsername ( const std::string  proxyUserName )

Sets the user name for an authenticated proxy server.

Parameters:
proxyUserNameis the user name required to access an authenticated proxy server.
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:
redirectPolicycontrols what types of redirection request are allowed.
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:
sessionIDis 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.
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:
valueEnable (true) or disable (false).
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:
valueEnable (true) or disable (false).
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:
userAgentis the new agent string.
Examples:
http_helper_getstring.cpp.

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:31