From 9e15d7859def446fb3f66f15d3ca1cd444bbf03e Mon Sep 17 00:00:00 2001 From: David Robillard Date: Wed, 20 Apr 2011 00:59:46 +0000 Subject: Update OSC documentation. git-svn-id: http://svn.drobilla.net/lad/trunk/ingen@3176 a436a847-0d15-0410-975c-d299462d15a1 --- src/engine/OSCClientSender.cpp | 84 ++++++++++++--------- src/engine/OSCEngineReceiver.cpp | 156 +++++++++++++++++++++------------------ 2 files changed, 132 insertions(+), 108 deletions(-) (limited to 'src/engine') diff --git a/src/engine/OSCClientSender.cpp b/src/engine/OSCClientSender.cpp index 020fb922..0d3c5cf6 100644 --- a/src/engine/OSCClientSender.cpp +++ b/src/engine/OSCClientSender.cpp @@ -27,6 +27,7 @@ #include "NodeImpl.hpp" #include "OSCClientSender.hpp" #include "PatchImpl.hpp" + #include "PluginImpl.hpp" #include "PortImpl.hpp" #include "ingen/ClientInterface.hpp" @@ -38,16 +39,17 @@ using namespace Raul; namespace Ingen { namespace Engine { -/*! \page client_osc_namespace Client OSC Namespace Documentation +/** @page client_osc_namespace Client OSC Namespace Documentation * *

These are the commands the client recognizes. All monitoring of * changes in the engine happens via these commands.

*/ -/** \page client_osc_namespace +/** @page client_osc_namespace *

/ok

- * \arg \b response-id (int) - Request ID this is a response to + * @arg @p response-id :: Integer * + * @par * Successful response to some command. */ void @@ -56,17 +58,20 @@ OSCClientSender::response_ok(int32_t id) if (!_enabled) return; + + if (lo_send(_address, "/ok", "i", id, LO_ARGS_END) < 0) { Raul::error << "Unable to send OK " << id << "! (" << lo_address_errstr(_address) << ")" << endl; } } -/** \page client_osc_namespace +/** @page client_osc_namespace *

/error

- * \arg \b response-id (int) - Request ID this is a response to - * \arg \b message (string) - Error message (natural language text) + * @arg @p response-id :: Integer + * @arg @p message :: String * + * @par * Unsuccessful response to some command. */ void @@ -81,13 +86,13 @@ OSCClientSender::response_error(int32_t id, const std::string& msg) } } -/** \page client_osc_namespace +/** @page client_osc_namespace *

/error

- * \arg \b message (string) - Error message (natural language text) + * @arg @p message :: String * - * Notification that an error has occurred. - * This is for notification of errors that aren't a direct response to a - * user command, ie "unexpected" errors. + * @par + * Notification that an error has occurred. This is for notification of errors + * that aren't a direct response to a user command, i.e. "unexpected" errors. */ void OSCClientSender::error(const std::string& msg) @@ -95,14 +100,15 @@ OSCClientSender::error(const std::string& msg) send("/error", "s", msg.c_str(), LO_ARGS_END); } -/** \page client_osc_namespace +/** @page client_osc_namespace *

/put

- * \arg \b path (string) - Path of object - * \arg \b predicate - * \arg \b value - * \arg \b ... + * @arg @p path :: String + * @arg @p predicate :: URI String + * @arg @p value + * @arg @p ... * - * PUT a set of properties to a path (see \ref methods). + * @par + * PUT a set of properties to a path. */ void OSCClientSender::put(const Raul::URI& path, @@ -127,12 +133,13 @@ OSCClientSender::delta(const Raul::URI& path, warn << "FIXME: OSC DELTA" << endl; } -/** \page client_osc_namespace +/** @page client_osc_namespace *

/move

- * \arg \b old-path (string) - Old path of object - * \arg \b new-path (string) - New path of object + * @arg @p old-path :: String + * @arg @p new-path :: String * - * MOVE an object to a new path (see \ref methods). + * @par + * MOVE an object to a new path. * The new path will have the same parent as the old path. */ void @@ -141,11 +148,12 @@ OSCClientSender::move(const Path& old_path, const Path& new_path) send("/move", "ss", old_path.c_str(), new_path.c_str(), LO_ARGS_END); } -/** \page client_osc_namespace +/** @page client_osc_namespace *

/delete

- * \arg \b path (string) - Path of object (which no longer exists) + * @arg @p path :: String * - * DELETE an object (see \ref methods). + * @par + * DELETE an object. */ void OSCClientSender::del(const URI& uri) @@ -153,11 +161,12 @@ OSCClientSender::del(const URI& uri) send("/delete", "s", uri.c_str(), LO_ARGS_END); } -/** \page client_osc_namespace +/** @page client_osc_namespace *

/connect

- * \arg \b src-path (string) - Path of the source port - * \arg \b dst-path (string) - Path of the destination port + * @arg @p src-path :: String + * @arg @p dst-path :: String * + * @par * Notification a new connection has been made. */ void @@ -167,11 +176,12 @@ OSCClientSender::connect(const Path& src_port_path, send("/connect", "ss", src_port_path.c_str(), dst_port_path.c_str(), LO_ARGS_END); } -/** \page client_osc_namespace +/** @page client_osc_namespace *

/disconnect

- * \arg \b src-path (string) - Path of the source port - * \arg \b dst-path (string) - Path of the destination port + * @arg @p src-path :: String + * @arg @p dst-path :: String * + * @par * Notification a connection has been unmade. */ void @@ -181,12 +191,13 @@ OSCClientSender::disconnect(const Path& src_port_path, send("/disconnect", "ss", src_port_path.c_str(), dst_port_path.c_str(), LO_ARGS_END); } -/** \page client_osc_namespace +/** @page client_osc_namespace *

/set_property

- * \arg \b path (string) - Path of the object associated with property (node, patch, or port) - * \arg \b key (string) - * \arg \b value (string) + * @arg @p path :: String + * @arg @p key :: URI String + * @arg @p value * + * @par * Notification of a property. */ void @@ -201,10 +212,11 @@ OSCClientSender::set_property(const URI& path, send_message("/set_property", m); } -/** \page client_osc_namespace +/** @page client_osc_namespace *

/activity

- * \arg \b path (string) - Path of object + * @arg @p path :: String * + * @par * Notification of "activity" (e.g. port message blinkenlights). */ void diff --git a/src/engine/OSCEngineReceiver.cpp b/src/engine/OSCEngineReceiver.cpp index 45af1d97..fdb0bcc4 100644 --- a/src/engine/OSCEngineReceiver.cpp +++ b/src/engine/OSCEngineReceiver.cpp @@ -47,14 +47,14 @@ using namespace Raul; namespace Ingen { namespace Engine { -/*! \page engine_osc_namespace Engine OSC Namespace Documentation +/** @page engine_osc_namespace Engine OSC Namespace Documentation * *

These are the commands the engine recognizes. A client can control every * aspect of the engine entirely with these commands.

* *

All commands on this page are in the "control band". If a client needs to * know about the state of the engine, it must listen to the "notification band". - * See the "Client OSC Namespace Documentation" for details. + * See the "Client OSC Namespace Documentation" for details.

*/ OSCEngineReceiver::OSCEngineReceiver(Engine& engine, size_t queue_size, uint16_t port) @@ -237,11 +237,9 @@ OSCEngineReceiver::error_cb(int num, const char* msg, const char* path) error << " (" << msg << ")" << endl; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/ping

- * \arg \b response-id (integer) - * - * Reply to sender immediately with a successful response. + * @arg @p response-id :: Integer */ int OSCEngineReceiver::_ping_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg) @@ -252,14 +250,15 @@ OSCEngineReceiver::_ping_cb(const char* path, const char* types, lo_arg** argv, return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/ping_queued

- * \arg \b response-id (integer) + * @arg @p response-id :: Integer * - * Reply to sender with a successful response after going through the event queue. - * This is useful for checking if the engine is actually active, or for sending after - * several events as a sentinel and wait on it's response, to know when all previous - * events have finished processing. + * @par + * Reply to sender with a successful response after going through the + * event queue. This is useful for checking if the engine is actually active, + * or for sending after several events as a sentinel and wait on it's response, + * to know when all previous events have finished processing. */ int OSCEngineReceiver::_ping_slow_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg) @@ -268,13 +267,13 @@ OSCEngineReceiver::_ping_slow_cb(const char* path, const char* types, lo_arg** a return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/register_client

- * \arg \b response-id (integer) + * @arg @p response-id :: Integer * - * Register a new client with the engine. - * The incoming address will be used for the new registered client. If you - * want to register a different specific address, use the URL version. + * @par + * Register a new client with the engine. The incoming address will be + * used for the new registered client. */ int OSCEngineReceiver::_register_client_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg) @@ -291,10 +290,11 @@ OSCEngineReceiver::_register_client_cb(const char* path, const char* types, lo_a return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/unregister_client

- * \arg \b response-id (integer) + * @arg @p response-id :: Integer * + * @par * Unregister a client. */ int @@ -309,11 +309,12 @@ OSCEngineReceiver::_unregister_client_cb(const char* path, const char* types, lo return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/get

- * \arg \b response-id (integer) - * \arg \b uri (string) - URI of object (patch, port, node, plugin) to send + * @arg @p response-id :: Integer + * @arg @p uri :: URI String * + * @par * Request all properties of an object. */ int @@ -323,15 +324,16 @@ OSCEngineReceiver::_get_cb(const char* path, const char* types, lo_arg** argv, i return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/put

- * \arg \b response-id (integer) - * \arg \b path (string) - Path of object - * \arg \b predicate - * \arg \b value - * \arg \b ... + * @arg @p response-id :: Integer + * @arg @p path :: String + * @arg @p predicate :: URI String + * @arg @p value + * @arg @p ... * - * PUT a set of properties to a path (see \ref methods). + * @par + * PUT a set of properties to a path. */ int OSCEngineReceiver::_put_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg) @@ -344,13 +346,14 @@ OSCEngineReceiver::_put_cb(const char* path, const char* types, lo_arg** argv, i return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/move

- * \arg \b response-id (integer) - * \arg \b old-path - Object's path - * \arg \b new-path - Object's new path + * @arg @p response-id :: Integer + * @arg @p old-path :: String + * @arg @p new-path :: String * - * MOVE an object to a new path (see \ref methods). + * @par + * MOVE an object to a new path. */ int OSCEngineReceiver::_move_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg) @@ -362,12 +365,13 @@ OSCEngineReceiver::_move_cb(const char* path, const char* types, lo_arg** argv, return 0; } -/** \page engine_osc_namespace - *

/del

- * \arg \b response-id (integer) - * \arg \b path (string) - Full path of the object +/** @page engine_osc_namespace + *

/delete

+ * @arg @p response-id :: Integer + * @arg @p path :: String * - * DELETE an object (see \ref methods). + * @par + * DELETE an object. */ int OSCEngineReceiver::_del_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg) @@ -378,12 +382,13 @@ OSCEngineReceiver::_del_cb(const char* path, const char* types, lo_arg** argv, i return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/connect

- * \arg \b response-id (integer) - * \arg \b src-port-path (string) - Full path of source port - * \arg \b dst-port-path (string) - Full path of destination port + * @arg @p response-id :: Integer + * @arg @p src-port-path :: String + * @arg @p dst-port-path :: String * + * @par * Connect two ports (which must be in the same patch). */ int @@ -396,12 +401,13 @@ OSCEngineReceiver::_connect_cb(const char* path, const char* types, lo_arg** arg return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/disconnect

- * \arg \b response-id (integer) - * \arg \b src-port-path (string) - Full path of source port - * \arg \b dst-port-path (string) - Full path of destination port + * @arg @p response-id :: Integer + * @arg @p src-port-path :: String + * @arg @p dst-port-path :: String * + * @par * Disconnect two ports. */ int @@ -414,12 +420,13 @@ OSCEngineReceiver::_disconnect_cb(const char* path, const char* types, lo_arg** return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/disconnect_all

- * \arg \b response-id (integer) - * \arg \b patch-path (string) - The (parent) patch in which to disconnect object. - * \arg \b object-path (string) - Full path of object. + * @arg @p response-id :: Integer + * @arg @p patch-path :: String + * @arg @p object-path :: String * + * @par * Disconnect all connections to/from a node/port. */ int @@ -432,13 +439,14 @@ OSCEngineReceiver::_disconnect_all_cb(const char* path, const char* types, lo_ar return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/note_on

- * \arg \b response-id (integer) - * \arg \b node-path (string) - Patch of Node to trigger (must be a trigger or note node) - * \arg \b note-num (int) - MIDI style note number (0-127) - * \arg \b velocity (int) - MIDI style velocity (0-127) + * @arg @p response-id :: Integer + * @arg @p node-path :: String + * @arg @p note-num (int) + * @arg @p velocity (int) * + * @par * Trigger a note-on, just as if it came from MIDI. */ int @@ -454,12 +462,13 @@ OSCEngineReceiver::_note_on_cb(const char* path, const char* types, lo_arg** arg return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/note_off

- * \arg \b response-id (integer) - * \arg \b node-path (string) - Patch of Node to trigger (must be a trigger or note node) - * \arg \b note-num (int) - MIDI style note number (0-127) + * @arg @p response-id :: Integer + * @arg @p node-path :: String + * @arg @p note-num :: Integer * + * @par * Trigger a note-off, just as if it came from MIDI. */ int @@ -474,11 +483,12 @@ OSCEngineReceiver::_note_off_cb(const char* path, const char* types, lo_arg** ar return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/all_notes_off

- * \arg \b response-id (integer) - * \arg \b patch-path (string) - Patch of patch to send event to + * @arg @p response-id :: Integer + * @arg @p patch-path :: String * + * @par * Trigger a note-off for all voices, just as if it came from MIDI. */ int @@ -493,13 +503,14 @@ OSCEngineReceiver::_all_notes_off_cb(const char* path, const char* types, lo_arg return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/set_property

- * \arg \b response-id (integer) - * \arg \b object-path (string) - Full path of object to associate property with - * \arg \b key (string) - URI for predicate of this property (e.g. "http://drobilla.net/ns/ingen#enabled") - * \arg \b value (string) - Value of property + * @arg @p response-id :: Integer + * @arg @p uri :: URI String + * @arg @p key :: URI String + * @arg @p value :: String * + * @par * Set a property on a graph object. */ int @@ -517,11 +528,11 @@ OSCEngineReceiver::_set_property_cb(const char* path, const char* types, lo_arg* return 0; } -/** \page engine_osc_namespace +/** @page engine_osc_namespace *

/request_property

- * \arg \b response-id (integer) - * \arg \b uri (string) - Subject - * \arg \b key (string) - Predicate + * @arg @p response-id :: Integer + * @arg @p uri :: URI String + * @arg @p key :: URI String * * Request the value of a property on an object. */ @@ -537,6 +548,7 @@ OSCEngineReceiver::_request_property_cb(const char* path, const char* types, lo_ // Static Callbacks // + // Display incoming OSC messages (for debugging purposes) int OSCEngineReceiver::generic_cb(const char* path, const char* types, lo_arg** argv, int argc, lo_message msg, void* user_data) -- cgit v1.2.1