1/* 2 * Copyright (c) 2007, 2008, 2009, 2012, ETH Zurich. 3 * All rights reserved. 4 * 5 * This file is distributed under the terms in the attached LICENSE file. 6 * If you do not find this file, copies can be found by writing to: 7 * ETH Zurich D-INFK, CAB F.78, Universitaetstrasse 6, CH-8092 Zurich, 8 * Attn: Systems Group. 9 */ 10 11interface octopus "octopus RPC Interface" { 12 13 alias mode uint64; 14 alias trigger_id uint64; 15 typedef enum {BINDING_RPC, BINDING_EVENT} binding_type; 16 17 // XXX: No flounder support for pointer values 18 typedef struct { 19 errval in_case; 20 binding_type send_to; 21 mode m; 22 uint64 trigger; 23 uint64 st; 24 } trigger; 25 26 // 27 // Binding Identification 28 // 29 rpc get_identifier(out uint64 id); 30 rpc identify(in uint64 id, in binding_type type); 31 32 33 // 34 // Get/Set API 35 // 36 37 /** 38 * \param query Records to find. 39 * \param t Additional trigger to watch for future events. 40 * \param output Comma separated String of record names or NULL on error. 41 * \param tid Id of registered trigger (0 in case no trigger registered). 42 * \param error_code Error value of request. 43 */ 44 rpc get_names(in String query[8192], in trigger t, out String output[8192], 45 out trigger_id tid, out errval error_code); 46 47 /** 48 * \param query Record to find. 49 * \param t Additional trigger to watch for future events. 50 * \param output Retrieved record or NULL on error. 51 * \param tid Id of registered trigger (0 in case no trigger registered). 52 * \param error_code Error value of request. 53 */ 54 rpc get(in String query[8192], in trigger t, out String output[8192], 55 out trigger_id tid, out errval error_code); 56 57 /** 58 * \param query Record to set. 59 * \param mode Set mode (see getset.h). 60 * \param t Additional trigger to watch for future events. 61 * \param get Return record if it has been set. 62 * \param record In case get is true and no error_code is ok 63 * contains record, otherwise NULL 64 * \param tid Id of registered trigger (0 in case no trigger registered). 65 * \param error_code Error value of request 66 */ 67 rpc set(in String query[8192], in uint64 mode, in trigger t, in bool get, 68 out String record[8192], out trigger_id tid, out errval error_code); 69 70 /** 71 * Find a record using an ID capability as the key/name of the record. 72 * 73 * \param idcap ID capability used as the name of the record. 74 * \param t Additional trigger to watch for future events. 75 * \param output Retrieved record or NULL on error. 76 * \param tid Id of registered trigger (0 in case no trigger registered). 77 * \param error_code Error value of request. 78 */ 79 rpc get_with_idcap(in cap idcap, in trigger t, out String output[8192], 80 out trigger_id tid, out errval error_code); 81 82 /** 83 * Set a record using an ID capability as the key/name of the record. 84 * 85 * \param idcap ID capability used as the key/name of the record. 86 * \param attributes Attributes to store in the record. 87 * \param mode Set mode (see getset.h). 88 * \param t Additional trigger to watch for future events. 89 * \param get Return record if it has been set. 90 * \param record In case get is true and no error_code is ok 91 * contains record, otherwise NULL 92 * \param tid Id of registered trigger (0 in case no trigger registered). 93 * \param error_code Error value of request 94 */ 95 rpc set_with_idcap(in cap idcap, in String attributes[2048], in uint64 mode, 96 in trigger t, in bool get, out String record[2048], 97 out trigger_id tid, out errval error_code); 98 99 /** 100 * \param query Record(s) to delete. 101 * \param t Additional trigger to watch for future events. 102 * \param tid Id of registered trigger (0 in case no trigger registered). 103 * \param error_code Error value of request 104 */ 105 rpc del(in String query[8192], in trigger t, out trigger_id tid, 106 out errval error_code); 107 108 /** 109 * \param query 110 * \param t Additional trigger to watch for future events. 111 * \param tid Id of registered trigger (0 in case no trigger registered). 112 * \param error_code Error value of request. 113 */ 114 rpc exists(in String query[8192], in trigger t, out trigger_id tid, 115 out errval error_code); 116 117 /** 118 * \brief Blocks until a record matching the provided query is registered. 119 * 120 * This was introduced specifically for the nameserver API 121 * due to limitations of the memory allocation during bootstrapping we 122 * can't use THC but need to support nameservice blocking lookup. 123 * If you use this call you might want to consider using 124 * a combination of get and triggers. 125 * 126 * \param query 127 * \param record 128 * \param error_code 129 */ 130 rpc wait_for(in String query[8192], out String record[2048], out errval error_code); 131 132 /** 133 * \brief Used to remove Triggers in case they are not needed anymore. 134 * 135 * Note that non persistent trigger are removed automatically after 136 * they have fired. For persistent triggers be aware that you might 137 * still get a notification after the trigger has been removed because 138 * trigger events are sent over another binding. 139 * 140 * \param id Trigger ID to remove 141 * \param error_code Error of operation 142 */ 143 rpc remove_trigger(in uint64 id, out errval error_code); 144 145 146 // 147 // Publish/Subscribe API 148 // 149 150 /** 151 * \param query 152 * \param client_state Additional state supplied by client. 153 * \param id Identifier for this subscription supplied by server. 154 * \param error_code Status of request. 155 */ 156 rpc subscribe(in String query[8192], in uint64 trigger_fn, in uint64 state, 157 out uint64 id, out errval error_code); 158 159 /** 160 * \param id Id for the subscription 161 * \param error_code Status of request 162 */ 163 rpc unsubscribe(in uint64 id, out errval error_code); 164 165 /** 166 * \param record Message to publish. 167 * \param error_code Status of request. 168 */ 169 rpc publish(in String record[2048], out errval error_code); 170 171 172 // 173 // Async events (sent by server to client) 174 // 175 message trigger(trigger_id id, uint64 trigger_fn, mode m, String record[2048], 176 uint64 state); 177 178 message subscription(trigger_id id, uint64 trigger_fn, mode m, 179 String record[2048], uint64 state); 180 181 182 // 183 // Backward compability with chips 184 // 185 186 // Simple capability storage 187 rpc get_cap(in String key[256], out cap retcap, out errval reterr); 188 rpc put_cap(in String key[256], in cap storecap, out errval reterr); 189 rpc sput_cap(in String key[256], in cap storecap, out String retkey[256], out errval reterr); 190 rpc remove_cap(in String key[256], out errval reterr); 191}; 192