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 #include "ovsdb-types.h"
  37
  38 struct json;
  39 struct ovsdb_datum;
  40 struct ovsdb_idl_class;
  41 struct ovsdb_idl_column;
  42 struct ovsdb_idl_table_class;
  43 struct uuid;
  44
  45 struct ovsdb_idl *ovsdb_idl_create(const char *remote,
  46                                    const struct ovsdb_idl_class *);
  47 void ovsdb_idl_destroy(struct ovsdb_idl *);
  48
  49 bool ovsdb_idl_run(struct ovsdb_idl *);
  50 void ovsdb_idl_wait(struct ovsdb_idl *);
  51
  52 unsigned int ovsdb_idl_get_seqno(const struct ovsdb_idl *);
  53 bool ovsdb_idl_has_ever_connected(const struct ovsdb_idl *);
  54 void ovsdb_idl_force_reconnect(struct ovsdb_idl *);
  55
  56 const struct ovsdb_idl_row *ovsdb_idl_get_row_for_uuid(
  57     const struct ovsdb_idl *, const struct ovsdb_idl_table_class *,
  58     const struct uuid *);
  59 const struct ovsdb_idl_row *ovsdb_idl_first_row(
  60     const struct ovsdb_idl *, const struct ovsdb_idl_table_class *);
  61 const struct ovsdb_idl_row *ovsdb_idl_next_row(const struct ovsdb_idl_row *);
  62
  63 const struct ovsdb_datum *ovsdb_idl_read(const struct ovsdb_idl_row *,
  64                                          const struct ovsdb_idl_column *);
  65 const struct ovsdb_datum *ovsdb_idl_get(const struct ovsdb_idl_row *,
  66                                         const struct ovsdb_idl_column *,
  67                                         enum ovsdb_atomic_type key_type,
  68                                         enum ovsdb_atomic_type value_type);
  69
  70 enum ovsdb_idl_txn_status {
  71     TXN_UNCHANGED,              /* Transaction didn't include any changes. */
  72     TXN_INCOMPLETE,             /* Commit in progress, please wait. */
  73     TXN_ABORTED,                /* ovsdb_idl_txn_abort() called. */
  74     TXN_SUCCESS,                /* Commit successful. */
  75     TXN_TRY_AGAIN,              /* Commit failed because a "verify" operation
  76                                  * reported an inconsistency, due to a network
  77                                  * problem, or other transient failure. */
  78     TXN_ERROR                   /* Commit failed due to a hard error. */
  79 };
  80
  81 const char *ovsdb_idl_txn_status_to_string(enum ovsdb_idl_txn_status);
  82
  83 struct ovsdb_idl_txn *ovsdb_idl_txn_create(struct ovsdb_idl *);
  84 void ovsdb_idl_txn_add_comment(struct ovsdb_idl_txn *, const char *, ...)
  85     PRINTF_FORMAT (2, 3);
  86 void ovsdb_idl_txn_set_dry_run(struct ovsdb_idl_txn *);
  87 void ovsdb_idl_txn_increment(struct ovsdb_idl_txn *, const char *table,
  88                              const char *column, const struct json *where);
  89 void ovsdb_idl_txn_destroy(struct ovsdb_idl_txn *);
  90 void ovsdb_idl_txn_wait(const struct ovsdb_idl_txn *);
  91 enum ovsdb_idl_txn_status ovsdb_idl_txn_commit(struct ovsdb_idl_txn *);
  92 enum ovsdb_idl_txn_status ovsdb_idl_txn_commit_block(struct ovsdb_idl_txn *);
  93 void ovsdb_idl_txn_abort(struct ovsdb_idl_txn *);
  94
  95 const char *ovsdb_idl_txn_get_error(const struct ovsdb_idl_txn *);
  96
  97 int64_t ovsdb_idl_txn_get_increment_new_value(const struct ovsdb_idl_txn *);
  98 const struct uuid *ovsdb_idl_txn_get_insert_uuid(const struct ovsdb_idl_txn *,
  99                                                  const struct uuid *);
 100
 101 void ovsdb_idl_txn_write(const struct ovsdb_idl_row *,
 102                          const struct ovsdb_idl_column *,
 103                          struct ovsdb_datum *);
 104 void ovsdb_idl_txn_delete(const struct ovsdb_idl_row *);
 105 const struct ovsdb_idl_row *ovsdb_idl_txn_insert(
 106     struct ovsdb_idl_txn *, const struct ovsdb_idl_table_class *,
 107     const struct uuid *);
 108
 109 struct ovsdb_idl *ovsdb_idl_txn_get_idl (struct ovsdb_idl_txn *);
 110
 111 #endif /* ovsdb-idl.h */