Changeset a742608 in ingen


Ignore:
Timestamp:
10/24/15 19:02:45 (2 years ago)
Author:
David Robillard <d@…>
Branches:
master, groups, nodeless, parallel, parameters, sequencefix
Children:
cbd64a41
Parents:
557f9d42
Message:

Document protocol

Fix invalid use of patch:request (use patch:sequenceNumber instead).

git-svn-id: http://svn.drobilla.net/lad/trunk/ingen@5781 a436a847-0d15-0410-975c-d299462d15a1

Files:
1 added
11 edited

Legend:

Unmodified
Added
Removed
  • doc/reference.doxygen.in

    rb71d638 ra742608  
    372372# The default value is: NO. 
    373373 
    374 INLINE_SIMPLE_STRUCTS  = NO 
     374INLINE_SIMPLE_STRUCTS  = YES 
    375375 
    376376# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or 
     
    756756 
    757757INPUT                  = @INGEN_SRCDIR@/ingen \ 
     758                         @INGEN_SRCDIR@/src \ 
    758759                         @INGEN_SRCDIR@/ingen/client \ 
    759760                         @INGEN_SRCDIR@/src/server/events/ 
     
    10711072# This tag requires that the tag GENERATE_HTML is set to YES. 
    10721073 
    1073 HTML_STYLESHEET        = 
     1074HTML_STYLESHEET        = @INGEN_SRCDIR@/doc/style.css 
     1075 
    10741076 
    10751077# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional user- 
     
    11031105# This tag requires that the tag GENERATE_HTML is set to YES. 
    11041106 
    1105 HTML_COLORSTYLE_HUE    = 220 
     1107HTML_COLORSTYLE_HUE    = 160 
    11061108 
    11071109# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors 
     
    11111113# This tag requires that the tag GENERATE_HTML is set to YES. 
    11121114 
    1113 HTML_COLORSTYLE_SAT    = 100 
     1115HTML_COLORSTYLE_SAT    = 40 
    11141116 
    11151117# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the 
     
    11381140# This tag requires that the tag GENERATE_HTML is set to YES. 
    11391141 
    1140 HTML_DYNAMIC_SECTIONS  = NO 
     1142HTML_DYNAMIC_SECTIONS  = YES 
    11411143 
    11421144# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries 
     
    15891591# This tag requires that the tag GENERATE_LATEX is set to YES. 
    15901592 
    1591 COMPACT_LATEX          = NO 
     1593COMPACT_LATEX          = YES 
    15921594 
    15931595# The PAPER_TYPE tag can be used to set the paper type that is used by the 
     
    16491651# This tag requires that the tag GENERATE_LATEX is set to YES. 
    16501652 
    1651 PDF_HYPERLINKS         = NO 
     1653PDF_HYPERLINKS         = YES 
    16521654 
    16531655# If the LATEX_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate 
     
    16571659# This tag requires that the tag GENERATE_LATEX is set to YES. 
    16581660 
    1659 USE_PDFLATEX           = NO 
     1661USE_PDFLATEX           = YES 
    16601662 
    16611663# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode 
     
    16731675# This tag requires that the tag GENERATE_LATEX is set to YES. 
    16741676 
    1675 LATEX_HIDE_INDICES     = NO 
     1677LATEX_HIDE_INDICES     = YES 
    16761678 
    16771679# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source 
  • ingen/Parser.hpp

    r84135d2 ra742608  
    6969    /** Parse a graph from RDF into a Interface (engine or client). 
    7070     * 
    71      * @param path If this is a file path, then the graph is loaded from that 
     71     * If `path` is a file path, then the graph is loaded from that 
    7272     * file.  If it is a directory, then the manifest.ttl from that directory 
    7373     * is used instead.  In either case, any rdfs:seeAlso files are loaded and 
  • ingen/URIs.hpp

    r732bfb33 ra742608  
    179179    const Quark patch_property; 
    180180    const Quark patch_remove; 
    181     const Quark patch_request; 
    182181    const Quark patch_sequenceNumber; 
    183182    const Quark patch_subject; 
  • src/AtomReader.cpp

    r732bfb33 ra742608  
    329329        _iface.move(*subject_path, *dest_path); 
    330330    } else if (obj->body.otype == _uris.patch_Response) { 
    331         const LV2_Atom* request = NULL; 
    332         const LV2_Atom* body    = NULL; 
     331        const LV2_Atom* seq = NULL; 
     332        const LV2_Atom* body = NULL; 
    333333        lv2_atom_object_get(obj, 
    334                             (LV2_URID)_uris.patch_request, &request, 
     334                            (LV2_URID)_uris.patch_sequenceNumber, &seq, 
    335335                            (LV2_URID)_uris.patch_body, &body, 
    336336                            0); 
    337         if (!request || request->type != _uris.atom_Int) { 
    338             _log.warn("Response message has no request\n"); 
     337        if (!seq || seq->type != _uris.atom_Int) { 
     338            _log.warn("Response message has no sequence number\n"); 
    339339            return false; 
    340340        } else if (!body || body->type != _uris.atom_Int) { 
     
    342342            return false; 
    343343        } 
    344         _iface.response(((const LV2_Atom_Int*)request)->body, 
     344        _iface.response(((const LV2_Atom_Int*)seq)->body, 
    345345                        (Ingen::Status)((const LV2_Atom_Int*)body)->body, 
    346346                        subject_uri ? subject_uri->c_str() : ""); 
  • src/AtomWriter.cpp

    r6b199af ra742608  
    122122} 
    123123 
     124/** @page protocol Ingen Protocol 
     125 * @tableofcontents 
     126 * 
     127 * @section methods Methods 
     128 */ 
     129 
     130/** @page protocol 
     131 * @subsection Put 
     132 * 
     133 * Use [patch:Put](http://lv2plug.in/ns/ext/patch#Put) to set properties on an 
     134 * object, creating it if necessary. 
     135 * 
     136 * If the object already exists, all existing object properties with keys that 
     137 * match any property in the message are first removed.  Other properties are 
     138 * left unchanged. 
     139 * 
     140 * If the object does not yet exist, the message must contain sufficient 
     141 * information to create it (e.g. supported rdf:type properties). 
     142 * 
     143 * @code{.ttl} 
     144 * [] 
     145 *     a patch:Put ; 
     146 *     patch:subject </graph/osc> ; 
     147 *     patch:body [ 
     148 *         a ingen:Block ; 
     149 *         lv2:prototype <http://drobilla.net/plugins/mda/Shepard> 
     150 *     ] . 
     151 * @endcode 
     152 */ 
    124153void 
    125154AtomWriter::put(const Raul::URI&            uri, 
     
    142171} 
    143172 
     173/** @page protocol 
     174 * @subsection Patch 
     175 * 
     176 * Use [patch:Patch](http://lv2plug.in/ns/ext/patch#Patch) to manipulate the 
     177 * properties of an object.  A set of properties are first removed, then 
     178 * another is added.  Analogous to WebDAV PROPPATCH. 
     179 * 
     180 * The special value [patch:wildcard](http://lv2plug.in/ns/ext/patch#wildcard) 
     181 * may be used to specify that any value with the given key should be removed. 
     182 * 
     183 * @code{.ttl} 
     184 * [] 
     185 *     a patch:Patch ; 
     186 *     patch:subject </graph/osc> ; 
     187 *     patch:add [ 
     188 *         lv2:name "Osckillator" ; 
     189 *         ingen:canvasX 32.0 ; 
     190 *         ingen:canvasY 32.0 ; 
     191 *     ] ; 
     192 *     patch:remove [ 
     193 *         eg:name "Old name" ;            # Remove specific value 
     194 *         ingen:canvasX patch:wildcard ;  # Remove all 
     195 *         ingen:canvasY patch:wildcard ;  # Remove all 
     196 *     ] . 
     197 * @endcode 
     198 */ 
    144199void 
    145200AtomWriter::delta(const Raul::URI&            uri, 
     
    168223} 
    169224 
     225/** @page protocol 
     226 * @subsection Copy 
     227 * 
     228 * Use [patch:Copy](http://lv2plug.in/ns/ext/copy#Copy) to copy an object from 
     229 * its current location (subject) to another (destination). 
     230 * 
     231 * If both the subject and destination are inside Ingen, like block paths, then the old object 
     232 * is copied by, for example, creating a new plugin instance. 
     233 * 
     234 * If the subject is a path and the destination is inside Ingen, then the 
     235 * subject must be an Ingen graph file or bundle, which is loaded to the 
     236 * specified destination path. 
     237 * 
     238 * If the subject is inside Ingen and the destination is a path, then the 
     239 * subject is saved to an Ingen bundle at the given destination. 
     240 * 
     241 * @code{.ttl} 
     242 * [] 
     243 *     a patch:Copy ; 
     244 *     patch:subject </graph/osc> ; 
     245 *     patch:destination </graph/osc2> . 
     246 * @endcode 
     247 */ 
    170248void 
    171249AtomWriter::copy(const Raul::URI& old_uri, 
     
    182260} 
    183261 
     262/** @page protocol 
     263 * @subsection Move 
     264 * 
     265 * Use [patch:Move](http://lv2plug.in/ns/ext/move#Move) to move an object from 
     266 * its current location (subject) to another (destination). 
     267 * 
     268 * Both subject and destination must be paths in Ingen with the same parent, 
     269 * moving between graphs is currently not supported. 
     270 * 
     271 * @code{.ttl} 
     272 * [] 
     273 *     a patch:Move ; 
     274 *     patch:subject </graph/osc> ; 
     275 *     patch:destination </graph/osc2> . 
     276 * @endcode 
     277 */ 
    184278void 
    185279AtomWriter::move(const Raul::Path& old_path, 
     
    196290} 
    197291 
     292/** @page protocol 
     293 * @subsection Delete 
     294 * 
     295 * Use [patch:Delete](http://lv2plug.in/ns/ext/delete#Delete) to remove an 
     296 * object from the engine and destroy it. 
     297 * 
     298 * All properties of the object are lost, as are all references to the object 
     299 * (e.g. any connections to it). 
     300 * 
     301 * @code{.ttl} 
     302 * [] 
     303 *     a patch:Delete ; 
     304 *     patch:subject </graph/osc> . 
     305 * @endcode 
     306 */ 
    198307void 
    199308AtomWriter::del(const Raul::URI& uri) 
     
    207316} 
    208317 
     318/** @page protocol 
     319 * @subsection Set 
     320 * 
     321 * Use [patch:Set](http://lv2plug.in/ns/ext/patch#Set) to set a property on an 
     322 * object.  Any existing value for that property is removed. 
     323 * 
     324 * @code{.ttl} 
     325 * [] 
     326 *     a patch:Set ; 
     327 *     patch:subject </graph/osc> ; 
     328 *     patch:property lv2:name ; 
     329 *     patch:value "Oscwellator" . 
     330 * @endcode 
     331 */ 
     332void 
     333AtomWriter::set_property(const Raul::URI& subject, 
     334                         const Raul::URI& predicate, 
     335                         const Atom&      value) 
     336{ 
     337    LV2_Atom_Forge_Frame msg; 
     338    forge_request(&msg, _uris.patch_Set); 
     339    lv2_atom_forge_key(&_forge, _uris.patch_subject); 
     340    forge_uri(subject); 
     341    lv2_atom_forge_key(&_forge, _uris.patch_property); 
     342    lv2_atom_forge_urid(&_forge, _map.map_uri(predicate.c_str())); 
     343    lv2_atom_forge_key(&_forge, _uris.patch_value); 
     344    lv2_atom_forge_atom(&_forge, value.size(), value.type()); 
     345    lv2_atom_forge_write(&_forge, value.get_body(), value.size()); 
     346 
     347    lv2_atom_forge_pop(&_forge, &msg); 
     348    finish_msg(); 
     349} 
     350 
     351/** @page protocol 
     352 * @subsection Get 
     353 * 
     354 * Use [patch:Get](http://lv2plug.in/ns/ext/patch#Get) to get the description 
     355 * of the subject. 
     356 * 
     357 * @code{.ttl} 
     358 * [] 
     359 *     a patch:Get ; 
     360 *     patch:subject </graph/osc> . 
     361 * @endcode 
     362 */ 
     363void 
     364AtomWriter::get(const Raul::URI& uri) 
     365{ 
     366    LV2_Atom_Forge_Frame msg; 
     367    forge_request(&msg, _uris.patch_Get); 
     368    lv2_atom_forge_key(&_forge, _uris.patch_subject); 
     369    forge_uri(uri); 
     370    lv2_atom_forge_pop(&_forge, &msg); 
     371    finish_msg(); 
     372} 
     373 
     374/** @page protocol 
     375 * 
     376 * @section arcs Arc Manipulation 
     377 */ 
     378 
     379/** @page protocol 
     380 * @subsection Connect Connecting Two Ports 
     381 * 
     382 * Ports are connected by putting an arc with the desired tail (an output port) 
     383 * and head (an input port).  The tail and head must both be within the 
     384 * subject, which must be a graph. 
     385 * 
     386 * @code{.ttl} 
     387 * [] 
     388 *     a patch:Put ; 
     389 *     patch:subject </graph/> ; 
     390 *     patch:body [ 
     391 *         a ingen:Arc ; 
     392 *         ingen:tail </graph/osc/out> ; 
     393 *         ingen:head </graph/filt/in> ; 
     394 *     ] . 
     395 * @endcode 
     396 */ 
    209397void 
    210398AtomWriter::connect(const Raul::Path& tail, 
     
    221409} 
    222410 
     411/** @page protocol 
     412 * @subsection Disconnect Disconnecting Two Ports 
     413 * 
     414 * Ports are disconnected by deleting the arc between them.  The description of 
     415 * the arc is the same as in the put command used to create the connection. 
     416 * 
     417 * @code{.ttl} 
     418 * [] 
     419 *     a patch:Delete ; 
     420 *     patch:body [ 
     421 *         a ingen:Arc ; 
     422 *         ingen:tail </graph/osc/out> ; 
     423 *         ingen:head </graph/filt/in> ; 
     424 *     ] . 
     425 * @endcode 
     426 */ 
    223427void 
    224428AtomWriter::disconnect(const Raul::Path& tail, 
     
    233437} 
    234438 
     439/** @page protocol 
     440 * @subsection DisconnectAll Fully Disconnecting an Object 
     441 * 
     442 * Disconnect a port completely is similar to disconnecting a specific port, 
     443 * but rather than specifying a specific tail and head, the special property 
     444 * ingen:incidentTo is used to specify any arc that is connected to a port or 
     445 * block in either direction.  This works with ports and blocks (including 
     446 * graphs, which act as blocks for the purpose of this operation and are not 
     447 * modified internally). 
     448 * 
     449 * @code{.ttl} 
     450 * [] 
     451 *     a patch:Delete ; 
     452 *     patch:subject </graph> ; 
     453 *     patch:body [ 
     454 *         a ingen:Arc ; 
     455 *         ingen:incidentTo </graph/osc/out> 
     456 *     ] . 
     457 * @endcode 
     458 */ 
    235459void 
    236460AtomWriter::disconnect_all(const Raul::Path& graph, 
     
    255479 
    256480void 
    257 AtomWriter::set_property(const Raul::URI& subject, 
    258                          const Raul::URI& predicate, 
    259                          const Atom&      value) 
    260 { 
    261     LV2_Atom_Forge_Frame msg; 
    262     forge_request(&msg, _uris.patch_Set); 
    263     lv2_atom_forge_key(&_forge, _uris.patch_subject); 
    264     forge_uri(subject); 
    265     lv2_atom_forge_key(&_forge, _uris.patch_property); 
    266     lv2_atom_forge_urid(&_forge, _map.map_uri(predicate.c_str())); 
    267     lv2_atom_forge_key(&_forge, _uris.patch_value); 
    268     lv2_atom_forge_atom(&_forge, value.size(), value.type()); 
    269     lv2_atom_forge_write(&_forge, value.get_body(), value.size()); 
    270  
    271     lv2_atom_forge_pop(&_forge, &msg); 
    272     finish_msg(); 
    273 } 
    274  
    275 void 
    276481AtomWriter::set_response_id(int32_t id) 
    277482{ 
     
    279484} 
    280485 
    281 void 
    282 AtomWriter::get(const Raul::URI& uri) 
    283 { 
    284     LV2_Atom_Forge_Frame msg; 
    285     forge_request(&msg, _uris.patch_Get); 
    286     lv2_atom_forge_key(&_forge, _uris.patch_subject); 
    287     forge_uri(uri); 
    288     lv2_atom_forge_pop(&_forge, &msg); 
    289     finish_msg(); 
    290 } 
    291  
     486 
     487/** @page protocol 
     488 * @section Responses 
     489 * 
     490 * Ingen responds to requests if the patch:sequenceNumber property is set.  For 
     491 * example: 
     492 * @code{.ttl} 
     493 * [] 
     494 *     a patch:Get ; 
     495 *     patch:sequenceNumber 42 ; 
     496 *     patch:subject </graph/osc> . 
     497 * @endcode 
     498 * 
     499 * Might receive a response like: 
     500 * @code{.ttl} 
     501 * [] 
     502 *     a patch:Response ; 
     503 *     patch:sequenceNumber 42 ; 
     504 *     patch:subject </graph/osc> ; 
     505 *     patch:body 0 . 
     506 * @endcode 
     507 * 
     508 * Where 0 is a status code, 0 meaning success and any other value being an 
     509 * error.  Information about status codes, including error message strings, 
     510 * are defined in ingen.lv2/errors.ttl. 
     511 * 
     512 * Note that a response is only a status response, operations that manipulate 
     513 * the graph may generate new data on the stream, e.g. the above get request 
     514 * would also receive a put that describes /graph/osc in the stream immediately 
     515 * following the response. 
     516 */ 
    292517void 
    293518AtomWriter::response(int32_t id, Status status, const std::string& subject) 
     
    299524    LV2_Atom_Forge_Frame msg; 
    300525    forge_request(&msg, _uris.patch_Response); 
    301     lv2_atom_forge_key(&_forge, _uris.patch_request); 
     526    lv2_atom_forge_key(&_forge, _uris.patch_sequenceNumber); 
    302527    lv2_atom_forge_int(&_forge, id); 
    303528    if (!subject.empty() && Raul::URI::is_valid(subject)) { 
     
    316541} 
    317542 
     543/** @page protocol 
     544 * @tableofcontents 
     545 */ 
     546 
    318547} // namespace Ingen 
  • src/URIs.cpp

    r732bfb33 ra742608  
    161161    , patch_property        (forge, map, lworld, LV2_PATCH__property) 
    162162    , patch_remove          (forge, map, lworld, LV2_PATCH__remove) 
    163     , patch_request         (forge, map, lworld, LV2_PATCH__request) 
    164163    , patch_sequenceNumber  (forge, map, lworld, LV2_PATCH__sequenceNumber) 
    165164    , patch_subject         (forge, map, lworld, LV2_PATCH__subject) 
  • src/server/NodeImpl.hpp

    rdd79e76 ra742608  
    8484    /** Apply a new (external) polyphony value. 
    8585     * 
    86      * Audio thread. 
    87      * 
     86     * \param context Process context (process thread only). 
    8887     * \param poly Must be <= the most recent value passed to prepare_poly. 
    8988     * \param maid Any objects no longer needed will be pushed to this 
  • src/server/events/Copy.hpp

    r6b199af ra742608  
    3434namespace Events { 
    3535 
    36 /** \page methods 
    37  * <h2>COPY</h2> 
    38  * As per WebDAV (RFC4918 S9.8). 
    39  * 
    40  * Copy an object from its current location and insert it at a new location 
    41  * in a single operation. 
    42  */ 
    43  
    44 /** COPY a graph object to a new path (see \ref methods). 
     36/** Copy a graph object to a new path. 
    4537 * \ingroup engine 
    4638 */ 
  • src/server/events/Delete.hpp

    r707c59c ra742608  
    4141class DisconnectAll; 
    4242 
    43 /** \page methods 
    44  * <h2>DELETE</h2> 
    45  * As per WebDAV (RFC4918 S9.6). 
    46  * 
    47  * Remove an object from the engine and destroy it. 
    48  * 
    49  * \li All properties of the object are lost 
    50  * \li All references to the object are lost (e.g. the parent's reference to 
    51  *     this child is lost, any connections to the object are removed, etc.) 
    52  */ 
    53  
    54 /** DELETE a graph object (see \ref methods). 
     43/** Delete a graph object. 
    5544 * \ingroup engine 
    5645 */ 
  • src/server/events/Delta.hpp

    rdd79e76 ra742608  
    4242 
    4343namespace Events { 
    44  
    45 /** \page methods 
    46  * <h2>POST</h2> 
    47  * As per HTTP (RFC2616 S9.5). 
    48  * 
    49  * Append properties to a graph object. 
    50  * 
    51  * An object can have several properties with a single predicate. 
    52  * POST appends properties without modifying or removing existing properties. 
    53  */ 
    54  
    55 /** \page methods 
    56  * <h2>PUT</h2> 
    57  * As per HTTP (RFC2616 S9.6). 
    58  * 
    59  * Set properties of a graph object, or create an object. 
    60  * 
    61  * An object can have several properties with a single predicate. 
    62  * \li If the object does not yet exist, the message must contain sufficient 
    63  * information to create the object (e.g. known rdf:type properties, etc.) 
    64  * \li If the object does exist, a PUT removes all existing object properties 
    65  * with predicates that match any property in the message, then adds all 
    66  * properties from the message. 
    67  */ 
    6844 
    6945class SetPortValue; 
  • src/server/events/Move.hpp

    r3353177 ra742608  
    3131namespace Events { 
    3232 
    33 /** \page methods 
    34  * <h2>MOVE</h2> 
    35  * As per WebDAV (RFC4918 S9.9). 
    36  * 
    37  * Move an object from its current location and insert it at a new location 
    38  * in a single operation. 
    39  * 
    40  * MOVE to a path with a different parent is currently not supported. 
    41  */ 
    42  
    43 /** MOVE a graph object to a new path (see \ref methods). 
     33/** Move a graph object to a new path. 
    4434 * \ingroup engine 
    4535 */ 
Note: See TracChangeset for help on using the changeset viewer.