Diff: mbedOSC.h

Revision:

1:ab7dc9550de6

Parent:

0:49cdaebd52d5

Child:

2:acfd0090c8e7

--- a/mbedOSC.h	Tue Mar 13 22:42:25 2012 +0000
+++ b/mbedOSC.h	Sun Apr 15 12:06:01 2012 +0000
@@ -75,50 +75,170 @@
         Host host; 
     
     public:
-    
+        /** A container for an OSC message to receive or send */
         OSCMessage();
-    
-        const IpAddr& getIp();    // return IpAddr object
-        const int&     getPort(); // return port
+
+        /** Return the IpAddr object */   
+        const IpAddr& getIp();
+        /** Return the port */
+        const int&     getPort();
     
-        //ex. address patern "/adr/test"
-        //    address[2]={"/ard" , "/test"}
+/*
+ Gets the address string of the OSC message
+ param [in] <-- _index is the index of the address string (byte)
+ return pointer of the address string (char *)
+ @note ex. "/ard/test"<br>
+ getAddress(0) = "/ard"<br>
+ getAddress(1) = "/test"
+ @attention It is maximum number of the addresses is 2<br>
+ In this case "/ard/test1/test2"<br>
+ ignore it after "/test2"
+ */
         char        *getAddress(uint8_t _index);    //retturn address
+        
+/*
+ Gets the TopAddress string of the OSC message (this is just the address with index 0)
+ param[in] None
+ return pointer of the TopAddress string (char *), i.e. address[0]
+ Example: In the case "/ard/test", getTopAddress() = "/ard" (WITH the slash "/") 
+ *//*
+ Gets the TopAddress string of the OSC message (this is just the address with index 0)
+ param[in] None
+ return pointer of the TopAddress string (char *), i.e. address[0]
+ Example: In the case "/ard/test", getTopAddress() = "/ard" (WITH the slash "/") 
+ */        
         char        *getTopAddress();    //return address[0] :"/ard"
+
+/*
+ Gets the "SubAddress" string of the OSC message (this is just the address with index 1)
+ param[in] None
+ return pointer of the SubAddress string (char *), i.e. address[1]
+ Example: in the case "/ard/test", getSubAddress() = "/test" (WITH the slash "/") 
+ */
         char        *getSubAddress();    //return address[1] :"/test"
+
+/*
+ Gets the number of the OSC message address
+ param[in] None
+ return number of the OSC message address (byte)
+ Examples: "/ard"      --> the number of the addresses is 1
+           "/ard/test" --> the number of the addresses is 2
+ Attention: the maximum number of addresses is 2 (MAX_ADDRESS)
+*/
         uint8_t         getAddressNum();    //return 2        
     
-        // 'i': long(int32_t)
-        // 'f': double
-        //ex 'if' 123 54.21
+/*
+ Gets the TypeTag string (with index) of the OSC message
+ param[in] <--_index is the index of the TypeTag string (byte)
+ return: TypeTag char (char)
+ Example: in the case of a total typetag string equal to "if", getTypeTag(0) = 'i' and getTypeTag(1) = 'f'
+ Attention: MAX_ARG is maximum number of the args, if the index argument is larger, it will be constrained to this max. 
+ */
         char         getTypeTag(uint8_t _index);    //_index=0 ->'i'
                                                     //_index=1 ->'f'
 
+/*
+ Gets the number of the OSC message args
+ param[in] None
+ return number of the args (byte)
+ Example: "i" 123 --> number of the OSC message args is 1
+          "if" 123 54.24 --> number of the OSC message args is 2
+ Attention: the maximum number of args is 2 (MAX_ARG)
+ */
         uint8_t         getArgNum();    //return 2
     
+/*
+ Get the args of the OSC message with an integer value
+ param[in] <--_index is (an int, or uint8_t), corresponding to the index of the args (byte)
+ return: integer value (long, or int32_t)
+ Example: in the case "if" 123 54.24, getArgInt(0) = 123
+ Noe: "i" is integer, but the return type is "long"
+ Note: When a index is bigger than the number of the args, it is set to the number of the args
+ */
         int32_t         getArgInt(uint8_t _index);        //_index=0 -> 123
+
+/*
+ Get the args of the OSC message with a float value
+ param[in] <--_index is the index of the args
+ return: float value (double)
+ note: In this case "if" 123 54.24, getArgFloat(1) = 54.24
+ attention: arg declared as float, but return value cast as "double"
+ attention: When index is bigger than the number of the args, it is set to the number of the args
+ */
         double         getArgFloat(uint8_t _index);    //_index=1 -> 54.21
     
     
+/*
+ Set TopAddress string of OSC Message 
+ param[in] <-- _address is a string pointer for the TopAddress String (char *). NOTE: is this a good idea? why not pass as const, and do allocation here?
+ return: None
+ Example: if the complete address string is "/ard/test", we set the topaddress as follows: char top[]="/ard" (allocation done here!), then setTopAddress(top)
+ */
         void setTopAddress(char *_address);        //set address[0]
+
+/*
+ Set SubAddress string of the OSC Message
+ param[in] <-- _address is a string pointer for the SubAddress String (char *)
+ return: None
+ Example:  if the complete address string is "/ard/test", we set the subaddress as follows: char sub[]="/test" (allocation done here!), then setSubAddress(sub)
+ Attention: we should call first setTopAddress, and then setSubAddress. The order is important. This does not seems like a good idea...
+ */
         void setSubAddress(char *_address);        //set address[1]
+
+/*
+ Set the complete Address string of the OSC Message (top and sub addresses)
+ param[in] <-- _topAddress and _subAddress are the string pointers to top and sub addresses (char *)
+ return: None
+ Example: in the case "/ard/test", we need to do: char top[]="/ard", char sub[]="/test", and then setAddress(top,sub)
+ Reminder: in this implementation, the maximum number of addresses is MAX_ADDRESS=2
+ */
         void setAddress(char *_topAddress,     
                         char *_subAddress);
+
+/*
+ Set address string using index (here 0 or 1)
+ Example: "/ard/test", char adr[]="/ard", setAddress(0,adr), char adr2[]="/test", setAddress(1,adr)
+ */
         void setAddress(uint8_t _index,        //set 0,address[0]
                         char *_address);    
                                             //set 1,address[1]
-    
+
+/*
+ Set IP Address of the OSC Message (for SENDING messages - for receiving this will be done when receiving something ) 
+ param[in] <-- _ip pointer of IP Address array (byte *)
+ Example: IP=192.168.0.99, then we have to do: ip[]={192,168,0,1}, then setIp(ip)
+ */    
         void setIp( uint8_t *_ip );    //set ip
-    
+
+/*!
+ Set IP Address to the OSC Message container (not through pointer)
+ Example: IP=192.168.0.99 => setIp(192,168,0,99)
+ */    
         void setIp(uint8_t _ip1,    //set(192,
                    uint8_t _ip2,    //      168,
                    uint8_t _ip3,    //    0,
                    uint8_t _ip4);    //    100)
-    
+
+        /*
+         Set PortNo for the OSC Message
+         @param[in] _port PortNo (unsigned int)
+         @return None
+         */
         void setPort( uint16_t _port );
     
-        //ex. long   v1=100
-        //    double v2=123.21
+/*
+ Set TypeTag and args to the OSC Message container
+ @param[in] types TypeTag string "i"(integer) or"f"(float) (char *)
+ @param[in] ... Pointer of the Args(variable argument) ..
+ @return None
+ @Example: 
+ (1) integer 123: (NOTE: integers are LONG)
+ long v1=123; sendMes.setArgs("i",&v1)
+ (2)integer:123 and float:52.14
+ long v1=123; double v2=52.14; sendMes.setArgs("if",&v1,&v2)
+ Attention: in this implementation, the maximum number of the args is 2
+ (if setArgs("iff",&v1,&v2,&v3), data is ignored after &v3)
+ */
         void setArgs( char *types , ... );    //set ("if",&v1,&v2)
     
         friend class OSCClass;
@@ -149,25 +269,64 @@
 
 public:
     
+    /** Wraps the UDP functions to send and receive OSC messages */
     OSCClass();
+    
+/*
+ This sets "binds" the received message to the receiver container of the communication object
+ @param[in]<--_mes is a pointer to the "receiveing" OSC message (OSCMessage *)
+ */
     OSCClass(OSCMessage *_mes); // set the receiver message container
+
+/*
+ Ignore: See messageReceivedCallback instead. This is called by the UDPSocket... and should be a protected function and we friend UDPSocket?
+ */
     void onUDPSocketEvent(UDPSocketEvent e);
         
-    //init osc 
+/*
+ This initializes the OSC communication object with default receiving port (DEFAULT_REC_PORT)
+ param[in]: None
+ return: None
+ */
     void begin();
+
+/*
+ Initialize an OSC object with arbitrary listening port
+ param[in] <-- _recievePort, is the listening ("receiving") Port No (unsigned int)
+ return: None
+ */
     void begin(uint16_t _recievePort);
+
+/*
+ Stop OSC communication (in fact, only the receiver - the server side)
+ */
     void stop();
     
     //new OSC data in the receiver message container: 
     bool newMessage;
 
+/*
+ Set a OSC receive message container
+ param[in] _mes Pointer to the OSC receive message container (OSCMessage *)
+ return None
+ */
     void setReceiveMessage( OSCMessage *_mes ); //set receive OSCmessage container (note: the message has a "host" object from which we get the upd packets)
+
+/*
+ Get the received OSC message (note: this is another way to access the message directly from the OSCClass object).
+ The advantage is that we will signal that we read the message, and will be able to query if a NEW message arrived
+ (Alternatively, one could have a function pointer to pass to the OSC object, that will be called each time a new packet is received: TO DO) 
+ */
     OSCMessage    *getMessage();    //return received OSCmessage    
 
     //buffer clear
     //void flush();    
     
-    //OSC send
+/*
+ Send an OSC Message (message contain the host ip and port where the message data has to be sent)
+ param[in] _mes Pointer to the OSC message container (OSCMessage *)
+ return None
+ */
     void sendOsc( OSCMessage *_mes ); //set&send OSCmessage (note: it will be sent to the host defined in the message container)
 
     //to be set by host program, will be called on receipt of an OSC message