Used for submitting searches to a Mascot server and retrieving search results using HTTP(S). More...

#include <ms_http_client_search.hpp>

Inheritance diagram for ms_http_client_search:

Collaboration diagram for ms_http_client_search:

[legend]

Public Types
enum	DownloadOption { DO_NORMAL = 0 , DO_WITH_IONS = 1 }
	Definitions for downloading results. More...

enum	ReportTopSpecialValues { RT_auto = 0 , RT_file = -1 }
	Definitions for special 'report top' values when requesting results in XML format. More...

enum	SearchStatusCode { SS_UNKNOWN , SS_ASSIGNED , SS_QUEUED , SS_RUNNING , SS_COMPLETE , SS_ERROR , SS_SEARCH_CONTROL_ERROR }
	Definitions for the various states possible when querying about a running Mascot search. More...

enum	UploadResponseCode { UR_SUCCESS , UR_ACCESS_DENIED , UR_INVALID_TASKID , UR_NO_RESULT_FILENAME , UR_NO_RESULT_FILE , UR_FILE_ALREADY_EXISTS , UR_ERROR }
	Definitions for the various responses possible when uploading data to Mascot. More...

Public Member Functions
	ms_http_client_search (const ms_http_client_search &src)

	ms_http_client_search (ms_http_client_session &session, const std::string &searchTaskId)
	Access previously run search results.

virtual	~ms_http_client_search ()
	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_search *right)

bool	downloadDaemonResultsFile (std::string filename, ms_http_helper_progress &progress)
	Download the summary results of a search in the format used by Mascot Daemon.

bool	downloadPercolatorFile (std::string filename, ms_http_helper_progress &progress)
	Download the Percolator input and output files for the associated search.

bool	downloadResultsFile (std::string filename, ms_http_helper_progress &progress, DownloadOption options=DO_WITH_IONS)
	Download the results in dat28 (MIME) format.

bool	downloadResultsFileMSR (std::string filename, ms_http_helper_progress &progress, DownloadOption options=DO_WITH_IONS)
	Download the results in Mascot Search Results (MSR) format.

bool	downloadXmlResultsFile (std::string filename, ms_http_helper_progress &progress, int reportTop=RT_auto)
	Download the results of the search in XML format.

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

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	getResultsFileName (std::string &returnFileName)
	Return the path to the result file on the server (usually relative to the cgi directory).

std::string	getSearchTaskID () const
	Get the task ID of the associated Mascot search.

std::string	getSessionID () const
	Get the associated session ID.

bool	getStage (std::string &stage, int &step)
	Return the current stage and step of the search (Mascot 2.8.1 or later required).

bool	getStatus (SearchStatusCode &returnCode, int &statusValue)
	Return the current status of the search.

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

ms_http_client_search &	operator= (const ms_http_client_search &right)

std::string	sessionId () const
	Get the associated session ID.

bool	uploadDistillerXmlResultsFile (std::string filename, UploadResponseCode &responseCode, std::string &responseText)
	Upload a Mascot Distiller quantitation XML file to the server.

Detailed Description

Used for submitting searches to a Mascot server and retrieving search results using HTTP(S).

Use ms_http_client_search to follow the progress of a new search as it runs on the Mascot server and to retrieve the results from both new searches and old searches stored on the server.

The Mascot search must be run on the server within a Mascot session created by ms_http_client_session.

A previous search can be accessed by constructing a ms_http_client_search with a task identifier.

Member Enumeration Documentation

◆ DownloadOption

enum DownloadOption

Definitions for downloading results.

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

Enumerator
DO_NORMAL	Downloads a compressed results file with the peak list data removed. This is the normal download mode for Mascot Distiller, but most other applications should use DO_WITH_IONS.
DO_WITH_IONS	Download the complete results file. The file is downloaded as uncompressed text.

◆ ReportTopSpecialValues

enum ReportTopSpecialValues

Definitions for special 'report top' values when requesting results in XML format.

Otherwise can use a small positive integer (eg 1..50) See Using enumerated values and static const ints in Perl, Java, Python and C#.

Enumerator
RT_auto	Automatically determine the number of protein hits included in the report.
RT_file	Honour the number of hits specified when the search was submitted.

◆ SearchStatusCode

enum SearchStatusCode

Definitions for the various states possible when querying about a running Mascot search.

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

Enumerator
SS_UNKNOWN	The search task ID was not recognised as a recent Mascot task.
SS_ASSIGNED	The search task has been assigned but no search has been submitted.
SS_QUEUED	The search has been submitted, but it has been queued by the server.
SS_RUNNING	The search has started. The approximate percentage that has been completed is available.
SS_COMPLETE	The search has completed.
SS_ERROR	An error occurred when running the search. The Mascot error number is available from the getStatus call.
SS_SEARCH_CONTROL_ERROR	An error has occurred in the Mascot server application trying to get the search status. The error code is available and is documented in the Mascot Installation and Setup Manual (For example, ERR_TASKID_FAILOPEN = 1)

◆ UploadResponseCode

enum UploadResponseCode

Definitions for the various responses possible when uploading data to Mascot.

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

Enumerator
UR_SUCCESS	The upload completed successfully.
UR_ACCESS_DENIED	The upload was not permitted by Mascot Security.
UR_INVALID_TASKID	The upload failed due to not having a task identifier.
UR_NO_RESULT_FILENAME	The upload failed due to not having a result file name.
UR_NO_RESULT_FILE	The upload failed due to the result file not existing.
UR_FILE_ALREADY_EXISTS	The upload failed because the file already exists.
UR_ERROR	The upload failed due to an unspecified error.

Constructor & Destructor Documentation

◆ ms_http_client_search() [1/2]

ms_http_client_search	(	ms_http_client_session &	session,
		const std::string &	searchTaskId
	)

Access previously run search results.

This constructor does not validate the searchTaskId or session and does not call any scripts on the Mascot Server. It is recommended that getStatus() is called before calling other functions so that the searchTaskId and session can be validated.

Parameters

session	The associated session object.
searchTaskId	The Mascot task identifier used for the associated search.

◆ ~ms_http_client_search()

~ms_http_client_search ( )

virtual

Destructor;.

Called automatically.

◆ ms_http_client_search() [2/2]

ms_http_client_search ( const ms_http_client_search & 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_search * right )

The session object is copied, it is not created anew, cf the other constructors

Parameters

right is the source to initialise from

◆ downloadDaemonResultsFile()

bool downloadDaemonResultsFile	(	std::string	filename,
		ms_http_helper_progress &	progress
	)

Download the summary results of a search in the format used by Mascot Daemon.

Parameters

filename	The name of the local file for the results to be written to.
progress	The progress information is maintained as the data is downloaded from the server. The download may be aborted by calling setAbort. See Maintaining object references: two rules of thumb.

Returns: Returns true if the function completed successfully.

◆ downloadPercolatorFile()

bool downloadPercolatorFile	(	std::string	filename,
		ms_http_helper_progress &	progress
	)

Download the Percolator input and output files for the associated search.

Parameters

filename	The name of the local file for the results to be written to.
progress	The progress information is maintained as the data is downloaded from the server. The download may be aborted by calling setAbort. See Maintaining object references: two rules of thumb.

Returns: Returns true if the function completed successfully.

◆ downloadResultsFile()

bool downloadResultsFile	(	std::string	filename,
		ms_http_helper_progress &	progress,
		DownloadOption	options = `DO_WITH_IONS`
	)

Download the results in dat28 (MIME) format.

It is safest to call getStatus() before calling this function to validate the searchTaskId, because this function has more limited error reporting.

The results data is downloaded as dat28 (MIME) format file. This is the F1234.dat format created by Mascot Server 2.8 and earlier. See ms_http_client_search::downloadResultsFileMSR() for downloading the data in the Mascot Search Results (MSR) format, introduced in Mascot Server 3.0.

Downloading can fail if the task ID doesn't exist or there is some other server-side problem. These are reported as "problem=" lines by Mascot. In this case, downloadResultsFile() saves the text in filename and returns true (not false!) because the HTTP(S) transfer did succeed.

The caller should always check the file contents: 1) If it's a gzipped file, uncompress it; 2) if it starts with "problem=", report the error string; and 3) finally, use ms_mascotresfilebase::resfileType() to detect the file type.

Error conditions for HTTP(S) transfer:

ms_errs::ERR_MSP_HTTP_NORESPONSE - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_TRANSMISSION_FAILED - if HTTP(s) transfer fails
ms_errs::ERR_MSP_HTTP_OPENSESSIONFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_CLOSESESSIONFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_OPENCONNECTIONFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_CLOSECONNECTIONFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_OPENREQUESTFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_CLOSEREQUESTFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_QUERYSTATUSFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_OPENOUTPUTFILEFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_DOWNLOADFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_ABORTEDBYUSER - if aborted by user

Parameters

filename	The name of the local file for the results to be written to.
progress	The progress information is maintained as the data is downloaded from the server. The download may be aborted by calling setAbort. See Maintaining object references: two rules of thumb.
options	This contains the bit flags that controls how the file will be downloaded. It should be DO_NORMAL or a bitwise accumulation (boolean OR) of the other flags.

Returns: Returns true if the function completed successfully.

◆ downloadResultsFileMSR()

bool downloadResultsFileMSR	(	std::string	filename,
		ms_http_helper_progress &	progress,
		DownloadOption	options = `DO_WITH_IONS`
	)

Download the results in Mascot Search Results (MSR) format.

It is safest to call getStatus() before calling this function to validate the searchTaskId. This function has more limited error reporting.

The results data is saved as Mascot Search Results (MSR) file. This is an SQLite database, introduced in Mascot Server 3.0. See ms_http_client_search::downloadResultsFile() for downloading the data in the traditional, dat28 (MIME) format.

The data sent by the server is an SQL dump, which is saved in a temporary file in the same location as filename. If download succeeds, the MSR file is restored from the SQL dump and saved as filename. The temporary file is removed in both cases.

Downloading the results as MSR may fail if 1) the server is Mascot Server 2.8 or earlier or 2) if creating MSR files has been disabled by a configuration option. In this case, try ms_http_client_search::downloadResultsFile(), which should always succeed.

Downloading can fail if the task ID doesn't exist or there is some other server-side problem. These are reported as "problem=" lines by Mascot. In this case, downloadResultsFileMSR() reports the problem string as a fatal error and returns false. Note: This behaviour is different from downloadResultsFile(), which saves string in the output file and returns true if there is a "problem=" line.

The caller should always check the file contents using ms_mascotresfilebase::resfileType() to confirm it is an MSR file.

Error conditions for HTTP(S) transfer:

ms_errs::ERR_MSP_HTTP_NORESPONSE - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_TRANSMISSION_FAILED - if HTTP(s) transfer fails
ms_errs::ERR_MSP_HTTP_OPENSESSIONFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_CLOSESESSIONFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_OPENCONNECTIONFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_CLOSECONNECTIONFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_OPENREQUESTFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_CLOSEREQUESTFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_QUERYSTATUSFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_OPENOUTPUTFILEFAILED - if HTTP(S) transfer fails
ms_errs::ERR_MSP_HTTP_DOWNLOADFAILED - if HTTP(S) transfer fails or there is a "problem=" line
ms_errs::ERR_MSP_HTTP_ABORTEDBYUSER - if aborted by user

Error conditions for restoring the file from the SQL dump:

ms_errs::ERR_MSP_FAILED_TO_OPEN_FILE - if failing to open temp file
ms_errs::ERR_MSP_FAILED_TO_READ_FILE - if failing to read from temp file
ms_errs::ERR_MSP_MSR_CREATING_FILE - if failing to create the target file
ms_errs::ERR_MSP_MSR_WRITING_FILE - if failing to write to the target file
ms_zip::decompressMore() error conditions - if input is gzipped and fails to decompress
ms_errs::ERR_MSP_HTTP_ABORTEDBYUSER - if aborted by user

Parameters

filename	The name of the local file for the results to be written to.
progress	Progress information for the data downloaded from the server. The download and post-processing may be aborted by calling setAbort. See Maintaining object references: two rules of thumb.
options	This contains the bit flags that controls how the file will be downloaded. It should be DO_NORMAL or a bitwise accumulation (boolean OR) of the other flags.

Returns: Returns true if the function completed successfully.

◆ downloadXmlResultsFile()

bool downloadXmlResultsFile	(	std::string	filename,
		ms_http_helper_progress &	progress,
		int	reportTop = `RT_auto`
	)

Download the results of the search in XML format.

Use of this function is deprecated. Use downloadResultsFile instead.

Parameters

filename	The name of the local file for the results to be written to.
progress	The progress information is maintained as the data is downloaded from the server. The download may be aborted by calling setAbort. See Maintaining object references: two rules of thumb.
reportTop	The number of protein hits to include in the results.

Returns: Returns true if the function completed successfully.

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

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

◆ getResultsFileName()

bool getResultsFileName ( std::string & returnFileName )

Return the path to the result file on the server (usually relative to the cgi directory).

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

client.pl?result_file_name&task_id=searchTaskId

If the function fails because an invalid searchTaskId has been set, then the function will return false, returnFileName will be empty and the ms_errs::ERR_MSP_HTTP_GETRESULTSFILENAME error will be set.

It is safest to call getStatus() before calling this function to validate the searchTaskId etc. because this function has more limited error reporting.

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

Parameters

[out] returnFileName Returns the path to the result file on the server (usually relative to the cgi directory).

Returns: Returns true if the function completed successfully.

◆ getSearchTaskID()

std::string getSearchTaskID ( ) const

Get the task ID of the associated Mascot search.

Returns: The Mascot task identifier used for the associated search.

◆ getSessionID()

std::string getSessionID ( ) const

Get the associated session ID.

Returns: The associated Mascot Server session ID.

◆ getStage()

bool getStage	(	std::string &	stage,
		int &	step
	)

Return the current stage and step of the search (Mascot 2.8.1 or later required).

Can be called regularly while a submitted search is runing in order to determine search stage.

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

client.pl?status_current_stage&task_id=searchTaskId

If the function fails because an invalid searchTaskId has been set, or if the Mascot Server version is earlier than 2.8.1 then the function will return false, stage will be empty and step set to -1 and the ms_errs::ERR_MSP_HTTP_GETSEARCHSTAGE error will be set.

It is safest to call getStatus() before calling this function to validate the searchTaskId etc. because this function has more limited error reporting.

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

Parameters

[out]	stage	Returns the search stage text
[out]	step	Returns the search stage step

Returns: Returns true if the function completed successfully.

◆ getStatus()

bool getStatus	(	SearchStatusCode &	returnCode,
		int &	statusValue
	)

Return the current status of the search.

Can be called regularly while a submitted search is runing in order to determine status.

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

client.pl?status&task_id=searchTaskId

The value returned in statusValue depends on the returnCode:

SS_UNKNOWN - statusValue will be 0
SS_ASSIGNED - statusValue will be 0
SS_ERROR -
- a positive statusValue will be a Mascot Error code. A full list of value are available here
- A statusValue of -1 indicates that the search crashed without an error.
- A statusValue of -2 indicates that the search was terminated by a user.
SS_QUEUED - statusValue will be 0
SS_RUNNING - statusValue will be the percentage complete for the search.
SS_COMPLETE - statusValue will be 0
SS_SEARCH_CONTROL_ERROR - statusValue will be:
- ERR_TASKID_NOERROR = 0
- ERR_TASKID_FAILOPEN = 1
- ERR_TASKID_FAILCREATE = 2
- ERR_TASKID_FAILREAD = 3
- ERR_TASKID_FAILWRITE = 4
- ERR_TASKID_FAILCLOSE = 5
- ERR_TASKID_CHANGEDRECORD = 6
- ERR_TASKID_INVALIDMASCOTDAT = 7
- ERR_TASKID_MISSINGRESULTSFILE = 8
- ERR_TASKID_FILENAMETOOLONG = 9
- ERR_TASKID_SESSIONTIMEDOUT = 10
- ERR_TASKID_PERMISSIONDENIED = 11

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

Parameters

[out]	returnCode	Returns the current status code of the search task.
[out]	statusValue	Returns an optional value depending on the returnCode.

Returns: 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_search & operator= ( const ms_http_client_search & right )

Parameters

right is the source to initialise from

Returns: reference to the current object

◆ sessionId()

std::string sessionId ( ) const

inline

Get the associated session ID.

Deprecated:: Use getSessionID()

Returns: session id

◆ uploadDistillerXmlResultsFile()

bool uploadDistillerXmlResultsFile	(	std::string	filename,
		ms_http_client_search::UploadResponseCode &	responseCode,
		std::string &	responseText
	)

Upload a Mascot Distiller quantitation XML file to the server.

Uploads a Mascot Distiller quantitation XML file to the Mascot Server.

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

Parameters

[in]	filename	The path of the file to be uploaded.
[out]	responseCode	If the return value is true then this should be checked to see if the upload was accepted as valid.
[out]	responseText	The response from the Mascot server.

Returns: Returns true if the file was uploaded, not whether the upload was accepted as valid.

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

ms_http_client_search.hpp
ms_http_client_search.cpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ DownloadOption

◆ ReportTopSpecialValues

◆ SearchStatusCode

◆ UploadResponseCode

Constructor & Destructor Documentation

◆ ms_http_client_search() [1/2]

◆ ~ms_http_client_search()

◆ ms_http_client_search() [2/2]

Member Function Documentation

◆ appendErrors()

◆ clearAllErrors()

◆ copyFrom() [1/2]

◆ copyFrom() [2/2]

◆ downloadDaemonResultsFile()

◆ downloadPercolatorFile()

◆ downloadResultsFile()

◆ downloadResultsFileMSR()

◆ downloadXmlResultsFile()

◆ getErrorHandler()

◆ getLastError()

◆ getLastErrorString()

◆ getResultsFileName()

◆ getSearchTaskID()

◆ getSessionID()

◆ getStage()

◆ getStatus()

◆ isValid()

◆ operator=()

◆ sessionId()

◆ uploadDistillerXmlResultsFile()