This gives access to a Mascot session so searches may be submitted. More...

#include <ms_http_client_session.hpp>

Inheritance diagram for ms_http_client_session:

Collaboration diagram for ms_http_client_session:

[legend]

Public Types
enum	SequenceShowOptions { SHOW_PI = 0x0001 , SHOW_TITLE = 0x0002 , SHOW_LENGTH = 0x0004 , SHOW_SEQUENCE = 0x0008 , SHOW_REFERENCE = 0x0010 , SHOW_NONE = 0 , SHOW_ALL = 0xFFFF }
	Information to include in a request for sequence data. More...

Public Member Functions
	ms_http_client_session ()
	Create an empty session.

	ms_http_client_session (const ms_http_client_session &src)

	ms_http_client_session (const ms_http_helper connection, const std::string sessionId)
	Construct a session object that can be used to access the Mascot Server.

virtual	~ms_http_client_session ()
	Destructor.

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

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

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

void	copyFrom (const ms_http_client_session *right)

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

bool	getIsPermitted (ms_security_tasks::TASKID taskType, bool &returnIsPermitted)
	Returns true if the security token is allowed for this session.

bool	getIsXmlUploadedList (const std::vector< std::string > &taskIds, std::vector< int > &xmlUploaded)
	Queries if the specified searches have had Mascot Distiller quantitation XML uploaded.

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	getSequenceFile (const std::string &database, const std::vector< std::string > &accessionNames, const std::vector< int > &accessionFrames, const std::string &filename, const SequenceShowOptions options=SHOW_ALL)
	Download sequence information for a set of accessions.

std::string	getSessionID () const
	Returns the Mascot session ID.

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

bool	logout ()
	Close the Mascot session.

ms_http_client_session &	operator= (const ms_http_client_session &right)

bool	submitSearch (ms_http_client_search &returnTask, const std::string &httpHeader, const std::string &prologue, const std::string &filename, const std::string &epilogue, ms_http_helper_progress &progress, bool batch=false)
	Submit a search to the Mascot server.

Detailed Description

This gives access to a Mascot session so searches may be submitted.

Create an ms_http_client_session object by calling: ms_http_client::userLogin and this object can then be used to submit a search by calling ms_http_client_session::submitSearch

Multiple searches and data requests may be made using the same ms_http_client_session. When access to the Mascot Server is complete, call logout

Server side documentation for sessions is here

Member Enumeration Documentation

◆ SequenceShowOptions

enum SequenceShowOptions

Information to include in a request for sequence data.

Add the flags together to include multiple data items per sequence. Pass the enum to getSequenceFile

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

Enumerator
SHOW_PI	Show the isoelectric point (as a pH).
SHOW_TITLE	Show the single-line title.
SHOW_LENGTH	Show the length of the sequence.
SHOW_SEQUENCE	Show the sequence itself.
SHOW_REFERENCE	Show the full entry annotation text.
SHOW_NONE	Show none of the information.
SHOW_ALL	Show all available information.

Constructor & Destructor Documentation

◆ ms_http_client_session() [1/3]

ms_http_client_session ( )

Create an empty session.

Create an empty session. This is normally passed to ms_http_client::userLogin to populate it.

◆ ms_http_client_session() [2/3]

ms_http_client_session	(	const ms_http_helper	connection,
		const std::string	sessionId
	)

Construct a session object that can be used to access the Mascot Server.

This is used internally by ms_http_client and should not normally be called by a client application.

Parameters

connection	The associated ms_http_helper.
sessionId	The Mascot Server session ID.

◆ ~ms_http_client_session()

~ms_http_client_session ( )

virtual

Destructor.

This tidies up any HTTP connection that is still open by calling logout() if necessary.

◆ ms_http_client_session() [3/3]

ms_http_client_session ( const ms_http_client_session & 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.

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

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

◆ getIsPermitted()

bool getIsPermitted	(	ms_security_tasks::TASKID	taskType,
		bool &	returnIsPermitted
	)

Returns true if the security token is allowed for this session.

Permissions are set in the Mascot Security Administration pages.

The most relevant tokens for third party clients are:

SECTASK_ALLOWPMF - Allow pmf searches.
SECTASK_ALLOWMSMS - Allow ms/ms (and SQ) searches.
SECTASK_ALLOWMSMSNOENZYME - Allow ms/ms no enzyme searches.
SECTASK_ALLOWPMFNOENZYME - Allow no enzyme pmf searches.
SECTASK_ALLFASTA - Allow all fasta databases to be searched.
SECTASK_NAMEDFASTA - Special fasta databases that override the default setting.
SECTASK_DAEMONCLIENT - Mascot Daemon is allowed to submit searches.
SECTASK_DISTILLERCLIENT - Mascot Distiller is allowed to submit searches.

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

Parameters

[in]	taskType	The security token being queried.
[out]	returnIsPermitted	Returns true if the security task type is permitted on this session, false if not.

Returns: Returns true if the function completed successfully.

◆ getIsXmlUploadedList()

bool getIsXmlUploadedList	(	const std::vector< std::string > &	taskIds,
		std::vector< int > &	xmlUploaded
	)

Queries if the specified searches have had Mascot Distiller quantitation XML uploaded.

The query can be for any number of searches. If the number of searches is too large for a single query to the server then multiple queries will be made.

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

Parameters

[in]	taskIds	The task IDs of the searches.
[out]	xmlUploaded	Set to the same size as taskIds. Non-zero if Mascot Distiller quantitation XML has been uploaded for that search.

Returns: True if the query 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.

◆ getSequenceFile()

bool getSequenceFile	(	const std::string &	database,
		const std::vector< std::string > &	accessionNames,
		const std::vector< int > &	accessionFrames,
		const std::string &	filename,
		const SequenceShowOptions	options = `SHOW_ALL`
	)

Download sequence information for a set of accessions.

The retrieved file is in XML.

If the database is not active on the Mascot server then the body opf the XML document will be empty.

The frame number is used if the frames collection has an entry for a name and it is not -1.

See Using STL vector classes vectori, vectord and VectorString in Perl, Java, Python and C#.

Parameters

database	The name of the database on the Mascot server fromn which the data is to be retrieved.
accessionNames	A collection of accession names for the peptides or NA sequences to be retrieved.
accessionFrames	A collection of frames. This only has meaning for an NA database. 0 means return the NA sequence. A number between 1 and 6 means translate the NA sequence in that frame and return the AA sequence.
filename	The name of the local file to be populated with the retrieved information. S
options	The types of information to be included in the output file.

Returns: Returns true if the function completed successfully.

◆ getSessionID()

std::string getSessionID ( ) const

Returns the Mascot session ID.

This may change during any call that accesses the Mascot server as the session on the server may have expired and a new one will be automatically created.

Returns: the current session id

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

◆ logout()

bool logout ( )

Close the Mascot session.

Called automatically by the destructor.

You must login again to create a new Mascot session in order to use the Mascot server again.

Returns: The final result of the attempt to logout.

◆ operator=()

ms_http_client_session & operator= ( const ms_http_client_session & right )

Parameters

right is the source to initialise from

Returns: reference to the current object

◆ submitSearch()

bool submitSearch	(	ms_http_client_search &	returnTask,
		const std::string &	httpHeader,
		const std::string &	prologue,
		const std::string &	filename,
		const std::string &	epilogue,
		ms_http_helper_progress &	progress,
		bool	batch = `false`
	)

Submit a search to the Mascot server.

The search is submitted using a POST request to the search executable (normally nph-mascot.exe) on the Mascot Server.

This function makes http calls to the Mascot Server to create a unique taskID and this is returned in the ms_http_client_search object and can be accessed using ms_http_client_search::getSearchTaskID . The name of the search application in use on the Mascot server is also retrieved from the server as part of this process.

The search parameters and peak list are combined into a MIME format file using the prologue, filename and epilogue parameters.

This function normally only returns when all the data has been sent. If the abort submission function is called then it will stop sending data at a convenient point and return early.

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

Parameters

returnTask	The search object that can be used to monitor progress and then retrieve results. See Maintaining object references: two rules of thumb.
httpHeader	The HTTP header line, specifying the content type and the MIME separator string. For example: "Content-Type: multipart/mixed; boundary=---------FormBoundary4C9ByKKVofH"
prologue	Text sent as the first part of the content of the HTTP POST. This will normally contain the search parameters. For an example, see http_client.pl
filename	The name of a file, the content of which is sent after the prologue text and before the epilogue text. This can be an MGF or other peak list data file.
epilogue	Text sent as the last part of the content of the HTTP POST. For example, "-----------FormBoundary4C9ByKKVofH--"
progress	The progress information is maintained as the data is uploaded to the server. The upload may be aborted by calling setAbort. See Maintaining object references: two rules of thumb.
batch	If true, the search will be submitted with the -batch switch, which will keep the search alive on IIS if the connection is broken. This can only be used with Mascot 2.5 or later, and will cause an error if set to true when submitting a search on an older version of Mascot [default=false].

Returns: Returns true if the function completed successfully.

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

ms_http_client_session.hpp
ms_http_client_session.cpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ SequenceShowOptions

Constructor & Destructor Documentation

◆ ms_http_client_session() [1/3]

◆ ms_http_client_session() [2/3]

◆ ~ms_http_client_session()

◆ ms_http_client_session() [3/3]

Member Function Documentation

◆ appendErrors()

◆ clearAllErrors()

◆ copyFrom() [1/2]

◆ copyFrom() [2/2]

◆ getErrorHandler()

◆ getIsPermitted()

◆ getIsXmlUploadedList()

◆ getLastError()

◆ getLastErrorString()

◆ getSequenceFile()

◆ getSessionID()

◆ isValid()

◆ logout()

◆ operator=()

◆ submitSearch()