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

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

	<digest>
		Create a local device
	</digest>

	<description>
		ossia.device creates a local device under which all models and parameters in the same patcher or below will register. Namespace of this device can then be exposed to local or distant applications through various protocols
	</description>

	
	<!--METADATA-->
	<metadatalist>
		<metadata name="author">Ossia</metadata>
		<metadata name="tag">Ossia</metadata>
		<metadata name="tag">Network</metadata>
		<metadata name="tag">Protocol</metadata>
		<metadata name="tag">osc</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>

	<!--ARGUMENTS-->
	<objarglist>
		<objarg name="Name" optional="0" type="symbol">
			<digest>
				Name in ossia namespace
			</digest>
			<description>
				<o>ossia.device</o> requires an argument defining the device name on the network
			</description>
		</objarg>
	</objarglist>	
	
	<!--METHODS-->	
	<methodlist>

		<method name="expose">
			<arglist>
				<arg name="protocol-name" optional="1" type="list" />
			</arglist>
			<digest>
				Expose the device to the network
			</digest>
			<description>
				Sending the <m>expose</m> message without any argument will print in Max Console various protocol and configuration options available
				Sending the <m>expose</m> message followed by a protocol name will explose the device to the network using the optional configuration option (ie. network ports)
			</description>
		</method>

		<method name="name">
			<arglist>
				<arg name="device-name" optional="1" type="symbol" />
			</arglist>
			<digest>
				Set and get the global device's name
			</digest>
			<description>
				Sending the <m>name</m> message will output the current device's name out of <o>ossia.device</o> outlet
				Sending the <m>name</m> message followed by a symbol argument specifying new name will set the device's name
			</description>
		</method>

		<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 value
			</description>
		</method>
		
		<method name="preset">
			<arglist>
				<arg name="save or load" optional="0" type="symbol" />
				<arg name="path" optional="0" type="symbol" />
			</arglist>
			<digest>Save and recall presets
			</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 <o>ossia.parameter</o>
			</digest>
			<description>
				Sending the <m>set</m> message followed by a 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.model" type="refpage"/>
		<seealso name="ossia.view" type="refpage"/>
		<seealso name="ossia.client" type="refpage"/>		
	</seealsolist>

	
</c74object>
