Matrix Science header
Public Types | Public Member Functions

ms_http_client_session Class Reference
[Accessing a Mascot Server using HTTP]

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:
Inheritance graph
[legend]
Collaboration diagram for ms_http_client_session:
Collaboration graph
[legend]

List of all members.

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_helper connection, const std::string sessionId)
 Construct a session object that can be used to access the Mascot Server.
 ms_http_client_session (const ms_http_client_session &src)
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_http_client_session *right)
void copyFrom (const ms_errors *right)
 Use this member to make a copy of another instance.
const ms_errsgetErrorHandler () 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_sessionoperator= (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

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

Create an empty session.

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

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:
connectionThe associated ms_http_helper.
sessionIdThe Mascot Server session ID.
~ms_http_client_session (  ) [virtual]

Destructor.

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

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_session 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 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]taskTypeThe security token being queried.
[out]returnIsPermittedReturns true if the security task type is permitted on this session, false if not.
Returns:
Returns true if the function completed successfully.
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]taskIdsThe task IDs of the searches.
[out]xmlUploadedSet 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.
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 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:
databaseThe name of the database on the Mascot server fromn which the data is to be retrieved.
accessionNamesA collection of accession names for the peptides or NA sequences to be retrieved.
accessionFramesA 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.
filenameThe name of the local file to be populated with the retrieved information. S
optionsThe types of information to be included in the output file.
Returns:
Returns true if the function completed successfully.
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
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.
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.
ms_http_client_session & operator= ( const ms_http_client_session right )
Parameters:
rightis the source to initialise from
Returns:
reference to the current object
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:
returnTaskThe search object that can be used to monitor progress and then retrieve results. See Maintaining object references: two rules of thumb.
httpHeaderThe HTTP header line, specifying the content type and the MIME separator string. For example: "Content-Type: multipart/mixed; boundary=---------FormBoundary4C9ByKKVofH"
prologueText 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
filenameThe 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.
epilogueText sent as the last part of the content of the HTTP POST. For example, "-----------FormBoundary4C9ByKKVofH--"
progressThe 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.
batchIf 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:

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