Subject: Element Properties

From: "Joel M. Halpern" <[email-masked]>
Date: Mon, 28 Mar 2005 11:26:19 -0500

As suggested on the list before the meeting, and discussed at the meeting, 
I think it may make sense to provide explicit mechanisms in the model and 
protocol for referencing the properties of any element of any LFB.

The basic approach would be to include in the core library a data 
definition for the scalar for access (none, read-only, write-only, and 
read-write is what I would start with.)
Then, we would define a structure to be returned for a properties reference 
to any element in the model.  A property reference would be indicated by 
setting a bit in the path flags that reference the element.

At the moment, I can see two structure definitions.  One for most elements 
which only contains the access permissions, and one for arrays which 
contains other array properties.  I have included the XML declarations for 
all of this at the end of this message.

There are a number of open questions:

1) What should we use for the properties of a structure?  We could just 
return the permissions, which would relate to the structure as a whole.  We 
could try to return a complex structure with the permissions for the struct 
and the permissions for every element within the structure.  I am inclined 
to keep this simple, but the result is that if one needs the element 
properties one has to GET a number of pieces of information.

2) What should we use for the properties of an LFB?  (This would be 
reference by a path with the properties flag set and 0 identifiers in the 
path ids.)  Should it reference just the LFB?  Should it try to return the 
properties for every top level element in the LFB?

3) What about Aliases?  All the other properties are read only.  It is very 
tempting to put the Alias target information into the alias properties 
structure (much as the array information is in the array properties 
structure.)  The one aspect that gives me pause in doing that is that we 
would have to allow SET operations against Alias properties to make this 
work.  Is that a good idea?

4) As a minor aspect, if we have nested path-data TLVs how should the 
property flag be set and interpreted?  My inclination is to say that the 
flag only applies to paths which do not have nested path-data.

For completeness, the XML:

<dataTypeDefs>
   <dataTypeDef>
     <name> elementAccessScalar </name>
     <synopsis> scalar of access permission values </synopsis>
     <atomic>
       <baseType> uchar </baseType>
       <specialValues>
         <specialValue value="0">
           <name> no-access </name>
           <synopsis> no access is permitted </synopsis>
         </specialValue>
         <specialValue value="2">
           <name> read-only </name>
           <synopsis> read access is permitted </synopsis>
         </specialValue>
         <specialValue value="2">
           <name> write-only </name>
           <synopsis> write access is permitted </synopsis>
         </specialValue>
         <specialValue value="3">
           <name> read-write </name>
           <synopsis> read and write access is permitted </synopsis>
         </specialValue>
       </specialValues>
     </atomic>
   </dataTypeDef>

   <dataTypeDef>
     <name> BasicElementProperties </name>
     <synopsis> the structure for most element properties </name>
     <struct>
       <element>
         <elementID> 1 </elementID>
         <name> access-permissions </name>
         <synopsis> what access is permitted to the referenced element 
</synopsis>
         <typeRef> elementAccessScalar </typeRef>
       </element>
     </struct>
   </dataTypeDef>

   <dataTypeDef>
     <name> ArrayElementProperties </name>
     <synopsis> the additional properties for an array element </name>
     <struct>
       <derived-from> BasicElementProperties </dervice-from>
       <element>
         <elementID> 2 </elementID>
         <name> first-used-index </name>
         <synopsis> index of the first used array element </synposis>
         <typeRef> uint32 </typeRef>
       </element>
       <element>
         <elementID> 3 </elementID>
         <name> first-unused-index </name>
         <synopsis> index of the first available array element </synposis>
         <typeRef> uint32 </typeRef>
       </element>
       <element>
         <elementID> 4 </elementID>
         <name> last-used-index </name>
         <synopsis> index of the last used array element </synposis>
         <typeRef> uint32 </typeRef>
       </element>
        <element>
         <elementID> 5 </elementID>
         <name> used-entry-count </name>
         <synopsis> number of entries used in the array element </synposis>
         <typeRef> uint32 </typeRef>
       </element>
    </struct>
   </dataTypeDef>

Yours,
Joel M. Halpern

PS: I have moved derived-from and element-ID to nested elements instead of 
attributes because that seems the most consistent with the advice I could 
get from the application folks.  I still should talk to Scott Hollenbeck to 
really understand this.