xapian-core/include/xapian/dbfactory.h

   1 /** @file
   2  * @brief Factory functions for constructing Database and WritableDatabase objects
   3  */
   4 /* Copyright (C) 2005,2006,2007,2008,2009,2011,2013,2014,2016,2024 Olly Betts
   5  *
   6  * This program is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU General Public License as
   8  * published by the Free Software Foundation; either version 2 of the
   9  * License, or (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
  19  * USA
  20  */
  21
  22 #ifndef XAPIAN_INCLUDED_DBFACTORY_H
  23 #define XAPIAN_INCLUDED_DBFACTORY_H
  24
  25 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
  26 # error Never use <xapian/dbfactory.h> directly; include <xapian.h> instead.
  27 #endif
  28
  29 #include <string>
  30 #include <string_view>
  31
  32 #include <xapian/constants.h>
  33 #include <xapian/database.h>
  34 #include <xapian/deprecated.h>
  35 #include <xapian/types.h>
  36 #include <xapian/version.h>
  37 #include <xapian/visibility.h>
  38
  39 namespace Xapian {
  40
  41 #ifdef XAPIAN_HAS_REMOTE_BACKEND
  42 /// Database factory functions for the remote backend.
  43 namespace Remote {
  44
  45 /** Construct a Database object for read-only access to a remote database
  46  *  accessed via a TCP connection.
  47  *
  48  * Access to the remote database is via a TCP connection to the specified
  49  * host and port.
  50  *
  51  * @param host          hostname to connect to.
  52  * @param port          port number to connect to.
  53  * @param timeout       timeout in milliseconds.  If this timeout is exceeded
  54  *                      for any individual operation on the remote database
  55  *                      then Xapian::NetworkTimeoutError is thrown.  A timeout
  56  *                      of 0 means don't timeout.  (Default is 10000ms, which
  57  *                      is 10 seconds).
  58  * @param connect_timeout       timeout to use when connecting to the server.
  59  *                              If this timeout is exceeded then
  60  *                              Xapian::NetworkTimeoutError is thrown.  A
  61  *                              timeout of 0 means don't timeout.  (Default is
  62  *                              10000ms, which is 10 seconds).
  63  */
  64 XAPIAN_VISIBILITY_DEFAULT
  65 Database open(std::string_view host,
  66               unsigned int port,
  67               unsigned timeout = 10000,
  68               unsigned connect_timeout = 10000);
  69
  70 /** Construct a WritableDatabase object for update access to a remote database
  71  *  accessed via a TCP connection.
  72  *
  73  * Access to the remote database is via a TCP connection to the specified
  74  * host and port.
  75  *
  76  * @param host          hostname to connect to.
  77  * @param port          port number to connect to.
  78  * @param timeout       timeout in milliseconds.  If this timeout is exceeded
  79  *                      for any individual operation on the remote database
  80  *                      then Xapian::NetworkTimeoutError is thrown.  (Default
  81  *                      is 0, which means don't timeout).
  82  * @param connect_timeout       timeout to use when connecting to the server.
  83  *                              If this timeout is exceeded then
  84  *                              Xapian::NetworkTimeoutError is thrown.  A
  85  *                              timeout of 0 means don't timeout.  (Default is
  86  *                              10000ms, which is 10 seconds).
  87  * @param flags         Xapian::DB_RETRY_LOCK or 0.
  88  */
  89 XAPIAN_VISIBILITY_DEFAULT
  90 WritableDatabase open_writable(std::string_view host,
  91                                unsigned int port,
  92                                unsigned timeout = 0,
  93                                unsigned connect_timeout = 10000,
  94                                int flags = 0);
  95
  96 /** Construct a Database object for read-only access to a remote database
  97  *  accessed via a program.
  98  *
  99  * Access to the remote database is done by running an external program and
 100  * communicating with it on stdin/stdout.
 101  *
 102  * @param program       the external program to run.
 103  * @param args          space-separated list of arguments to pass to program.
 104  * @param timeout       timeout in milliseconds.  If this timeout is exceeded
 105  *                      for any individual operation on the remote database
 106  *                      then Xapian::NetworkTimeoutError is thrown.  A timeout
 107  *                      of 0 means don't timeout.  (Default is 10000ms, which
 108  *                      is 10 seconds).
 109  */
 110 XAPIAN_VISIBILITY_DEFAULT
 111 Database open(std::string_view program,
 112               std::string_view args,
 113               unsigned timeout = 10000);
 114
 115 /** Construct a WritableDatabase object for update access to a remote database
 116  *  accessed via a program.
 117  *
 118  * Access to the remote database is done by running an external program and
 119  * communicating with it on stdin/stdout.
 120  *
 121  * @param program       the external program to run.
 122  * @param args          space-separated list of arguments to pass to program.
 123  * @param timeout       timeout in milliseconds.  If this timeout is exceeded
 124  *                      for any individual operation on the remote database
 125  *                      then Xapian::NetworkTimeoutError is thrown.  (Default
 126  *                      is 0, which means don't timeout).
 127  * @param flags         Xapian::DB_RETRY_LOCK or 0.
 128  */
 129 XAPIAN_VISIBILITY_DEFAULT
 130 WritableDatabase open_writable(std::string_view program,
 131                                std::string_view args,
 132                                unsigned timeout = 0,
 133                                int flags = 0);
 134
 135 }
 136 #endif
 137
 138 }
 139
 140 #endif /* XAPIAN_INCLUDED_DBFACTORY_H */