Matrix Science header
Public Types | Public Member Functions

ms_http_client_search Class Reference
[Accessing a Mascot Server using HTTP]

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

#include <ms_http_client_search.hpp>

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

List of all members.

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 (ms_http_client_session &session, const std::string &searchTaskId)
 Access previously run search results.
 ms_http_client_search (const ms_http_client_search &src)
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 inpput 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 file (F*.dat).
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_errsgetErrorHandler () 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 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_searchoperator= (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.

Use ms_http_client_search to follow the progress of a new search as it runs on the Macot 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

Definitions for downloading results.

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

Enumerator:
DO_NORMAL 

Downloads a compressed results file with the peak list sections 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.

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

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

See Using enumerated values 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 .

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)

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

See Using enumerated values 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 ( 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:
sessionThe associated session object.
searchTaskIdThe Mascot task identifier used for the associated search.
~ms_http_client_search (  ) [virtual]

Destructor;.

Called automatically.

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.
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.
void copyFrom ( const ms_http_client_search right )

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

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
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:
filenameThe name of the local file for the results to be written to.
progressThe 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.
bool downloadPercolatorFile ( std::string  filename,
ms_http_helper_progress progress 
)

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

Parameters:
filenameThe name of the local file for the results to be written to.
progressThe 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.
bool downloadResultsFile ( std::string  filename,
ms_http_helper_progress progress,
DownloadOption  options = DO_WITH_IONS 
)

Download the results file (F*.dat).

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

Parameters:
filenameThe name of the local file for the results to be written to.
progressThe 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.
optionsThis contains the bit flags that controls how the file will be downloaded. It should be DO_NORMAL or a bitwise accumulation (boolean or operation) of the other flags.
Returns:
Returns true if the function completed successfully.
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:
filenameThe name of the local file for the results to be written to.
progressThe 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.
reportTopThe number of protein hits to include in the results.
Returns:
Returns true if the function completed successfully.
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.
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 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]returnFileNameReturns the path to the result file on the server (usually relative to the cgi directory).
Returns:
Returns true if the function completed successfully.
std::string getSearchTaskID (  ) const

Get the task ID of the associated Mascot search.

Returns:
The Mascot task identifier used for the associated search.
std::string getSessionID (  ) const

Get the associated session ID.

Returns:
The associated Mascot Server session ID.
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]returnCodeReturns the current status code of the search task.
[out]statusValueReturns an optional value depending on the returnCode.
Returns:
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 is 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_search & operator= ( const ms_http_client_search right )
Parameters:
rightis the source to initialise from
Returns:
reference to the current object
std::string sessionId (  ) const [inline]

Get the associated session ID.

Deprecated:
Use getSessionID()
Returns:
session id
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]filenameThe path of the file to be uploaded.
[out]responseCodeIf the return value is true then this should be checked to see if the upload was accepted as valid.
[out]responseTextThe 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:
Copyright © 2016 Matrix Science Ltd.  All Rights Reserved. Generated on Fri Jun 2 2017 01:44:52