Matrix Science header
Public Types | Public Member Functions

ms_http_client Class Reference
[Accessing a Mascot Server using HTTP]

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

#include <ms_http_client.hpp>

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

List of all members.

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 std::string &baseUrl, ms_connection_settings settings)
 Constructor to provide access to the Mascot server.
 ms_http_client (const ms_http_client &src)
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_errsgetErrorHandler () 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_clientoperator= (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:

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


Member Enumeration Documentation

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.

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 ( 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:
baseUrlThe URL of the Mascot server CGI directory. For example "http://your-server/mascot/cgi/". Must end with the /cgi/
settingsSettings that control the connection to the Mascot server.
~ms_http_client (  ) [virtual]

Destructor.

Called automatically.

ms_http_client ( const ms_http_client src )
Parameters:
srcis the source to initialise from

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.
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/".
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:
usernameThe name of the user for whom the password is to be changed.
oldPasswordThe current (before the change) password for the user.
newPasswordThe new password that is to be set for the user.
Returns:
The final result of the attempt to change the password.
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.
ms_connection_settings connectionSettings (  ) const

Returns the HTTP connection settings.

Returns:
Settings that control the HTTP connection to the Mascot server.
void copyFrom ( const ms_http_client 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.
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]databaseNameThe name of the database to look for on the Mascot server.
[out]returnIsActiveReturns true if the named database is available on the Mascot server.
Returns:
True if the function completed successfully.
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]returnIsSecurityEnabledReturns true if security is enabled. This is only valid if the function succeeds.
[out]returnUnsecuredSessionIdReturns 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.
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]returnIsWebAuthenticationEnabledReturns true if web authentication is enabled for the user logged into the web server.
[out]returnWebAuthenticatedSessionIdReturns 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.
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 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]osnameReturns name of the Mascot server's operating system; either 'linux' or 'MSWin32'
Returns:
True if the function completed successfully.
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]majorReturns the major version number. For example, version 2.4.1.24 would return 2.
[out]minorReturns the minor version number. For example, version 2.4.1.24 would return 4.
[out]part3Returns part 3 of the version number. For example, version 2.4.1.24 would return 1.
[out]part4Returns part 4 of the version number. For example, version 2.4.1.24 would return 24.
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.
ms_http_client & operator= ( const ms_http_client right )
Parameters:
rightis the source to initialise from
Returns:
reference to the current object
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:
baseUrlThe URL of the Mascot server CGI directory.
void setConnectionSettings ( const ms_connection_settings settings )

Sets the HTTP connection settings.

The settings control the HTTP connection to the Mascot server.

Parameters:
settingsThe new settings for the server connection.
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]usernameThe name of the user to login with, or blank for a web authenticated or anonymous session.
[in]passwordThe password associated with the user name.
[out]returnSessionReturns 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:

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