This class enables access to a Mascot server using HTTP. More...

#include <ms_http_client.hpp>

Inheritance diagram for ms_http_client:

Collaboration diagram for ms_http_client:

[legend]

Public Types
enum	ChangePasswordResultCode { CP_SUCCESS , CP_UNKNOWNUSER , CP_INCORRECTPASSWORD , CP_BADNEWPASSWORD , CP_UNSPECIFIEDERROR }
	Definitions for the possible responses to an attempt to change a password. More...

enum	LoginResultCode { L_SUCCESS , L_SECURITYDISABLED , L_UNKNOWNUSER , L_INCORRECTPASSWORD , L_PASSWORDEXPIRED , L_WEBAUTHENTICATIONFAILED , L_GUESTLOGINDISABLED , L_UNSPECIFIEDERROR }
	Definitions for the types of response from the login program on the Mascot server. More...

Public Member Functions
	ms_http_client (const ms_http_client &src)

	ms_http_client (const std::string &baseUrl, ms_connection_settings settings)
	Constructor to provide access to the Mascot server.

virtual	~ms_http_client ()
	Destructor.

void	appendErrors (const ms_errors &src)
	Copies all errors from another instance and appends them at the end of own list.

std::string	baseUrl () const
	Returns the base URL for the Mascot server.

ChangePasswordResultCode	changePassword (const std::string &userName, const std::string &oldPassword, const std::string &newPassword)
	Change the password for a user. The user's old password must be supplied.

void	clearAllErrors ()
	Remove all errors from the current list of errors.

ms_connection_settings	connectionSettings () const
	Returns the HTTP connection settings.

void	copyFrom (const ms_errors *right)
	Use this member to make a copy of another instance.

void	copyFrom (const ms_http_client *right)

const ms_errs *	getErrorHandler () const
	Retrive the error object using this function to get access to all errors and error parameters.

bool	getIsDatabaseActive (const std::string &databaseName, bool &returnIsActive)
	Queries whether the specified database is available for searching. Returns true if successful.

bool	getIsSecurityEnabled (bool &returnIsSecurityEnabled, std::string &returnUnsecuredSessionId)
	Determine if Mascot Security is enabled on the Mascot Server.

bool	getIsWebAuthenticationEnabled (bool &returnIsWebAuthenticationEnabled, std::string &returnWebAuthenticatedSessionId)
	Determine if Mascot Security is setup to use Web Authentication.

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	getOsName (std::string &osname)
	Queries the operating system running on the server. Returns true if successful.

bool	getVersion (int &major, int &minor, int &part3, int &part4)
	Queries the version of Mascot running on the server. Returns true if successful.

bool	isValid () const
	Call this function to determine if there have been any errors.

ms_http_client &	operator= (const ms_http_client &right)

void	setBaseUrl (const std::string &baseUrl)
	Sets the base URL for the Mascot server.

void	setConnectionSettings (const ms_connection_settings &settings)
	Sets the HTTP connection settings.

LoginResultCode	userLogin (const std::string &username, const std::string &password, ms_http_client_session &returnSession)
	Attempts to log into the Mascot server using the supplied credentials.

Detailed Description

This class enables access to a Mascot server using HTTP.

Creating an ms_http_client object establishes an HTTP connection to the Mascot Server and provides a number of utility functions:

Log in to Mascot Security
Determine the version of Mascot running on the server
Discover the OS being run on the server
Change the password of a Mascot user (if permitted)
Determine if a particular database is active

Once the userLogin function has been called, searches can be submitted and results retrieved using ms_http_client_search

Member Enumeration Documentation

◆ ChangePasswordResultCode

enum ChangePasswordResultCode

Definitions for the possible responses to an attempt to change a password.

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

Enumerator
CP_SUCCESS	The password was changed successfully.
CP_UNKNOWNUSER	The user ID was not recognised. No password was changed.
CP_INCORRECTPASSWORD	The old password supplied was incorrect. No password was changed.
CP_BADNEWPASSWORD	The new password could not be used (e.g. too short). No password was changed.
CP_UNSPECIFIEDERROR	An error occurred. No further information is available.

◆ LoginResultCode

enum LoginResultCode

Definitions for the types of response from the login program on the Mascot server.

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

Enumerator
L_SUCCESS	The function completed successfully.
L_SECURITYDISABLED	Security is disabled on the Mascot server.
L_UNKNOWNUSER	The user ID supplied was not recognised by the Mascot server.
L_INCORRECTPASSWORD	The password supplied for the specified user was incorrect.
L_PASSWORDEXPIRED	The password supplied for the specified user has expired.
L_WEBAUTHENTICATIONFAILED	Web authentication failed for the currently logged in user.
L_GUESTLOGINDISABLED	The guest login could not be accessed because it is disabled on the server.
L_UNSPECIFIEDERROR	An error occurred. No further information is available.

Constructor & Destructor Documentation

◆ ms_http_client() [1/2]

ms_http_client	(	const std::string &	baseUrl,
		ms_connection_settings	settings
	)

Constructor to provide access to the Mascot server.

Make a connection to a Mascot Server using HTTP.

Parameters

baseUrl	The URL of the Mascot server CGI directory. For example "http://your-server/mascot/cgi/". Must end with the /cgi/
settings	Settings that control the connection to the Mascot server.

◆ ~ms_http_client()

~ms_http_client ( )

virtual

Destructor.

Called automatically.

◆ ms_http_client() [2/2]

ms_http_client ( const ms_http_client & src )

Parameters

src	is the source to initialise from

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

std::string baseUrl ( ) const

Returns the base URL for the Mascot server.

This typically ends with '/cgi/'.

Returns: The URL of the Mascot server CGI directory. For example "http://your-server/mascot/cgi/".

◆ changePassword()

ms_http_client::ChangePasswordResultCode changePassword	(	const std::string &	username,
		const std::string &	oldPassword,
		const std::string &	newPassword
	)

Change the password for a user. The user's old password must be supplied.

The function is implemented by calling ms_http_helper::httpGetString with the command:

login.pl?action=newpassword&username=username&password=oldPassword&newpw1=newPassword&newpw2=newPassword

Parameters

username	The name of the user for whom the password is to be changed.
oldPassword	The current (before the change) password for the user.
newPassword	The new password that is to be set for the user.

Returns: The final result of the attempt to change the password.

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

ms_connection_settings connectionSettings ( ) const

Returns the HTTP connection settings.

Returns: Settings that control the HTTP connection to the Mascot 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_client * 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.

◆ getIsDatabaseActive()

bool getIsDatabaseActive	(	const std::string &	databaseName,
		bool &	returnIsActive
	)

Queries whether the specified database is available for searching. Returns true if successful.

If the function fails then the return value is false; error messages may be retrieved from the ms_errors base class.

The function is implemented by calling ms_http_helper::httpGetString with the command:

client.pl?db_active&db_name=databaseName

If the databaseName is not available for searching on the server, the function can still return true, but returnIsActive will be false.

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

Parameters

[in]	databaseName	The name of the database to look for on the Mascot server.
[out]	returnIsActive	Returns true if the named database is available on the Mascot server.

Returns: True if the function completed successfully.

◆ getIsSecurityEnabled()

bool getIsSecurityEnabled	(	bool &	returnIsSecurityEnabled,
		std::string &	returnUnsecuredSessionId
	)

Determine if Mascot Security is enabled on the Mascot Server.

If the function fails then the return value is false; error messages may be retrieved from the ms_errors base class.

The function is implemented by calling ms_http_helper::httpGetString with the command:

login.pl?action=issecuritydisabled

If security is disabled then the session ID 'all_secdisabledsession ' will be returned in returnUnsecuredSessionId. If security is enabled, then an empty string will be returned, even if the guest account is enabled. See matrix_science::ms_session for further information.

Many client applications will not need to call this function but it is useful for determining if it is necessary to prompt the user for a username and password.

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

Parameters

[out]	returnIsSecurityEnabled	Returns true if security is enabled. This is only valid if the function succeeds.
[out]	returnUnsecuredSessionId	Returns a session ID or an empty string. If security is disabled, this will return all_secdisabledsession This value is only valid if the function succeeds.

Returns: True if the function completed successfully.

◆ getIsWebAuthenticationEnabled()

bool getIsWebAuthenticationEnabled	(	bool &	returnIsWebAuthenticationEnabled,
		std::string &	returnWebAuthenticatedSessionId
	)

Determine if Mascot Security is setup to use Web Authentication.

If the function fails then the return value is false; error messages may be retrieved from the ms_errors base class.

The function is implemented by calling ms_http_helper::httpGetString with the command:

login.pl?action=webauthentication

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

Parameters

[out]	returnIsWebAuthenticationEnabled	Returns true if web authentication is enabled for the user logged into the web server.
[out]	returnWebAuthenticatedSessionId	Returns a session ID that can be used, or blank if web authentication failed or is not enabled for this user. This is only valid if the function succeeds.

Returns: True if the function completed successfully.

◆ 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.

◆ getOsName()

bool getOsName ( std::string & osname )

Queries the operating system running on the server. Returns true if successful.

If the function fails then the return value is false; error messages may be retrieved from the ms_errors base class.

The function is implemented by calling ms_http_helper::httpGetString with the command:

client.pl?osname

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

Parameters

[out] osname Returns name of the Mascot server's operating system; either 'linux' or 'MSWin32'

Returns: True if the function completed successfully.

◆ getVersion()

bool getVersion	(	int &	major,
		int &	minor,
		int &	part3,
		int &	part4
	)

Queries the version of Mascot running on the server. Returns true if successful.

If the version returned by the Mascot server does not contain all four parts, the remaining parts are set to zero.

The function is implemented by calling ms_http_helper::httpGetString with the command:

client.pl?version

If the function fails then the return value is false; error messages may be retrieved from the ms_errors base class.

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

Parameters

[out]	major	Returns the major version number. For example, version 2.4.1.24 would return 2.
[out]	minor	Returns the minor version number. For example, version 2.4.1.24 would return 4.
[out]	part3	Returns part 3 of the version number. For example, version 2.4.1.24 would return 1.
[out]	part4	Returns part 4 of the version number. For example, version 2.4.1.24 would return 24.

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

ms_http_client & operator= ( const ms_http_client & right )

Parameters

right is the source to initialise from

Returns: reference to the current object

◆ setBaseUrl()

void setBaseUrl ( const std::string & baseUrl )

Sets the base URL for the Mascot server.

This typically ends with '/cgi/'. The baseUrl would normally be passed in the constructor.

Parameters

baseUrl The URL of the Mascot server CGI directory.

◆ setConnectionSettings()

void setConnectionSettings ( const ms_connection_settings & settings )

Sets the HTTP connection settings.

The settings control the HTTP connection to the Mascot server.

Parameters

settings The new settings for the server connection.

◆ userLogin()

ms_http_client::LoginResultCode userLogin	(	const std::string &	username,
		const std::string &	password,
		ms_http_client_session &	returnSession
	)

Attempts to log into the Mascot server using the supplied credentials.

If security is disabled on the Mascot server (or the server version is 2.1 or earlier) then the supplied username and password are ignored and an anonymous session is created.

If a username is supplied then the username and password combination will be authenticated on the Mascot server before a session is created.

If no username is supplied, a session using web authentication will be attempted. This can only succeed if the user name supplied for web server authentication matches a user name configured in Mascot security as a web authenticated user.

If no username is supplied and web authentication fails, a session using the guest account will be attempted (however, the guest account may be disabled, in which case the function will fail).

The logging level and logging file (if any) in the returnSession are set to be the same as in the ms_http_client object. Any existing errors in returnSession are cleared.

The function is implemented by calling ms_http_helper::httpGetString with a number of different commands, for example:

login.pl?action=login&username=username&password=password

Parameters

[in]	username	The name of the user to login with, or blank for a web authenticated or anonymous session.
[in]	password	The password associated with the user name.
[out]	returnSession	Returns a session if the login was successful. The ms_http_client_session object passed should be created using the default constructor and when calling from Perl, pass the object in the parameter list.

Returns: The result of the Mascot login attempt.

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

ms_http_client.hpp
ms_http_client.cpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ ChangePasswordResultCode

◆ LoginResultCode

Constructor & Destructor Documentation

◆ ms_http_client() [1/2]

◆ ~ms_http_client()

◆ ms_http_client() [2/2]

Member Function Documentation

◆ appendErrors()

◆ baseUrl()

◆ changePassword()

◆ clearAllErrors()

◆ connectionSettings()

◆ copyFrom() [1/2]

◆ copyFrom() [2/2]

◆ getErrorHandler()

◆ getIsDatabaseActive()

◆ getIsSecurityEnabled()

◆ getIsWebAuthenticationEnabled()

◆ getLastError()

◆ getLastErrorString()

◆ getOsName()

◆ getVersion()

◆ isValid()

◆ operator=()

◆ setBaseUrl()

◆ setConnectionSettings()

◆ userLogin()