mysql_lease_mgr.h 27.9 KB
 Stephen Morris committed Oct 16, 2012 1 2 3 4 5 6 7 8 9 10 11 12 13 14 // Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC") // // Permission to use, copy, modify, and/or distribute this software for any // purpose with or without fee is hereby granted, provided that the above // copyright notice and this permission notice appear in all copies. // // THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH // REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY // AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, // INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM // LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR // PERFORMANCE OF THIS SOFTWARE.  Stephen Morris committed Oct 29, 2012 15 16 #ifndef MYSQL_LEASE_MGR_H #define MYSQL_LEASE_MGR_H  Stephen Morris committed Oct 16, 2012 17   Tomek Mrugalski committed Jan 10, 2013 18 #include  Stephen Morris committed Nov 16, 2012 19 20 #include  Stephen Morris committed Nov 06, 2012 21 #include  Stephen Morris committed Mar 07, 2013 22 #include  Stephen Morris committed Nov 16, 2012 23 #include  Stephen Morris committed Nov 16, 2012 24 25  #include  Stephen Morris committed Oct 16, 2012 26 27 28 29  namespace isc { namespace dhcp {  Stephen Morris committed Mar 07, 2013 30 31 /// @brief MySQL Handle Holder ///  Jelte Jansen committed Mar 07, 2013 32 /// Small RAII object for safer initialization, will close the database  Stephen Morris committed Mar 07, 2013 33 34 35 36 37 38 39 40 41 /// connection upon destruction. This means that if an exception is thrown /// during database initialization, resources allocated to the database are /// guaranteed to be freed. /// /// It makes no sense to copy an object of this class. After the copy, both /// objects would contain pointers to the same MySql context object. The /// destruction of one would invalid the context in the remaining object. /// For this reason, the class is declared noncopyable. class MySqlHolder : public boost::noncopyable {  Jelte Jansen committed Mar 07, 2013 42 public:  Stephen Morris committed Mar 07, 2013 43 44 45 46 47 48  /// @brief Constructor /// /// Initialize MySql and store the associated context object. /// /// @throw DbOpenError Unable to initialize MySql handle.  Jelte Jansen committed Mar 07, 2013 49 50 51 52 53 54  MySqlHolder() : mysql_(mysql_init(NULL)) { if (mysql_ == NULL) { isc_throw(DbOpenError, "unable to initialize MySQL"); } }  Stephen Morris committed Mar 07, 2013 55 56 57  /// @brief Destructor /// /// Frees up resources allocated by the initialization of MySql.  Jelte Jansen committed Mar 07, 2013 58  ~MySqlHolder() {  Stephen Morris committed Mar 07, 2013 59  if (mysql_ != NULL) {  Jelte Jansen committed Mar 07, 2013 60 61 62 63  mysql_close(mysql_); } }  Stephen Morris committed Mar 07, 2013 64 65 66 67  /// @brief Conversion Operator /// /// Allows the MySqlHolder object to be passed as the context argument to /// mysql_xxx functions.  Jelte Jansen committed Mar 07, 2013 68 69 70 71 72  operator MYSQL*() const { return (mysql_); } private:  Stephen Morris committed Mar 07, 2013 73  MYSQL* mysql_; ///< Initialization context  Jelte Jansen committed Mar 07, 2013 74 75 };  Stephen Morris committed Oct 24, 2012 76 77 // Define the current database schema values  Stephen Morris committed Nov 30, 2012 78 79 const uint32_t CURRENT_VERSION_VERSION = 1; const uint32_t CURRENT_VERSION_MINOR = 0;  Stephen Morris committed Oct 24, 2012 80   Stephen Morris committed Nov 06, 2012 81   Stephen Morris committed Dec 03, 2012 82 // Forward declaration of the Lease exchange objects. These classes are defined  Stephen Morris committed Nov 06, 2012 83 // in the .cc file.  Stephen Morris committed Nov 21, 2012 84 class MySqlLease4Exchange;  Stephen Morris committed Nov 06, 2012 85 86 87 class MySqlLease6Exchange;  Stephen Morris committed Oct 24, 2012 88 /// @brief MySQL Lease Manager  Stephen Morris committed Oct 16, 2012 89 ///  Stephen Morris committed Nov 26, 2012 90 91 92 93 /// This class provides the \ref isc::dhcp::LeaseMgr interface to the MySQL /// database. Use of this backend presupposes that a MySQL database is /// available and that the Kea schema has been created within it.  Stephen Morris committed Oct 16, 2012 94 95 96 97 98 99 class MySqlLeaseMgr : public LeaseMgr { public: /// @brief Constructor /// /// Uses the following keywords in the parameters passed to it to /// connect to the database:  Stephen Morris committed Oct 24, 2012 100 101 102 103  /// - name - Name of the database to which to connect (mandatory) /// - host - Host to which to connect (optional, defaults to "localhost") /// - user - Username under which to connect (optional) /// - password - Password for "user" on the database (optional)  Stephen Morris committed Oct 16, 2012 104 105 106 107 108 109 110 111 112  /// /// If the database is successfully opened, the version number in the /// schema_version table will be checked against hard-coded value in /// the implementation file. /// /// Finally, all the SQL commands are pre-compiled. /// /// @param parameters A data structure relating keywords and values /// concerned with the database.  Stephen Morris committed Oct 24, 2012 113  ///  Stephen Morris committed Nov 08, 2012 114 115 116 117  /// @throw isc::dhcp::NoDatabaseName Mandatory database name not given /// @throw isc::dhcp::DbOpenError Error opening the database /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 16, 2012 118 119 120 121 122  MySqlLeaseMgr(const ParameterMap& parameters); /// @brief Destructor (closes database) virtual ~MySqlLeaseMgr();  Stephen Morris committed Nov 23, 2012 123  /// @brief Adds an IPv4 lease  Stephen Morris committed Oct 16, 2012 124 125  /// /// @param lease lease to be added  Stephen Morris committed Oct 20, 2012 126 127 128 129  /// /// @result true if the lease was added, false if not (because a lease /// with the same address was already there). ///  Stephen Morris committed Nov 08, 2012 130 131  /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 20, 2012 132  virtual bool addLease(const Lease4Ptr& lease);  Stephen Morris committed Oct 16, 2012 133   Stephen Morris committed Nov 23, 2012 134  /// @brief Adds an IPv6 lease  Stephen Morris committed Oct 16, 2012 135 136  /// /// @param lease lease to be added  Stephen Morris committed Oct 20, 2012 137 138 139 140  /// /// @result true if the lease was added, false if not (because a lease /// with the same address was already there). ///  Stephen Morris committed Nov 08, 2012 141 142  /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 20, 2012 143  virtual bool addLease(const Lease6Ptr& lease);  Stephen Morris committed Oct 16, 2012 144 145 146 147  /// @brief Returns an IPv4 lease for specified IPv4 address /// /// This method return a lease that is associated with a given address.  Stephen Morris committed Dec 07, 2012 148  /// For other query types (by hardware addr, by Client ID) there can be  Stephen Morris committed Oct 16, 2012 149 150 151 152 153 154 155 156  /// several leases in different subnets (e.g. for mobile clients that /// got address in different subnets). However, for a single address /// there can be only one lease, so this method returns a pointer to /// a single lease, not a container of leases. /// /// @param addr address of the searched lease /// /// @return smart pointer to the lease (or NULL if a lease is not found)  Stephen Morris committed Nov 30, 2012 157 158 159 160 161 162  /// /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to /// fit into the space allocated for the result. This indicates a /// programming error. /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 20, 2012 163  virtual Lease4Ptr getLease4(const isc::asiolink::IOAddress& addr) const;  Stephen Morris committed Oct 16, 2012 164   Stephen Morris committed Oct 22, 2012 165   Stephen Morris committed Oct 16, 2012 166 167 168 169 170 171 172 173 174 175  /// @brief Returns existing IPv4 leases for specified hardware address. /// /// Although in the usual case there will be only one lease, for mobile /// clients or clients with multiple static/fixed/reserved leases there /// can be more than one. Thus return type is a container, not a single /// pointer. /// /// @param hwaddr hardware address of the client /// /// @return lease collection  Stephen Morris committed Nov 30, 2012 176 177 178 179 180 181  /// /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to /// fit into the space allocated for the result. This indicates a /// programming error. /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Tomek Mrugalski committed Jan 10, 2013 182  virtual Lease4Collection getLease4(const isc::dhcp::HWAddr& hwaddr) const;  Stephen Morris committed Oct 16, 2012 183 184 185 186 187 188 189 190 191 192 193  /// @brief Returns existing IPv4 leases for specified hardware address /// and a subnet /// /// There can be at most one lease for a given HW address in a single /// pool, so this method with either return a single lease or NULL. /// /// @param hwaddr hardware address of the client /// @param subnet_id identifier of the subnet that lease must belong to /// /// @return a pointer to the lease (or NULL if a lease is not found)  Stephen Morris committed Nov 30, 2012 194 195 196 197 198 199  /// /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to /// fit into the space allocated for the result. This indicates a /// programming error. /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Tomek Mrugalski committed Jan 10, 2013 200  virtual Lease4Ptr getLease4(const isc::dhcp::HWAddr& hwaddr,  Stephen Morris committed Oct 17, 2012 201  SubnetID subnet_id) const;  Stephen Morris committed Oct 16, 2012 202 203 204 205 206 207 208 209 210 211 212  /// @brief Returns existing IPv4 lease for specified client-id /// /// Although in the usual case there will be only one lease, for mobile /// clients or clients with multiple static/fixed/reserved leases there /// can be more than one. Thus return type is a container, not a single /// pointer. /// /// @param clientid client identifier /// /// @return lease collection  Stephen Morris committed Nov 30, 2012 213 214 215 216 217 218  /// /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to /// fit into the space allocated for the result. This indicates a /// programming error. /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 17, 2012 219  virtual Lease4Collection getLease4(const ClientId& clientid) const;  Stephen Morris committed Oct 16, 2012 220 221 222 223 224 225 226 227 228 229  /// @brief Returns existing IPv4 lease for specified client-id /// /// There can be at most one lease for a given HW address in a single /// pool, so this method with either return a single lease or NULL. /// /// @param clientid client identifier /// @param subnet_id identifier of the subnet that lease must belong to /// /// @return a pointer to the lease (or NULL if a lease is not found)  Stephen Morris committed Nov 30, 2012 230 231 232 233 234 235  /// /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to /// fit into the space allocated for the result. This indicates a /// programming error. /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 16, 2012 236  virtual Lease4Ptr getLease4(const ClientId& clientid,  Stephen Morris committed Oct 17, 2012 237  SubnetID subnet_id) const;  Stephen Morris committed Oct 16, 2012 238 239 240 241 242 243 244 245 246 247  /// @brief Returns existing IPv6 lease for a given IPv6 address. /// /// For a given address, we assume that there will be only one lease. /// The assumtion here is that there will not be site or link-local /// addresses used, so there is no way of having address duplication. /// /// @param addr address of the searched lease /// /// @return smart pointer to the lease (or NULL if a lease is not found)  Stephen Morris committed Oct 24, 2012 248  ///  Stephen Morris committed Nov 08, 2012 249 250  /// @throw isc::BadValue record retrieved from database had an invalid /// lease type field.  Stephen Morris committed Nov 30, 2012 251 252 253  /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to /// fit into the space allocated for the result. This indicates a /// programming error.  Stephen Morris committed Nov 08, 2012 254 255  /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 20, 2012 256  virtual Lease6Ptr getLease6(const isc::asiolink::IOAddress& addr) const;  Stephen Morris committed Oct 16, 2012 257 258 259 260 261 262 263 264 265 266 267 268  /// @brief Returns existing IPv6 leases for a given DUID+IA combination /// /// Although in the usual case there will be only one lease, for mobile /// clients or clients with multiple static/fixed/reserved leases there /// can be more than one. Thus return type is a container, not a single /// pointer. /// /// @param duid client DUID /// @param iaid IA identifier /// /// @return smart pointer to the lease (or NULL if a lease is not found)  Stephen Morris committed Nov 30, 2012 269 270 271 272 273 274 275 276  /// /// @throw isc::BadValue record retrieved from database had an invalid /// lease type field. /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to /// fit into the space allocated for the result. This indicates a /// programming error. /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 16, 2012 277  virtual Lease6Collection getLease6(const DUID& duid,  Stephen Morris committed Oct 17, 2012 278  uint32_t iaid) const;  Stephen Morris committed Oct 16, 2012 279 280 281 282 283 284 285 286  /// @brief Returns existing IPv6 lease for a given DUID+IA combination /// /// @param duid client DUID /// @param iaid IA identifier /// @param subnet_id subnet id of the subnet the lease belongs to /// /// @return smart pointer to the lease (or NULL if a lease is not found)  Stephen Morris committed Nov 30, 2012 287 288 289 290 291 292 293 294  /// /// @throw isc::BadValue record retrieved from database had an invalid /// lease type field. /// @throw isc::dhcp::DataTruncation Data was truncated on retrieval to /// fit into the space allocated for the result. This indicates a /// programming error. /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 16, 2012 295  virtual Lease6Ptr getLease6(const DUID& duid, uint32_t iaid,  Stephen Morris committed Oct 17, 2012 296  SubnetID subnet_id) const;  Stephen Morris committed Oct 16, 2012 297 298 299  /// @brief Updates IPv4 lease. ///  Stephen Morris committed Nov 23, 2012 300 301 302  /// Updates the record of the lease in the database (as identified by the /// address) with the data in the passed lease object. ///  Stephen Morris committed Oct 16, 2012 303 304  /// @param lease4 The lease to be updated. ///  Stephen Morris committed Nov 23, 2012 305 306 307 308  /// @throw isc::dhcp::NoSuchLease Attempt to update a lease that did not /// exist. /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 20, 2012 309  virtual void updateLease4(const Lease4Ptr& lease4);  Stephen Morris committed Oct 16, 2012 310   Stephen Morris committed Nov 08, 2012 311  /// @brief Updates IPv6 lease.  Stephen Morris committed Oct 16, 2012 312  ///  Stephen Morris committed Nov 23, 2012 313 314 315  /// Updates the record of the lease in the database (as identified by the /// address) with the data in the passed lease object. ///  Stephen Morris committed Nov 08, 2012 316  /// @param lease6 The lease to be updated.  Stephen Morris committed Oct 16, 2012 317  ///  Stephen Morris committed Nov 08, 2012 318 319 320 321  /// @throw isc::dhcp::NoSuchLease Attempt to update a lease that did not /// exist. /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 20, 2012 322  virtual void updateLease6(const Lease6Ptr& lease6);  Stephen Morris committed Oct 16, 2012 323   Stephen Morris committed Dec 10, 2012 324  /// @brief Deletes a lease.  Stephen Morris committed Oct 16, 2012 325  ///  Stephen Morris committed Dec 10, 2012 326 327  /// @param addr Address of the lease to be deleted. This can be an IPv4 /// address or an IPv6 address.  Stephen Morris committed Oct 16, 2012 328 329  /// /// @return true if deletion was successful, false if no such lease exists  Stephen Morris committed Oct 24, 2012 330  ///  Stephen Morris committed Nov 08, 2012 331 332  /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Dec 10, 2012 333  virtual bool deleteLease(const isc::asiolink::IOAddress& addr);  Stephen Morris committed Oct 16, 2012 334   Stephen Morris committed Nov 13, 2012 335 336 337 338 339 340 341 342 343  /// @brief Return backend type /// /// Returns the type of the backend (e.g. "mysql", "memfile" etc.) /// /// @return Type of the backend. virtual std::string getType() const { return (std::string("mysql")); }  Stephen Morris committed Oct 16, 2012 344 345 346  /// @brief Returns backend name. /// /// Each backend have specific name, e.g. "mysql" or "sqlite".  Stephen Morris committed Nov 13, 2012 347 348  /// /// @return Name of the backend.  Stephen Morris committed Oct 17, 2012 349  virtual std::string getName() const;  Stephen Morris committed Oct 16, 2012 350 351 352 353  /// @brief Returns description of the backend. /// /// This description may be multiline text that describes the backend.  Stephen Morris committed Nov 13, 2012 354 355  /// /// @return Description of the backend.  Stephen Morris committed Oct 17, 2012 356  virtual std::string getDescription() const;  Stephen Morris committed Oct 16, 2012 357 358 359 360 361 362  /// @brief Returns backend version. /// /// @return Version number as a pair of unsigned integers. "first" is the /// major version number, "second" the minor number. ///  Stephen Morris committed Nov 08, 2012 363 364  /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 16, 2012 365 366  virtual std::pair getVersion() const;  Stephen Morris committed Oct 20, 2012 367 368 369 370 371  /// @brief Commit Transactions /// /// Commits all pending database operations. On databases that don't /// support transactions, this is a no-op. ///  Stephen Morris committed Nov 08, 2012 372  /// @throw DbOperationError Iif the commit failed.  Stephen Morris committed Oct 20, 2012 373 374 375 376 377 378 379  virtual void commit(); /// @brief Rollback Transactions /// /// Rolls back all pending database operations. On databases that don't /// support transactions, this is a no-op. ///  Stephen Morris committed Nov 08, 2012 380  /// @throw DbOperationError If the rollback failed.  Stephen Morris committed Oct 20, 2012 381 382 383 384  virtual void rollback(); ///@{ /// The following methods are used to convert between times and time  Stephen Morris committed Oct 22, 2012 385 386 387 388 389  /// intervals stored in the Lease object, and the times stored in the /// database. The reason for the difference is because in the DHCP server, /// the cltt (Client Time Since Last Transmission) is the natural data; in /// the lease file - which may be read by the user - it is the expiry time /// of the lease.  Stephen Morris committed Oct 20, 2012 390 391 392  /// @brief Convert Lease Time to Database Times ///  Stephen Morris committed Oct 24, 2012 393 394 395 396  /// Within the DHCP servers, times are stored as client last transmit time /// and valid lifetime. In the database, the information is stored as /// valid lifetime and "expire" (time of expiry of the lease). They are /// related by the equation:  Stephen Morris committed Oct 20, 2012 397  ///  Stephen Morris committed Oct 24, 2012 398  /// - expire = client last transmit time + valid lifetime  Stephen Morris committed Oct 20, 2012 399 400 401 402 403  /// /// This method converts from the times in the lease object into times /// able to be added to the database. /// /// @param cltt Client last transmit time  Stephen Morris committed Oct 24, 2012 404  /// @param valid_lifetime Valid lifetime  Stephen Morris committed Oct 20, 2012 405 406 407  /// @param expire Reference to MYSQL_TIME object where the expiry time of /// the lease will be put. static  Stephen Morris committed Oct 24, 2012 408 409  void convertToDatabaseTime(time_t cltt, uint32_t valid_lifetime, MYSQL_TIME& expire);  Stephen Morris committed Oct 20, 2012 410 411 412  /// @brief Convert Database Time to Lease Times ///  Stephen Morris committed Oct 24, 2012 413 414 415 416  /// Within the database, time is stored as "expire" (time of expiry of the /// lease) and valid lifetime. In the DHCP server, the information is /// stored client last transmit time and valid lifetime. These are related /// by the equation:  Stephen Morris committed Oct 20, 2012 417  ///  Stephen Morris committed Oct 24, 2012 418  /// - client last transmit time = expire - valid_lifetime  Stephen Morris committed Oct 20, 2012 419 420 421 422 423 424  /// /// This method converts from the times in the database into times /// able to be inserted into the lease object. /// /// @param expire Reference to MYSQL_TIME object from where the expiry /// time of the lease is taken.  Stephen Morris committed Nov 12, 2012 425  /// @param valid_lifetime lifetime of the lease.  Stephen Morris committed Oct 20, 2012 426 427 428  /// @param cltt Reference to location where client last transmit time /// is put. static  Jelte Jansen committed Mar 07, 2013 429  void convertFromDatabaseTime(const MYSQL_TIME& expire,  Stephen Morris committed Oct 24, 2012 430  uint32_t valid_lifetime, time_t& cltt);  Stephen Morris committed Oct 20, 2012 431 432  ///@}  Stephen Morris committed Oct 22, 2012 433  /// @brief Statement Tags  Stephen Morris committed Oct 18, 2012 434  ///  Stephen Morris committed Oct 22, 2012 435  /// The contents of the enum are indexes into the list of SQL statements  Stephen Morris committed Oct 18, 2012 436  enum StatementIndex {  Stephen Morris committed Nov 21, 2012 437  DELETE_LEASE4, // Delete from lease4 by address  Stephen Morris committed Nov 03, 2012 438  DELETE_LEASE6, // Delete from lease6 by address  Stephen Morris committed Nov 21, 2012 439  GET_LEASE4_ADDR, // Get lease4 by address  Stephen Morris committed Dec 03, 2012 440 441  GET_LEASE4_CLIENTID, // Get lease4 by client ID GET_LEASE4_CLIENTID_SUBID, // Get lease4 by client ID & subnet ID  Stephen Morris committed Nov 23, 2012 442 443  GET_LEASE4_HWADDR, // Get lease4 by HW address GET_LEASE4_HWADDR_SUBID, // Get lease4 by HW address & subnet ID  Stephen Morris committed Nov 03, 2012 444 445  GET_LEASE6_ADDR, // Get lease6 by address GET_LEASE6_DUID_IAID, // Get lease6 by DUID and IAID  Stephen Morris committed Dec 03, 2012 446  GET_LEASE6_DUID_IAID_SUBID, // Get lease6 by DUID, IAID and subnet ID  Stephen Morris committed Nov 03, 2012 447  GET_VERSION, // Obtain version number  Stephen Morris committed Nov 21, 2012 448  INSERT_LEASE4, // Add entry to lease4 table  Stephen Morris committed Nov 03, 2012 449  INSERT_LEASE6, // Add entry to lease6 table  Stephen Morris committed Nov 23, 2012 450  UPDATE_LEASE4, // Update a Lease4 entry  Stephen Morris committed Nov 03, 2012 451 452  UPDATE_LEASE6, // Update a Lease6 entry NUM_STATEMENTS // Number of statements  Stephen Morris committed Oct 18, 2012 453 454  };  Stephen Morris committed Nov 04, 2012 455 private:  Stephen Morris committed Oct 18, 2012 456 457 458 459 460 461 462 463 464 465  /// @brief Prepare Single Statement /// /// Creates a prepared statement from the text given and adds it to the /// statements_ vector at the given index. /// /// @param index Index into the statements_ vector into which the text /// should be placed. The vector must be big enough for the index /// to be valid, else an exception will be thrown. /// @param text Text of the SQL statement to be prepared. ///  Stephen Morris committed Nov 08, 2012 466 467 468  /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed. /// @throw isc::InvalidParameter 'index' is not valid for the vector.  Stephen Morris committed Oct 18, 2012 469 470 471 472 473 474  void prepareStatement(StatementIndex index, const char* text); /// @brief Prepare statements /// /// Creates the prepared statements for all of the SQL statements used /// by the MySQL backend.  Stephen Morris committed Oct 24, 2012 475  ///  Stephen Morris committed Nov 08, 2012 476 477 478 479  /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed. /// @throw isc::InvalidParameter 'index' is not valid for the vector. This /// represents an internal error within the code.  Stephen Morris committed Oct 18, 2012 480 481  void prepareStatements();  Stephen Morris committed Oct 17, 2012 482 483 484 485 486  /// @brief Open Database /// /// Opens the database using the information supplied in the parameters /// passed to the constructor. ///  Stephen Morris committed Nov 08, 2012 487 488  /// @throw NoDatabaseName Mandatory database name not given /// @throw DbOpenError Error opening the database  Stephen Morris committed Oct 17, 2012 489 490  void openDatabase();  Stephen Morris committed Nov 21, 2012 491 492  /// @brief Add Lease Common Code ///  Stephen Morris committed Dec 03, 2012 493 494 495  /// This method performs the common actions for both flavours (V4 and V6) /// of the addLease method. It binds the contents of the lease object to /// the prepared statement and adds it to the database.  Stephen Morris committed Nov 21, 2012 496 497 498 499 500 501 502 503 504 505  /// /// @param stindex Index of statemnent being executed /// @param bind MYSQL_BIND array that has been created for the type /// of lease in question. /// /// @return true if the lease was added, false if it was not added because /// a lease with that address already exists in the database. /// /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Nov 26, 2012 506  bool addLeaseCommon(StatementIndex stindex, std::vector& bind);  Stephen Morris committed Nov 21, 2012 507   Stephen Morris committed Nov 23, 2012 508 509 510 511 512 513  /// @brief Get Lease Collection Common Code /// /// This method performs the common actions for obtaining multiple leases /// from the database. /// /// @param stindex Index of statement being executed  Stephen Morris committed Nov 26, 2012 514  /// @param bind MYSQL_BIND array for input parameters  Stephen Morris committed Nov 23, 2012 515  /// @param exchange Exchange object to use  Stephen Morris committed Dec 03, 2012 516 517 518  /// @param lease LeaseCollection object returned. Note that any leases in /// the collection when this method is called are not erased: the /// new data is appended to the end.  Stephen Morris committed Nov 23, 2012 519 520 521 522 523 524 525 526 527  /// @param single If true, only a single data item is to be retrieved. /// If more than one is present, a MultipleRecords exception will /// be thrown. /// /// @throw isc::dhcp::BadValue Data retrieved from the database was invalid. /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed. /// @throw isc::dhcp::MultipleRecords Multiple records were retrieved /// from the database where only one was expected.  Stephen Morris committed Nov 23, 2012 528  template  Stephen Morris committed Nov 26, 2012 529  void getLeaseCollection(StatementIndex stindex, MYSQL_BIND* bind,  Stephen Morris committed Nov 23, 2012 530 531  Exchange& exchange, LeaseCollection& result, bool single = false) const;  Stephen Morris committed Nov 23, 2012 532   Stephen Morris committed Nov 23, 2012 533  /// @brief Get Lease Collection  Stephen Morris committed Nov 06, 2012 534  ///  Stephen Morris committed Nov 23, 2012 535 536  /// Gets a collection of Lease4 objects. This is just an interface to /// the get lease collection common code.  Stephen Morris committed Nov 06, 2012 537  ///  Stephen Morris committed Nov 23, 2012 538  /// @param stindex Index of statement being executed  Stephen Morris committed Nov 26, 2012 539  /// @param bind MYSQL_BIND array for input parameters  Stephen Morris committed Dec 03, 2012 540 541 542  /// @param lease LeaseCollection object returned. Note that any leases in /// the collection when this method is called are not erased: the /// new data is appended to the end.  Stephen Morris committed Nov 23, 2012 543 544 545 546 547 548  /// /// @throw isc::dhcp::BadValue Data retrieved from the database was invalid. /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed. /// @throw isc::dhcp::MultipleRecords Multiple records were retrieved /// from the database where only one was expected.  Stephen Morris committed Nov 26, 2012 549  void getLeaseCollection(StatementIndex stindex, MYSQL_BIND* bind,  Stephen Morris committed Nov 23, 2012 550  Lease4Collection& result) const {  Stephen Morris committed Nov 26, 2012 551  getLeaseCollection(stindex, bind, exchange4_, result);  Stephen Morris committed Nov 23, 2012 552 553 554 555 556 557 558 559  } /// @brief Get Lease Collection /// /// Gets a collection of Lease6 objects. This is just an interface to /// the get lease collection common code. /// /// @param stindex Index of statement being executed  Stephen Morris committed Nov 26, 2012 560  /// @param bind MYSQL_BIND array for input parameters  Stephen Morris committed Dec 03, 2012 561 562  /// @param lease LeaseCollection object returned. Note that any existing /// data in the collection is erased first.  Stephen Morris committed Nov 23, 2012 563 564 565 566 567 568  /// /// @throw isc::dhcp::BadValue Data retrieved from the database was invalid. /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed. /// @throw isc::dhcp::MultipleRecords Multiple records were retrieved /// from the database where only one was expected.  Stephen Morris committed Nov 26, 2012 569  void getLeaseCollection(StatementIndex stindex, MYSQL_BIND* bind,  Stephen Morris committed Nov 23, 2012 570  Lease6Collection& result) const {  Stephen Morris committed Nov 26, 2012 571  getLeaseCollection(stindex, bind, exchange6_, result);  Stephen Morris committed Nov 23, 2012 572 573  }  Stephen Morris committed Dec 03, 2012 574  /// @brief Get Lease4 Common Code  Stephen Morris committed Nov 23, 2012 575 576 577 578 579 580  /// /// This method performs the common actions for the various getLease4() /// methods. It acts as an interface to the getLeaseCollection() method, /// but retrieveing only a single lease. /// /// @param stindex Index of statement being executed  Stephen Morris committed Nov 26, 2012 581  /// @param bind MYSQL_BIND array for input parameters  Stephen Morris committed Nov 23, 2012 582  /// @param lease Lease4 object returned  Stephen Morris committed Nov 26, 2012 583  void getLease(StatementIndex stindex, MYSQL_BIND* bind,  Stephen Morris committed Nov 23, 2012 584 585  Lease4Ptr& result) const;  Stephen Morris committed Dec 03, 2012 586  /// @brief Get Lease6 Common Code  Stephen Morris committed Nov 23, 2012 587  ///  Stephen Morris committed Dec 03, 2012 588  /// This method performs the common actions for the various getLease46)  Stephen Morris committed Nov 23, 2012 589 590 591 592  /// methods. It acts as an interface to the getLeaseCollection() method, /// but retrieveing only a single lease. /// /// @param stindex Index of statement being executed  Stephen Morris committed Nov 26, 2012 593  /// @param bind MYSQL_BIND array for input parameters  Stephen Morris committed Nov 23, 2012 594  /// @param lease Lease6 object returned  Stephen Morris committed Nov 26, 2012 595  void getLease(StatementIndex stindex, MYSQL_BIND* bind,  Stephen Morris committed Nov 23, 2012 596 597 598 599 600 601 602  Lease6Ptr& result) const; /// @brief Update lease common code /// /// Holds the common code for updating a lease. It binds the parameters /// to the prepared statement, executes it, then checks how many rows /// were affected.  Stephen Morris committed Nov 06, 2012 603 604  /// /// @param stindex Index of prepared statement to be executed  Stephen Morris committed Nov 23, 2012 605  /// @param bind Array of MYSQL_BIND objects representing the parameters.  Stephen Morris committed Nov 06, 2012 606 607  /// (Note that the number is determined by the number of parameters /// in the statement.)  Stephen Morris committed Nov 23, 2012 608  /// @param lease Pointer to the lease object whose record is being updated.  Stephen Morris committed Nov 06, 2012 609  ///  Stephen Morris committed Nov 23, 2012 610 611  /// @throw NoSuchLease Could not update a lease because no lease matches /// the address given.  Stephen Morris committed Nov 08, 2012 612 613  /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Nov 23, 2012 614  template  Stephen Morris committed Nov 26, 2012 615 616  void updateLeaseCommon(StatementIndex stindex, MYSQL_BIND* bind, const LeasePtr& lease);  Stephen Morris committed Nov 23, 2012 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633  /// @brief Delete lease common code /// /// Holds the common code for deleting a lease. It binds the parameters /// to the prepared statement, executes the statement and checks to /// see how many rows were deleted. /// /// @param stindex Index of prepared statement to be executed /// @param bind Array of MYSQL_BIND objects representing the parameters. /// (Note that the number is determined by the number of parameters /// in the statement.) /// /// @return true if one or more rows were deleted, false if none were /// deleted. /// /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Dec 10, 2012 634  bool deleteLeaseCommon(StatementIndex stindex, MYSQL_BIND* bind);  Stephen Morris committed Nov 06, 2012 635   Stephen Morris committed Oct 20, 2012 636 637 638 639 640 641 642 643 644 645  /// @brief Check Error and Throw Exception /// /// Virtually all MySQL functions return a status which, if non-zero, /// indicates an error. This inline function conceals a lot of error /// checking/exception-throwing code. /// /// @param status Status code: non-zero implies an error /// @param index Index of statement that caused the error /// @param what High-level description of the error ///  Stephen Morris committed Nov 08, 2012 646 647  /// @throw isc::dhcp::DbOperationError An operation on the open database has /// failed.  Stephen Morris committed Oct 22, 2012 648  inline void checkError(int status, StatementIndex index,  Stephen Morris committed Oct 20, 2012 649 650 651  const char* what) const { if (status != 0) { isc_throw(DbOperationError, what << " for <" <<  Stephen Morris committed Oct 24, 2012 652  text_statements_[index] << ">, reason: " <<  Stephen Morris committed Oct 22, 2012 653 654  mysql_error(mysql_) << " (error code " << mysql_errno(mysql_) << ")");  Stephen Morris committed Oct 20, 2012 655 656 657  } }  Stephen Morris committed Oct 17, 2012 658  // Members  Stephen Morris committed Nov 06, 2012 659   Stephen Morris committed Nov 23, 2012 660 661 662 663  /// The exchange objects are used for transfer of data to/from the database. /// They are pointed-to objects as the contents may change in "const" calls, /// while the rest of this object does not. (At alternative would be to /// declare them as "mutable".)  Stephen Morris committed Nov 21, 2012 664 665  boost::scoped_ptr exchange4_; ///< Exchange object boost::scoped_ptr exchange6_; ///< Exchange object  Jelte Jansen committed Mar 07, 2013 666  MySqlHolder mysql_;  Stephen Morris committed Nov 23, 2012 667 668  std::vector statements_; ///< Prepared statements std::vector text_statements_; ///< Raw text of statements  Stephen Morris committed Oct 16, 2012 669 670 671 672 673 }; }; // end of isc::dhcp namespace }; // end of isc namespace  Stephen Morris committed Oct 29, 2012 674 #endif // MYSQL_LEASE_MGR_H