<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<?xml-stylesheet href="./_c74_ref.xsl" type="text/xsl"?>

<c74object name="ossia.client" module="Ossia" category="Ossia">

	<digest>
		Connect to a distant Ossia device
	</digest>

	<description>
		<o>ossia.client</o> allows to connect to a distant device (either locally or on another computer) through various protcols, and lets you bind to it through <o>ossia.view</o> and <o>ossia.remote</o>
	</description>

	
	<!--METADATA-->
	<metadatalist>
		<metadata name="author">Ossia</metadata>
		<metadata name="tag">Ossia</metadata>
		<metadata name="tag">Network</metadata>
	</metadatalist>

	<!--INLETS-->
	<inletlist>
			<inlet id="0" name="Message input" type="any">
			<digest>Messages to ossia.model</digest>
			<description>Messages to the node</description>
		</inlet>
	</inletlist>


	<!--OUTLETS-->
	<outletlist>
			<outlet id="0" name="Info outlet" type="any">
			<digest>Various information messages</digest>
			<description>Messages and information in reply to various messages</description>
		</outlet>
	</outletlist>

	<!--METHODS-->	
	<methodlist>
		<method name="namespace">
			<arglist/>
			<digest>
				Output list of all parameters and their current values
			</digest>
			<description>
				Sending the <m>namespace</m> message to the leftmost inlet outputs the list of all parameters registered under this node, and their current values
			</description>
		</method>

		<method name="getdevices">
			<arglist/>
			<digest>
				Get the list of all discoverable devices on the network
			</digest>
			<description>
				Sending the <m>getdevices</m> message to the leftmost inlet will print to all discoverable devices that are present on the network
			</description>
		</method>

		<method name="connect">
			<arglist/>
			<digest>
				Connect to a global device to the network
			</digest>
			<description>
				The <m>connect</m> message to the leftmost inlet will print its configuration parameters for the various available protocols
				Then, sending it with the appropriate values will connect to the appropriate device on the network, and allow it to be explored, queried and remotely-controlled.
				Notice that, if the <m>getdevices</m> message has not been sent previously, the object will internally do it, which might take some time, and delay the actual connection accordingly.
			</description>
		</method>

		<method name="disconnect">
			<arglist/>
			<digest>
				Disconnect from the currently connected remoted device
			</digest>
			<description>
				The <m>disconnect</m> message to the leftmost inlet will disconnect <o>ossia.client</o> from the currently remoted device
			</description>
		</method>

		<method name="update">
			<arglist/>
			<digest>
				Update the namespace of the remote device
			</digest>
			<description>
				For some protocols or remote devices, the remote namespace is not automatically updated. Sending the "update" message will do this.
			</description>
		</method>

		<method name="preset">
			<arglist/>
			<digest>Preset Management
			</digest>
			<description>
				Sending the <m>preset save /path/to/file.txt</m> message to the leftmost inlet will write a list of all parameters and their values to the the disk, under the file /path/to/file.txt <!-- - The preset can also be saved under a json format, by replacing the extension by .json -->
				Sending the <m>preset load /path/to/file.txt</m> message to the leftmost inlet will load a list of all parameters and their values from the the file /path/to/file.txt, and recall the values to the parameters
			</description>
		</method>
		<method name="set">
			<arglist>
				<arg name="relative node address" optional="0" type="symbol" />
				<arg name="node value" optional="0" type="any" />
			</arglist>
			<digest>Send value to distant <o>ossia.parameter</o>
			</digest>
			<description>
				The <m>set</m> message followed by a distant node address and value will set the node to the value specified as argument
			</description>
		</method>
		
	</methodlist>	
	
	
	<!--ATTRIBUTES-->
	<attributelist>

		<attribute name="description" get="1" set="1" type="atom" size="1">
			<digest>
				Descirption of this node
			</digest>
			<description>
				The <at>description</at> attribute allows to give a textual description for this node. This helps documenting the parameter.
			</description>
		</attribute>

		<attribute name="invisible" get="1" set="1" type="int" size="1">
			<digest>
				Hide device on the network
			</digest>
			<description>
				The <at>invisible</at> attribute allows to hide device on the network. Note that this attribute cannot be changed once the device has been exposed on the network
			</description>
		</attribute>
		
		<attribute name="priority" get="1" set="1" type="int" size="1">
			<digest>
				Set priority
			</digest>
			<description>
				The <at>priority</at> attribute allows to order how several values of a same hierarchical level can be recalled 
			</description>
		</attribute>
		
		<attribute name="tags" get="1" set="1" type="atom" size="1">
			<digest>
				Tags associated with this node
			</digest>
			<description>
				The <at>tags</at> attribute allows to associate a variable number of tags for this node. This helps documenting the parameter.
			</description>
		</attribute>
		
		<attribute name="trim_address" get="1" set="1" type="boolean" size="1">
			<digest>
				Output absolute or relative address path
			</digest>
			<description>
				The <a>trim_address</a> attribute sets whether the address is output as a relative or absolute path
			</description>
		</attribute>

	</attributelist>	

	<!--SEEALSO-->
	<seealsolist>
		<seealso name="ossia.device" type="refpage"/>
		<seealso name="ossia.view" type="refpage"/>
		<seealso name="ossia.remote" type="refpage"/>		
	</seealsolist>

	
</c74object>
