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