lib/ovsdb-idl.h

   1 /* Copyright (c) 2009, 2010 Nicira Networks.
   2  *
   3  * Licensed under the Apache License, Version 2.0 (the "License");
   4  * you may not use this file except in compliance with the License.
   5  * You may obtain a copy of the License at:
   6  *
   7  *     http://www.apache.org/licenses/LICENSE-2.0
   8  *
   9  * Unless required by applicable law or agreed to in writing, software
  10  * distributed under the License is distributed on an "AS IS" BASIS,
  11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12  * See the License for the specific language governing permissions and
  13  * limitations under the License.
  14  */
  15
  16 #ifndef OVSDB_IDL_H
  17 #define OVSDB_IDL_H 1
  18
  19 /* Open vSwitch Database Interface Definition Language (OVSDB IDL).
  20  *
  21  * The OVSDB IDL maintains an in-memory replica of a database.  It issues RPC
  22  * requests to an OVSDB database server and parses the responses, converting
  23  * raw JSON into data structures that are easier for clients to digest.  Most
  24  * notably, references to rows via UUID become C pointers.
  25  *
  26  * The IDL also assists with issuing database transactions.  The client creates
  27  * a transaction, manipulates the IDL data structures, and commits or aborts
  28  * the transaction.  The IDL then composes and issues the necessary JSON-RPC
  29  * requests and reports to the client whether the transaction completed
  30  * successfully.
  31  */
  32
  33 #include <stdbool.h>
  34 #include <stdint.h>
  35 #include "compiler.h"
  36
  37 struct json;
  38 struct ovsdb_datum;
  39 struct ovsdb_idl_class;
  40 struct ovsdb_idl_column;
  41 struct ovsdb_idl_table_class;
  42 struct uuid;
  43
  44 struct ovsdb_idl *ovsdb_idl_create(const char *remote,
  45                                    const struct ovsdb_idl_class *);
  46 void ovsdb_idl_destroy(struct ovsdb_idl *);
  47
  48 bool ovsdb_idl_run(struct ovsdb_idl *);
  49 void ovsdb_idl_wait(struct ovsdb_idl *);
  50
  51 unsigned int ovsdb_idl_get_seqno(const struct ovsdb_idl *);
  52 bool ovsdb_idl_has_ever_connected(const struct ovsdb_idl *);
  53 void ovsdb_idl_force_reconnect(struct ovsdb_idl *);
  54
  55 const struct ovsdb_idl_row *ovsdb_idl_get_row_for_uuid(
  56     const struct ovsdb_idl *, const struct ovsdb_idl_table_class *,
  57     const struct uuid *);
  58 const struct ovsdb_idl_row *ovsdb_idl_first_row(
  59     const struct ovsdb_idl *, const struct ovsdb_idl_table_class *);
  60 const struct ovsdb_idl_row *ovsdb_idl_next_row(const struct ovsdb_idl_row *);
  61
  62 enum ovsdb_idl_txn_status {
  63     TXN_UNCHANGED,              /* Transaction didn't include any changes. */
  64     TXN_INCOMPLETE,             /* Commit in progress, please wait. */
  65     TXN_ABORTED,                /* ovsdb_idl_txn_abort() called. */
  66     TXN_SUCCESS,                /* Commit successful. */
  67     TXN_TRY_AGAIN,              /* Commit failed because a "verify" operation
  68                                  * reported an inconsistency, due to a network
  69                                  * problem, or other transient failure. */
  70     TXN_ERROR                   /* Commit failed due to a hard error. */
  71 };
  72
  73 const char *ovsdb_idl_txn_status_to_string(enum ovsdb_idl_txn_status);
  74
  75 struct ovsdb_idl_txn *ovsdb_idl_txn_create(struct ovsdb_idl *);
  76 void ovsdb_idl_txn_add_comment(struct ovsdb_idl_txn *, const char *, ...)
  77     PRINTF_FORMAT (2, 3);
  78 void ovsdb_idl_txn_set_dry_run(struct ovsdb_idl_txn *);
  79 void ovsdb_idl_txn_increment(struct ovsdb_idl_txn *, const char *table,
  80                              const char *column, const struct json *where);
  81 void ovsdb_idl_txn_destroy(struct ovsdb_idl_txn *);
  82 void ovsdb_idl_txn_wait(const struct ovsdb_idl_txn *);
  83 enum ovsdb_idl_txn_status ovsdb_idl_txn_commit(struct ovsdb_idl_txn *);
  84 enum ovsdb_idl_txn_status ovsdb_idl_txn_commit_block(struct ovsdb_idl_txn *);
  85 void ovsdb_idl_txn_abort(struct ovsdb_idl_txn *);
  86
  87 const char *ovsdb_idl_txn_get_error(const struct ovsdb_idl_txn *);
  88
  89 int64_t ovsdb_idl_txn_get_increment_new_value(const struct ovsdb_idl_txn *);
  90 const struct uuid *ovsdb_idl_txn_get_insert_uuid(const struct ovsdb_idl_txn *,
  91                                                  const struct uuid *);
  92
  93 void ovsdb_idl_txn_read(const struct ovsdb_idl_row *,
  94                         const struct ovsdb_idl_column *,
  95                         struct ovsdb_datum *);
  96 void ovsdb_idl_txn_write(const struct ovsdb_idl_row *,
  97                          const struct ovsdb_idl_column *,
  98                          struct ovsdb_datum *);
  99 void ovsdb_idl_txn_delete(const struct ovsdb_idl_row *);
 100 const struct ovsdb_idl_row *ovsdb_idl_txn_insert(
 101     struct ovsdb_idl_txn *, const struct ovsdb_idl_table_class *,
 102     const struct uuid *);
 103
 104 struct ovsdb_idl *ovsdb_idl_txn_get_idl (struct ovsdb_idl_txn *);
 105
 106 #endif /* ovsdb-idl.h */