octopus: remove include to flounder file in public include
[barrelfish] / include / octopus_server / query.h
1 /**
2  * \file
3  * \brief octopus Query Interface Header file
4  *
5  * The server must implement this interface in order for dist2
6  * to work accordingly.
7  */
8
9 /*
10  * Copyright (c) 2011, ETH Zurich.
11  * All rights reserved.
12  *
13  * This file is distributed under the terms in the attached LICENSE file.
14  * If you do not find this file, copies can be found by writing to:
15  * ETH Zurich D-INFK, Haldeneggsteig 4, CH-8092 Zurich. Attn: Systems Group.
16  */
17
18 #ifndef OCTOPUS_QUERY_H_
19 #define OCTOPUS_QUERY_H_
20
21 #include <barrelfish/barrelfish.h>
22
23
24 #include <octopus_server/service.h>
25 #include <octopus/parser/ast.h>
26
27 /**
28  * \brief Stores a binding for the given id.
29  *
30  * Used to find the event binding for a given RPC connection
31  * since in a regular flounder interface RPC calls are on on a
32  * different waitset we currently need two binding.
33  *
34  * \param type Binding type (RPC or Event)
35  * \param id Identifier unique per client
36  * \param binding Pointer value of binding
37  *
38  * \retval SYS_ERR_OK
39  * \retval OCT_ERR_UNSUPPORTED_BINDING
40  * \retval OCT_ERR_ENGINE_FAIL
41  * \retval LIB_ERR_MALLOC_FAIL
42  */
43 errval_t set_binding(octopus_binding_type_t type, uint64_t id, void* binding);
44
45 /**
46  * Given a query returns a number of record names matching
47  * the query. The record names are stored as a comma separated string
48  * in oct_query_state.
49  *
50  * \param ast Abstract Syntax Tree of query.
51  * \param dqs Contains the result of the query invocation.
52  *
53  * \retval SYS_ERR_OK
54  * \retval OCT_ERR_NO_RECORD
55  * \retval OCT_ERR_ENGINE_FAIL
56  */
57 errval_t get_record_names(struct ast_object* ast, struct oct_query_state* dqs);
58
59 /**
60  * \brief Returns a record matching the given query.
61  *
62  * \param ast Query supplied by client converted to AST.
63  * \param dqs Contains the result of the query invocation.
64  *
65  * \retval SYS_ERR_OK
66  * \retval OCT_ERR_NO_RECORD
67  * \retval OCT_ERR_ENGINE_FAIL
68  */
69 errval_t get_record(struct ast_object* ast, struct oct_query_state* dqs);
70
71 /**
72  * \brief Stores a record in the database.
73  *
74  * \param ast Record to set.
75  * \param mode A combination of modes as defined in getset.h.
76  * \param dqs Returned result of query invocation.
77  *
78  * \retval SYS_ERR_OK
79  * \retval OCT_ERR_ENGINE_FAIL
80  */
81 errval_t set_record(struct ast_object* ast, uint64_t mode,
82         struct oct_query_state* dqs);
83
84 /**
85  * \brief Deletes a record in the database.
86  *
87  * \param ast Record to delete.
88  * \param dqs Returned result of query invocation.
89  *
90  * \retval SYS_ERR_OK
91  * \retval OCT_ERR_NO_RECORD
92  * \retval OCT_ERR_ENGINE_FAIL
93  */
94 errval_t del_record(struct ast_object*, struct oct_query_state*);
95
96 /**
97  * Sets a watch for a record(s) matching the given query. The Query Engine
98  * is supposed to use the drs struct to reply to the client once the watch is
99  * triggered.
100  *
101  * \param b RPC Binding
102  * \param ast AST to watch for
103  * \param mode When to trigger the watch (del or set).
104  * \param drs Reply state used to reply to the client.
105  * \param wid ID of the installed watch (used for remove).
106  *
107  * \retval SYS_ERR_OK
108  * \retval OCT_ERR_ENGINE_FAIL
109  */
110 errval_t set_watch(struct octopus_binding* b, struct ast_object* ast,
111         uint64_t mode, struct oct_reply_state* drs, uint64_t* wid);
112
113 /**
114  * \brief Removes a watch
115  *
116  * \param b Binding of caller
117  * \param id Trigger Id supplied by caller
118  * \param dqs Query state
119  *
120  * \retval SYS_ERR_OK
121  * \retval OCT_ERR_INVALID_ID
122  * \retval OCT_ERR_ENGINE_FAIL
123  */
124 errval_t del_watch(struct octopus_binding* b, octopus_trigger_id_t id,
125         struct oct_query_state* dqs);
126
127 /**
128  * \brief Adds a subscription.
129  *
130  * \param b RPC binding of subscriber.
131  * \param ast Subscription template (to match with published records).
132  * \param trigger_fn Client handler function.
133  * \param state Additional state argument supplied by client.
134  * \param drs Returned result of query invocation.
135  *
136  * \retval SYS_ERR_OK
137  * \retval OCT_ERR_MAX_SUBSCRIPTIONS
138  * \retval OCT_ERR_ENGINE_FAIL
139  * \retval LIB_ERR_MALLOC_FAIL
140  */
141 errval_t add_subscription(struct octopus_binding* b, struct ast_object* ast,
142         uint64_t trigger_fn, uint64_t state, struct oct_reply_state* drs);
143
144 /**
145  * \brief Deletes a subscription for a given (Binding, Id) pair.
146  *
147  * \param b RPC binding of subscriber.
148  * \param id ID of the subscription.
149  * \param dqs Returned result of query invocation.
150  *
151  * \retval SYS_ERR_OK
152  * \retval OCT_ERR_NO_SUBSCRIPTION
153  * \retval OCT_ERR_ENGINE_FAIL
154  */
155 errval_t del_subscription(struct octopus_binding* b, uint64_t id,
156         struct oct_query_state* dqs);
157
158 /**
159  * Find all subscribers with a matching subscription for the given
160  * AST.
161  *
162  * \param ast Record to match with stored subscription.
163  * \param dqs Returned result of query invocation.
164  *
165  * \retval SYS_ERR_OK
166  * \retval OCT_ERR_NO_SUBSCRIBERS
167  * \retval OCT_ERR_ENGINE_FAIL
168  */
169 errval_t find_subscribers(struct ast_object* ast, struct oct_query_state* dqs);
170
171 /**
172  * \brief Find the event binding of the client based on his RPC binding.
173  *
174  * \param binding RPC binding
175  * \return Pointer of event binding or NULL on error.
176  */
177 struct octopus_binding* get_event_binding(struct octopus_binding* binding);
178
179 #endif /* OCTOPUS_QUERY_H_ */