NCBI C++ ToolKit
eutils_client.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef MISC_EUTILS_CLIENT___EUTILS_CLIENT__HPP
2 #define MISC_EUTILS_CLIENT___EUTILS_CLIENT__HPP
3 
4 /* $Id: eutils_client.hpp 96737 2022-05-04 17:17:06Z kans $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors: Mike DiCuccio
30  *
31  * File Description:
32  *
33  */
34 
35 #include <corelib/ncbistd.hpp>
36 #include <corelib/ncbiobj.hpp>
37 #include <corelib/ncbimisc.hpp>
39 #include <sstream>
41 
43 
44 
45 /////////////////////////////////////////////////////////////////////////////
46 
47 namespace edirect {
48 
49  // Provides simplified access to Entrez Direct scripts
50 
51  string Execute (
52  const string& cmmd,
53  const vector<string>& args,
54  const string& data = kEmptyStr
55  );
56 }
57 
58 
60 {
61 public:
62  enum EErrCode {
68  };
69  virtual const char* GetErrCodeString(void) const override;
71 };
72 
73 /// Class for querying via E-Utils.
75 {
76 public:
77  /// Subclass this to override how messages (warnings and errors)
78  /// are handled.
79  ///
80  /// For example, use this to stop on some kinds of errors.
81  ///
82  /// @see CAgpConverter::CErrorHandler for the inspiration for
83  /// the inspiration behind this class.
84  class CMessageHandler : public CObject
85  {
86  public:
87  virtual ~CMessageHandler() { }
88 
89  /// Pure virtual function, to be implemented by subclass.
90  virtual void HandleMessage(EDiagSev severity,
92  const string & message) const = 0;
93  };
94 
95  enum EUseHistory {
98  };
99 
101  eContentType_default = 1, // maps to "xml"
106  };
107 
108  CEutilsClient();
109  CEutilsClient(const string& host);
110 
111  /// Default is to log all messages at informational level.
112  /// Equivalent to: LOG_POST(Info << ...).
113  void SetMessageHandlerDefault(void);
114 
115  /// Equivalent to: ERR_POST(Warning|Error << ...).
116  void SetMessageHandlerDiagPost(void);
117 
118  /// Equivalent to: NCBI_THROW, ERR_POST, LOG_POST as appropriate.
120 
121  /// Set custom message handler.
122  void SetMessageHandler(CMessageHandler& message_handler);
123 
124  void SetUserTag(const string& tag);
125  void SetMaxReturn(int ret_max);
126  void SetLinkName(const string& link_name);
127 
128  void ClearAddedParameters();
129  void AddParameter(const string &name, const string &value);
130 
131  Uint8 Count(const string& db,
132  const string& term);
133 
134  //return the total count
135 #ifdef NCBI_INT8_GI
137  Uint8 Search(const string& db,
138  const string& term,
139  vector<int>& uids,
140  const string& xml_path = kEmptyStr);
141 #endif
142 
143  Uint8 Search(const string& db,
144  const string& term,
145  vector<objects::CSeq_id_Handle>& uids,
146  const string& xml_path = kEmptyStr);
147 
148  Uint8 Search(const string& db,
149  const string& term,
150  vector<string>& uids,
151  const string& xml_path = kEmptyStr);
152 
153  Uint8 Search(const string& db,
154  const string& term,
155  vector<TEntrezId>& uids,
156  const string& xml_path = kEmptyStr);
157 
158  void Search(const string& db,
159  const string& term,
160  CNcbiOstream& ostr,
161  EUseHistory use_history=eUseHistoryDisabled);
162 
163  void SearchHistory(const string& db,
164  const string& term,
165  const string& web_env,
166  Int8 query_key,
167  int retstart,
168  CNcbiOstream& ostr);
169 
170  void SearchHistory(const string& db,
171  const string& term,
172  const string& web_env,
173  objects::CSeq_id_Handle query_key,
174  int retstart,
175  CNcbiOstream& ostr);
176 
177  void SearchHistory(const string& db,
178  const string& term,
179  const string& web_env,
180  const string& query_key,
181  int retstart,
182  CNcbiOstream& ostr);
183 
184 #ifdef NCBI_INT8_GI
186  void Link(const string& db_from,
187  const string& db_to,
188  const vector<int>& uids_from,
189  vector<int>& uids_to,
190  const string& xml_path = kEmptyStr,
191  const string& command = "neighbor");
192 #endif
193 
194  void Link(const string& db_from,
195  const string& db_to,
196  const vector<objects::CSeq_id_Handle>& uids_from,
197  vector<objects::CSeq_id_Handle>& uids_to,
198  const string& xml_path = kEmptyStr,
199  const string& command = "neighbor");
200 
201  void Link(const string& db_from,
202  const string& db_to,
203  const vector<string>& uids_from,
204  vector<string>& uids_to,
205  const string& xml_path = kEmptyStr,
206  const string& command = "neighbor");
207 
208  void Link(const string& db_from,
209  const string& db_to,
210  const vector<TEntrezId>& uids_from,
211  vector<TEntrezId>& uids_to,
212  const string& xml_path = kEmptyStr,
213  const string& command = "neighbor");
214 
215 #ifdef NCBI_INT8_GI
217  void Link(const string& db_from,
218  const string& db_to,
219  const vector<int>& uids_from,
220  vector<TEntrezId>& uids_to,
221  const string& xml_path = kEmptyStr,
222  const string& command = "neighbor");
223 
225  void Link(const string& db_from,
226  const string& db_to,
227  const vector<TEntrezId>& uids_from,
228  vector<int>& uids_to,
229  const string& xml_path = kEmptyStr,
230  const string& command = "neighbor");
231 #endif
232 
233  void Link(const string& db_from,
234  const string& db_to,
235  const vector<TEntrezId>& uids_from,
236  vector<objects::CSeq_id_Handle>& uids_to,
237  const string& xml_path = kEmptyStr,
238  const string& command ="neighbor");
239 
240  void Link(const string& db_from,
241  const string& db_to,
242  const vector<objects::CSeq_id_Handle>& uids_from,
243  vector<TEntrezId>& uids_to,
244  const string& xml_path = kEmptyStr,
245  const string& command = "neighbor");
246 
247 #ifdef NCBI_INT8_GI
249  void Link(const string& db_from,
250  const string& db_to,
251  const vector<int>& uids_from,
252  CNcbiOstream& ostr,
253  const string& command = "neighbor");
254 #endif
255 
256  void Link(const string& db_from,
257  const string& db_to,
258  const vector<objects::CSeq_id_Handle>& uids_from,
259  CNcbiOstream& ostr,
260  const string& command = "neighbor");
261 
262  void Link(const string& db_from,
263  const string& db_to,
264  const vector<string>& uids_from,
265  CNcbiOstream& ostr,
266  const string& command = "neighbor");
267 
268  void Link(const string& db_from,
269  const string& db_to,
270  const vector<TEntrezId>& uids_from,
271  CNcbiOstream& ostr,
272  const string& command = "neighbor");
273 
274  void LinkHistory(const string& db_from,
275  const string& db_to,
276  const string& web_env,
277  Int8 query_key,
278  CNcbiOstream& ostr);
279 
280  void LinkHistory(const string& db_from,
281  const string& db_to,
282  const string& web_env,
283  objects::CSeq_id_Handle query_key,
284  CNcbiOstream& ostr);
285 
286  void LinkHistory(const string& db_from,
287  const string& db_to,
288  const string& web_env,
289  const string& query_key,
290  CNcbiOstream& ostr);
291 
292 #ifdef NCBI_INT8_GI
294  void LinkOut(const string& db,
295  const vector<int>& uids,
296  xml::document& docsums,
297  const string& cmd = "llinks");
298 #endif
299 
300  void LinkOut(const string& db,
301  const vector<objects::CSeq_id_Handle>& uids,
302  xml::document& docsums,
303  const string& cmd = "llinks");
304 
305  void LinkOut(const string& db,
306  const vector<string>& uids,
307  xml::document& docsums,
308  const string& cmd = "llinks");
309 
310  void LinkOut(const string& db,
311  const vector<TEntrezId>& uids,
312  xml::document& docsums,
313  const string& cmd = "llinks");
314 
315 #ifdef NCBI_INT8_GI
317  void Summary(const string& db,
318  const vector<int>& uids,
319  xml::document& docsums,
320  const string& version = "");
321 #endif
322 
323  void Summary(const string& db,
324  const vector<objects::CSeq_id_Handle>& uids,
325  xml::document& docsums,
326  const string& version = "");
327 
328  void Summary(const string& db,
329  const vector<string>& uids,
330  xml::document& docsums,
331  const string& version = "");
332 
333  void Summary(const string& db,
334  const vector<TEntrezId>& uids,
335  xml::document& docsums,
336  const string& version = "");
337 
338  void SummaryHistory(const string& db,
339  const string& web_env,
340  Int8 query_key,
341  int retstart, // Position within the result set
342  const string& version,// Version: "" or "2.0"
343  CNcbiOstream& ostr);
344 
345  void SummaryHistory(const string& db,
346  const string& web_env,
347  objects::CSeq_id_Handle query_key,
348  int retstart, // Position within the result set
349  const string& version,// Version: "" or "2.0"
350  CNcbiOstream& ostr);
351 
352  void SummaryHistory(const string& db,
353  const string& web_env,
354  const string& query_key,
355  int retstart, // Position within the result set
356  const string& version,// Version: "" or "2.0"
357  CNcbiOstream& ostr);
358 
359 #ifdef NCBI_INT8_GI
361  void Fetch(const string& db,
362  const vector<int>& uids,
363  CNcbiOstream& ostr,
364  const string& retmode="xml");
365 #endif
366 
367  void Fetch(const string& db,
368  const vector<objects::CSeq_id_Handle>& uids,
369  CNcbiOstream& ostr,
370  const string& retmode="xml");
371 
372  void Fetch(const string& db,
373  const vector<string>& uids,
374  CNcbiOstream& ostr,
375  const string& retmode="xml");
376 
377  void Fetch(const string& db,
378  const vector<TEntrezId>& uids,
379  CNcbiOstream& ostr,
380  const string& retmode="xml");
381 
382  void FetchHistory(const string& db,
383  const string& web_env,
384  Int8 query_key,
385  int retstart,
386  EContentType content_type,
387  CNcbiOstream& ostr);
388 
389  void FetchHistory(const string& db,
390  const string& web_env,
391  objects::CSeq_id_Handle query_key,
392  int retstart,
393  EContentType content_type,
394  CNcbiOstream& ostr);
395 
396  void FetchHistory(const string& db,
397  const string& web_env,
398  const string& query_key,
399  int retstart,
400  EContentType content_type,
401  CNcbiOstream& ostr);
402 
403 
404  const list<string> GetUrl(void) const;
405  const list<CTime> GetTime(void) const;
406 
407 protected:
408 #ifdef NCBI_INT8_GI
410  vector<int>& uids);
411 #endif
412 
414  vector<objects::CSeq_id_Handle>& uids);
415 
417  vector<string>& uids);
418 
420  vector<TEntrezId>& uids);
421 
422 #ifdef NCBI_INT8_GI
423  Uint8 ParseSearchResults(const string& xml_file,
424  vector<int>& uids);
425 #endif
426 
427  Uint8 ParseSearchResults(const string& xml_file,
428  vector<objects::CSeq_id_Handle>& uids);
429 
430  Uint8 ParseSearchResults(const string& xml_file,
431  vector<string>& uids);
432 
433  Uint8 ParseSearchResults(const string& xml_file,
434  vector<TEntrezId>& uids);
435 
437 
440  mutable string m_CachedHostName;
441  string m_HostName;
442  string m_UrlTag;
444  int m_RetMax;
445  string m_LinkName;
446 
447  //exact url of last request
448  //list holds multiple entries if multiple tries needed
449  list<string> m_Url;
450 
451  //time of last request
452  //list holds multiple entries if multiple tried needed
453  list<CTime> m_Time;
454 
455  // Execute HTTP GET request.
456  // Store received content into the @ostr.
457 
458  const string& x_GetHostName(void) const;
459  void x_Get(string const& path, string const& params, CNcbiOstream& ostr);
460 
461  static string x_BuildUrl(const string& host, const string &path,
462  const string &params);
463  void x_AddAdditionalParameters(string &params);
464 
465  template<class T> Uint8 x_Search(const string& db,
466  const string& term,
467  vector<T>& uids,
468  const string& xml_path = kEmptyStr);
469 
470 
471  template<class T1, class T2> void x_Link(const string& db_from,
472  const string& db_to,
473  const vector<T1>& uids_from,
474  vector<T2>& uids_to,
475  const string& xml_path,
476  const string& command);
477 
478  template<class T> void x_Link(const string& db_from,
479  const string& db_to,
480  const vector<T>& uids_from,
481  CNcbiOstream& ostr,
482  const string& command);
483 
484  template<class T> void x_LinkOut(const string& db,
485  const vector<T>& uids,
486  xml::document& doc,
487  const string& cmd);
488 
489  template<class T> void x_Summary(const string& db,
490  const vector<T>& uids,
491  xml::document& docsums,
492  const string& version="");
493 
494 
495  template<class T> void x_Fetch(const string& db,
496  const vector<T>& uids,
497  CNcbiOstream& ostr,
498  const string& retmode="xml");
499 
500  template<class T> Uint8 x_ParseSearchResults(const string& xml_file,
501  vector<T>& uids);
502 
503  template<class T> Uint8 x_ParseSearchResults(CNcbiIstream& istr,
504  vector<T>& uids);
505 };
506 
507 
509 
510 
511 #endif // MISC_EUTILS_CLIENT___EUTILS_CLIENT__HPP
virtual const char * GetErrCodeString(void) const override
Get error code interpreted as text.
NCBI_EXCEPTION_DEFAULT(CEUtilsException, CException)
Subclass this to override how messages (warnings and errors) are handled.
virtual void HandleMessage(EDiagSev severity, CEUtilsException::EErrCode err_code, const string &message) const =0
Pure virtual function, to be implemented by subclass.
Class for querying via E-Utils.
void Link(const string &db_from, const string &db_to, const vector< TEntrezId > &uids_from, vector< objects::CSeq_id_Handle > &uids_to, const string &xml_path=kEmptyStr, const string &command="neighbor")
void SearchHistory(const string &db, const string &term, const string &web_env, objects::CSeq_id_Handle query_key, int retstart, CNcbiOstream &ostr)
const list< CTime > GetTime(void) const
list< CTime > m_Time
void LinkOut(const string &db, const vector< objects::CSeq_id_Handle > &uids, xml::document &docsums, const string &cmd="llinks")
void Fetch(const string &db, const vector< objects::CSeq_id_Handle > &uids, CNcbiOstream &ostr, const string &retmode="xml")
void SetMaxReturn(int ret_max)
CRef< CMessageHandler > m_MessageHandler
void SearchHistory(const string &db, const string &term, const string &web_env, Int8 query_key, int retstart, CNcbiOstream &ostr)
string m_CachedHostName
Uint8 Search(const string &db, const string &term, vector< objects::CSeq_id_Handle > &uids, const string &xml_path=kEmptyStr)
TParamList m_AdditionalParams
const list< string > GetUrl(void) const
static string x_BuildUrl(const string &host, const string &path, const string &params)
void x_AddAdditionalParameters(string &params)
void x_Fetch(const string &db, const vector< T > &uids, CNcbiOstream &ostr, const string &retmode="xml")
void x_Summary(const string &db, const vector< T > &uids, xml::document &docsums, const string &version="")
void FetchHistory(const string &db, const string &web_env, objects::CSeq_id_Handle query_key, int retstart, EContentType content_type, CNcbiOstream &ostr)
void AddParameter(const string &name, const string &value)
void Summary(const string &db, const vector< objects::CSeq_id_Handle > &uids, xml::document &docsums, const string &version="")
void Link(const string &db_from, const string &db_to, const vector< objects::CSeq_id_Handle > &uids_from, vector< TEntrezId > &uids_to, const string &xml_path=kEmptyStr, const string &command="neighbor")
void SetLinkName(const string &link_name)
void ClearAddedParameters()
void x_Link(const string &db_from, const string &db_to, const vector< T1 > &uids_from, vector< T2 > &uids_to, const string &xml_path, const string &command)
void LinkHistory(const string &db_from, const string &db_to, const string &web_env, objects::CSeq_id_Handle query_key, CNcbiOstream &ostr)
Uint8 x_Search(const string &db, const string &term, vector< T > &uids, const string &xml_path=kEmptyStr)
void SetMessageHandlerDiagPost(void)
Equivalent to: ERR_POST(Warning|Error << ...).
void x_Get(string const &path, string const &params, CNcbiOstream &ostr)
Uint8 x_ParseSearchResults(const string &xml_file, vector< T > &uids)
map< string, string > TParamList
void SetMessageHandlerThrowOnError(void)
Equivalent to: NCBI_THROW, ERR_POST, LOG_POST as appropriate.
void Link(const string &db_from, const string &db_to, const vector< objects::CSeq_id_Handle > &uids_from, vector< objects::CSeq_id_Handle > &uids_to, const string &xml_path=kEmptyStr, const string &command="neighbor")
const string & x_GetHostName(void) const
void SetMessageHandler(CMessageHandler &message_handler)
Set custom message handler.
void SetMessageHandlerDefault(void)
Default is to log all messages at informational level.
void SetUserTag(const string &tag)
Uint8 ParseSearchResults(CNcbiIstream &istr, vector< objects::CSeq_id_Handle > &uids)
void FetchHistory(const string &db, const string &web_env, Int8 query_key, int retstart, EContentType content_type, CNcbiOstream &ostr)
void LinkHistory(const string &db_from, const string &db_to, const string &web_env, Int8 query_key, CNcbiOstream &ostr)
Uint8 ParseSearchResults(const string &xml_file, vector< objects::CSeq_id_Handle > &uids)
Uint8 Count(const string &db, const string &term)
void Link(const string &db_from, const string &db_to, const vector< objects::CSeq_id_Handle > &uids_from, CNcbiOstream &ostr, const string &command="neighbor")
list< string > m_Url
void SummaryHistory(const string &db, const string &web_env, Int8 query_key, int retstart, const string &version, CNcbiOstream &ostr)
void SummaryHistory(const string &db, const string &web_env, objects::CSeq_id_Handle query_key, int retstart, const string &version, CNcbiOstream &ostr)
void x_LinkOut(const string &db, const vector< T > &uids, xml::document &doc, const string &cmd)
CObject –.
Definition: ncbiobj.hpp:180
CRef –.
Definition: ncbiobj.hpp:618
The xml::document class is used to hold the XML tree and various bits of information about it.
Definition: document.hpp:80
char value[7]
Definition: config.c:431
Include a standard set of the NCBI C++ Toolkit most basic headers.
static CS_COMMAND * cmd
Definition: ct_dynamic.c:26
EDiagSev
Severity level for the posted diagnostics.
Definition: ncbidiag.hpp:650
EErrCode
Error types that an application can generate.
Definition: ncbiexpt.hpp:884
#define NCBI_DEPRECATED
int64_t Int8
8-byte (64-bit) signed integer
Definition: ncbitype.h:104
uint64_t Uint8
8-byte (64-bit) unsigned integer
Definition: ncbitype.h:105
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
IO_PREFIX::ostream CNcbiOstream
Portable alias for ostream.
Definition: ncbistre.hpp:149
IO_PREFIX::istream CNcbiIstream
Portable alias for istream.
Definition: ncbistre.hpp:146
#define kEmptyStr
Definition: ncbistr.hpp:123
static int version
Definition: mdb_load.c:29
string Execute(const string &cmmd, const vector< string > &args, const string &data=kEmptyStr)
const char * tag
Miscellaneous common-use basic types and functionality.
Portable reference counted smart and weak pointers using CWeakRef, CRef, CObject and CObjectEx.
const char * command
Modified on Wed Feb 21 09:55:25 2024 by modify_doxy.py rev. 669887