Proposal for OpenSound Control Specification AmendmentFirst Draft, April 7 2005, Richard Healy0.0 IntroductionThis is a proposal for amendment to the OSC specification. The proposed amendment provides a mechanism to uniquely identify OSC Message(s) using a new OSC data type OSC ID and suggests a mechanism based on the proposed OSC ID to allow OSC Servers to return data to OSC Clients using formatted query and reply messages. 1.0 The OSC IDIt is proposed that a new definition "OSC ID" be added to the OSC specification. Its purpose is to uniquely identify any OSC Message.
OSC ID {
OSC String OSCIDTag;
OSC Address Pattern OSCIDAddressPattern;
}
The OSC ID consists of two fields "OSCIDTag" and "OSCIDAddressPattern". OSCIDAddressPattern consists of three forward slash deliniated subfields "OSCIDServerID", "OSCIDClientID" and "OSCIDReturnID." An OSC ID consisting of just the OSCIDServerID/OSCIDClientID subfields is referred to as an "OSC ID Pair." Example of an OSC ID with the OSCIDTag and OSCIDServerID of 1, OSCIDClientID of 2 and an OSCIDReturnID of three: #id[0x00]/1/2/3[0x0000] Example of an OSC ID Pair with an OSCIDServerID of 1 and an OSCIDClientID of 2: #id[0x00]/1/2[0x00000000]
OSCIDTag Field
OSCIDAddressPattern Field
OSCIDServerID Subfield
OSCIDClientID Subfield
OSCIDReturnID Subfield 1.1 Insuring OSC ID UniquenessIt is necessary to insure OSC ID uniqueness by several means. First, uniqueness is insured by a proposed means of incrementing the OSC ID fields. Second, uniqueness is insured by proposed means for an OSC Client to request a unique OSCIDServerID from an OSC Server. Third, uniqueness is insured by a set of rules governing the returns made by the OSC Methods associated with an OSC ID Pair. 1.1.1 IncrementingTo insure OSC ID uniqueness each subfield in the OSCIDAddressPattern (OSCIDServerID, OSCIDClientID, OSCIDReturnID) should be incremented in a predictable way. It is proposed that the subfield string be treated as a number represented by a block of bytes terminated by a null (ASCII 0) or forward slash (ASCII 47 or '/'). A single byte integer value must be within the range of allowed OSC ASCII character values. Incrementing a byte will step the byte through the range. The left most byte is least significant. Carries occur to the right. The number size and what occurs when the maximum size is exceeded is implementation specific. The implementation is required to insure uniqueness at all times even when the OSC ID data type maximum has been exceeded. 1.1.2 OSC ID Uniqueness Between Client and ServerIn order to insure a unique id some sort of synchronization between the OSC Server and the OSC Client is necessary. This is accomplished through a client query to the server for a unique OSCIDServerID. The server returns a unique OSCIDServerID value to the client. In all subsequent OSC ID(s) sent by the client the client must initialize the OSCIDServerID subfield of the OSC ID with the identifier returned by the server. The OSCIDClientID field's value must be unique for each OSC ID sent using the given OSCIDServerID. 1.1.3 Defining a ReturnA return is defined as a block of bytes an OSC Method wishes to be made available to a requesting OSC Client. Each return is issued a unique OSC ID consisting of the original OSC ID Pair identifing the OSC Message responsible for invoking the method plus an OSCIDReturnID unique to the OSC ID Pair. 1.1.4 OSC ID Uniqueness Among Returns and Return AtomicityIt is possible that an OSC Address Pattern containing regular expressions will match to several OSC Methods, some of which may return data. In order to uniquely identify each return belonging to an OSC ID Pair the OSC Server assigns unique values to each return's OSCIDReturnID. To insure predicatability the OSC Server increments the OSCIDReturnID for each return containing the same OSC ID Pair. In this way the OSC Client is guaranteed that it can retrieve multiple returns for a given OSC ID Pair in a predictable fashion by beginning at the lowest value (ASCII 32 or '!') and incrementing. Example showing the OSC ID of three returns resulting from an OSC Message with an OSC ID Pair of /a/b and an OSC Address Pattern matching three methods which returned data. Note that the space (ASCII 32)and hash (ASCII 35 or '#') characters have been skipped in the sequence: /a/b/! /a/b/" /a/b/$ All returns with the same OSC ID Pair are atomic. The deletion of an individual return is prohibited. Only deletions of all returns associated with an OSC ID Pair or all returns associated with a single OSCIDServerID are allowed. 1.2 OSC ID In The OSC MessageThe OSC ID is put before the OSC Address Pattern in an OSC Message. The OSC ID is optional and only necessary if the client wishes to uniquely identify the OSC Message. The OSCIDReturnID field is ignored. Example OSC Message with an OSC ID Pair of /1/2, an OSC Address Pattern of /a/b/c invoking method c with no arguments: #id[0x00]/1/2[0x00000000]/a/b/c[0x0000],[0x000000] Example OSC Message with an OSC ID of /1/2/3 an OSC Address Pattern of /a/b/c invoking method c with no arguments. The OSCIDreturnID subfield of '3' is ignored:
#id[0x00]/1/2/3[0x0000]/a/b/c[0x0000],[0x000000] 2.0 OSC ID and Return Mechanism SuggestionsThe following is a suggested way of implementing the OSC ID and Return Mechanism. It is proposed here not as a specific amendment but only as a beginning for discussion and to better illustrate the goals of this proposal. The OSC Client must be able to signal to the OSC Server that it is requesting information about a return or the actual return. This could be implemented as a series of transactions between an OSC Server and an OSC Client or as invocation of methods in the OSC Address Space. 2.1 Using the OSC Address Space To Store ReturnsThe OSC ID scheme was designed to store returns easily within the OSC Address Space. The OSCIDServerID and OSCIDClientID fields correspond to nesting containers and the OSCIDReturnID field corresponds to an OSC Method holding the return data. Example of an OSC Address Space listing representing a group of returns having a root container of "return" an OSCIDServerID container of "a" and OSCIDClientID(s) of a, b and c respectively. Notice that /return/a/b/ has three OSCIDReturnID methods ! " and $ which are sequential and adhere to the permitted OSC Characters: /return/a/a/! /return/a/b/! /return/a/b/" /return/a/b/$ /return/a/c/! 2.2 Methods Posting Return DataThe OSC implementation must provide some way for a method to post return data. This is the function prototype given by the OSC-Kit in the header file NetworkReturnAddress.h:
Boolean NetworkSendReturnMessage(NetworkReturnAddressPtr addr,
int n,
void *buf);
The OSC-Kit return mechanism allows the transport layer to identify the source of each incoming OSC Packet. Since an OSC Packet may contain multiple OSC Messages it can not be reasonably expected that the transport layer will be able to keep track of returns from each OSC Method invocation. A suggestion is to add the following function:
int OSCReturnPost(OSCReturnMethodInfoPtr preturn,
int buf_sz;
void *buf);
Which has the effect of posting buf_sz bytes of return data stored in pbuf associated with the OSC ID Pair contained in the OSCReturnMethodInfoPtr for later OSC Client retrieval. 2.3 Using the OSC Return Message To Return DataThe return mechanism could be implemented as a series of transactions between OSC Client and OSC Server. All transactions have a Client Query and a Server Reply. Queries and Replies use a standard message format in the form of an "OSC Return Message".
OSC Return Message {
char Tag[8];
OSC ID Id;
OSC Int iReply;
}
Example of an OSC Return Message containing the retget function an OSC ID of /1/2/3 and an iReply of 0:
#retget[0x00]#id[0x00]/1/2/3[0x0000][0x00000000]
Tag Field
Id Field
iReply Field 2.4 Client Query and Server ReplyThis section proposes a set of unique messages to implement the Return Communication scheme. Client Queries and Server Replies are of type OSC Return Message. About iReply: In all of the Client Query messages the iReply field is reserved for use by the transport. For example, it was found that to reliably implement UDP it was necessary to communicate the port number of the listening client connection to the server via the iReply field. In another example it is thought that transport mechanisms may be required to append transport specific data to the message. In such a case the iReply field could be used to store the size of appended data in bytes. 2.4.1 uidget MessageThe uidget message is used by the OSC Client to request a unique server identifier.
Client Query Fields: #uidget[0x00]#id[0x00]/[0x000000][0x00000000]
Server Reply Fields: Example of a reply containing the server id of "1" and an iReply of 4 showing that the server allows four bytes for each OSC ID Tag subfield: #uidget[0x00]#id[0x00]/1[0x0000][0x00000004] 2.4.2 retget MessageThe retget message is used by the OSC Client to request return data associated with an OSC ID Tag. Return data is appended to the end of the reply sent by the OSC Server.
Client Query Fields: #retget[0x00]#id[0x00]/1/2/3[0x0000][0x00000000]
Server Reply Fields: Example of a reply containing 4 bytes of return data consisting of [0x12345678]: #retget[0x00]#id[0x00]/1/2/3[0x0000][0x00000004][0x12345678] 2.4.3 retdel MessageThe retdel message is used by the OSC Client to request the deletion by the server of return data associated with an OSC ID consisting of an OSC ID Pair or just the OSCServerID. The OSCIDReturnID if present is ignored.
Client Query Fields: Example query requesting that the server delete all the returns associated with OSC Pair /1/2: #retdel[0x00]#id[0x00]/1/2[0x00000000][0x00000000] Example query requesting that the server delete all the returns associated with OSCIDServerID /1: #retdel[0x00]#id[0x00]/1[0x0000][0x00000000]
Server Reply Fields: Example reply confirming that all returns associated with OSC ID Pair /1/2 have been deleted: #retdel[0x00]#id[0x00]/1/2[0x00000000][0x00000000] Example reply confirming that all returns associated with OSCIDServerID /1 have been deleted: #retdel[0x00]#id[0x00]/1[0x0000][0x00000000] 2.4.4 retsz MessageThe retsz message is used by the OSC Client to request the size in bytes of the return data associated with a complete OSC ID Tag which contains OSCIDServerID, OSCClientID and OSCReturnID fields.
Client Query Fields: Example of a retsz message querying for the size of the return data associated with OSC ID /1/2/3: #retsz[0x0000]#id[0x00]/1/2/3[0x0000][0x00000000]
Server Reply Fields: Example of a reply with 4 in the iReply field indicating that the return data matching the sent unique id has a size of 4 bytes: #retsz[0x0000]#id[0x00]/1/2/3[0x0000][0x00000004] 2.4.5 retnum MessageThe retnum message is used by the OSC Client to request the number of return entries associated with just the OSC ID Pair. The OSCIDReturnID field if present is ignored.
Client Query Fields: Example of a retnum message querying for the number of returns associated with /1/2: #retnum[0x0000]#id[0x00]/1/2[0x00000000][0x00000000]
Server Reply Fields: Example of a retnum reply indicating that the matching OSC ID pair /1/2 has 4 returns: #retnum[0x0000]#id[0x00]/1/2[0x00000000][0x00000004] 2.5 Using OSC Methods in the OSC Address Space To Return DataThe functionality of all the unique messages defined in 2.4 could be implemented as a series of methods in the OSC Address Space whose arguments correspond to the OSC Return Message Tag, ID and iReply fields. Example of an OSC Address Space listing showing return functionality: /bin/ /bin/uidget /bin/return/ /bin/return/retget /bin/return/retdel /bin/return/retsz /bin/return/retnum /bin/return/post 3.0 ReferencesWright, M. (2002). OpenSound Control Specification Version 1.0. Wright, M. (1998). http://cnmat.berkeley.edu/OpenSoundControl/src/OSC-Kit/NetworkReturnAddress.h
|