Changeset a742608 in ingen


Ignore:
Timestamp:
Oct 24, 2015, 7:02:45 PM (2 years ago)
Author:
David Robillard <d@…>
Branches:
groups, master, nodeless, parallel, parameters, sequencefix, tasks
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

    r557f9d42 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

    r557f9d42 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

    r557f9d42 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

    r557f9d42 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

    r557f9d42 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

    r557f9d42 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

    r557f9d42 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

    r557f9d42 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

    r557f9d42 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

    r557f9d42 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

    r557f9d42 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.