From d324f4f532093ac6acce78da6d53601b7818ac4e Mon Sep 17 00:00:00 2001 From: Guobao Shen Date: Sun, 4 Nov 2012 09:23:32 -0500 Subject: [PATCH] fix API interface definition, and revise documentation. --- documentation/ntCPP.html | 92 +++++++++++++++++----------------------- src/nt/ntnameValue.h | 12 +++--- src/nt/nttable.cpp | 4 +- src/nt/nttable.h | 14 +++--- 4 files changed, 54 insertions(+), 68 deletions(-) diff --git a/documentation/ntCPP.html b/documentation/ntCPP.html index cfe2da5..b0f8ed5 100644 --- a/documentation/ntCPP.html +++ b/documentation/ntCPP.html @@ -19,19 +19,25 @@ -

EPICS pvDataCPP
-2012.01.11

+

EPICS normative type C++ implementation +

-

TODO

- +

Draft, 4-Nov-2012

+
+
This version:
+
ntCPP.html
+
Editors:
+
Guobao Shen, BNL
+ Marty Kraimer, BNL
+
+

Normative Types

-

This section describes the C++ implemmentation of normative types.

+

This section describes the C++ implemmentation of normative types. Two (2) helper classes are implemented, +ntNameValue and NTTable respectively.

Normative Type Fields.

@@ -40,42 +46,23 @@ There is a single instance of this class, which is obtained via NTField::get(). 

class NTField: NoDefaultMethods {
 public:
-    static NTField * get();
+    static NTFieldPtr get();
     ~NTField() {}
-    bool isEnumerated(FieldConstPtr field);
-    bool isTimeStamp(FieldConstPtr field);
-    bool isAlarm(FieldConstPtr field);
-    bool isDisplay(FieldConstPtr field);
-    bool isAlarmLimit(FieldConstPtr field);
-    bool isControl(FieldConstPtr field);
 
-    StructureConstPtr createEnumerated(String fieldName);
-    StructureConstPtr createTimeStamp();
-    StructureConstPtr createAlarm();
-    StructureConstPtr createDisplay();
-    StructureConstPtr createAlarmLimit();
-    StructureConstPtr createControl();
+    PVStructurePtr createEnumerated(StringArray const & choices);
+    PVStructurePtr createTimeStamp();
+    PVStructurePtr createAlarm();
+    PVStructurePtr createDisplay();
+    PVStructurePtr createAlarmLimit();
+    PVStructurePtr createControl();
 
-    StructureArrayConstPtr createEnumeratedArray(String fieldName);
-    StructureArrayConstPtr createTimeStampArray(String fieldName);
-    StructureArrayConstPtr createAlarmArray(String fieldName);
+    PVStructureArrayPtr createEnumeratedArray();
+    PVStructureArrayPtr createTimeStampArray();
+    PVStructureArrayPtr createAlarmArray();
 };

where

-
isEnumerated
-
Is this field an enumerated structure, i. e. a structure that has a int - field named index and a string array field named choices.
-
isTimeStamp
-
Is this field a timeStamp structure.
-
isAlarm
-
Is this field an alarm structure..
-
isDisplay
-
Is the field a display structure.
-
isAlarmLimit
-
Is the field an alarm limit structure.
-
isControl
-
Is the field a control structure.
createEnumerated
Create an introspection interface for an enumerated structure.
createTimeStamp
@@ -105,19 +92,20 @@ public: 
class NTNameValue : private NoDefaultMethods
 {
 public:
-    static bool isNTNameValue(PVStructurePtr pvStructure);
-    static PVStructure::shared_pointer create(
+    static bool isNTNameValue(PVStructurePtr const & pvStructure);
+    static NTNameValuePtr create(
         bool hasFunction,bool hasTimeStamp, bool hasAlarm);
-    NTNameValue(PVStructure::shared_pointer const & pvStructure);
+    static NTNameValuePtr create(
+        PVStructurePtr const & pvStructure);
     ~NTNameValue();
-    PVString* getFunction();
+    PVStringPtr getFunction();
     void attachTimeStamp(PVTimeStamp &pvTimeStamp);
     void attachAlarm(PVAlarm &pvAlarm);
     PVStructurePtr getPVStructure();
     PVStructurePtr getTimeStamp();
     PVStructurePtr getAlarm();
-    PVStringArray *getNames();
-    PVStringArray *getValues();
+    PVStringArrayPtr getNames();
+    PVStringArrayPtr getValues();
 };

where

@@ -126,9 +114,6 @@ public:
Is the structure a NTNameValue structure?
create
Create an NTNameValue that has the associated fields.
-
NTNameValue
-
The constructor. The pvStructure must be a NTNameValue - structure.
~NTNameValue
The destructor.
getFunction
@@ -156,21 +141,25 @@ public: 
class NTTable: private NoDefaultMethods
 {
 public:
-    static bool isNTTable(PVStructurePtr pvStructure);
+    static bool isNTTable(PVStructurePtr const & pvStructure);
     static PVStructure::shared_pointer create(
         bool hasFunction,bool hasTimeStamp, bool hasAlarm,
         int numberValues,
         FieldConstPtrArray valueFields);
-    NTTable(PVStructure::shared_pointer const & pvStructure);
+        static NTTablePtr create(
+            bool hasFunction,bool hasTimeStamp, bool hasAlarm,
+            StringArray const & valueNames,
+            FieldConstPtrArray const &valueFields);
+        static NTTablePtr clone(PVStructurePtr const &);
     ~NTTable();
-    PVString *getFunction();
+    PVStringPtr getFunction();
     void attachTimeStamp(PVTimeStamp &pvTimeStamp);
     void attachAlarm(PVAlarm &pvAlarm);
     PVStructurePtr getPVStructure();
     PVStructurePtr getTimeStamp();
     PVStructurePtr getAlarm();
-    PVStringArray *getLabel();
-    int getNumberValues();
+    PVStringArrayPtr getLabel();
+    size_t getNumberValues();
     FieldConstPtr getField(int index);
     PVFieldPtr getPVField(int index);
 };
@@ -181,9 +170,6 @@ public:
y
create
Create an NTTable that has the associated fields.
-
NTTable
-
The constructor. The pvStructure must be a NTTable - structure.
~NTTable
The destructor.
getFunction
diff --git a/src/nt/ntnameValue.h b/src/nt/ntnameValue.h index 632c40c..790292d 100644 --- a/src/nt/ntnameValue.h +++ b/src/nt/ntnameValue.h @@ -49,7 +49,7 @@ public: * Get the function field. * @return The pvString or null if no function field. */ - PVStringPtr & getFunction() {return pvFunction;} + PVStringPtr getFunction() {return pvFunction;} /** * Attach a pvTimeStamp. * @param pvTimeStamp The pvTimeStamp that will be attached. @@ -66,27 +66,27 @@ public: * Get the pvStructure. * @return PVStructurePtr. */ - PVStructurePtr & getPVStructure(){return pvNTNameValue;} + PVStructurePtr getPVStructure(){return pvNTNameValue;} /** * Get the timeStamp. * @return PVStructurePtr which may be null. */ - PVStructurePtr & getTimeStamp(){return pvTimeStamp;} + PVStructurePtr getTimeStamp(){return pvTimeStamp;} /** * Get the alarm. * @return PVStructurePtr which may be null. */ - PVStructurePtr & getAlarm() {return pvAlarm;} + PVStructurePtr getAlarm() {return pvAlarm;} /** * Get the string array on names. * @return The array of names. */ - PVStringArrayPtr & getNames() {return pvNames;} + PVStringArrayPtr getNames() {return pvNames;} /** * Get the string array on values. * @return The array of values. */ - PVStringArrayPtr & getValues() {return pvValues;} + PVStringArrayPtr getValues() {return pvValues;} private: NTNameValue(PVStructurePtr const & pvStructure); PVStructurePtr pvNTNameValue; diff --git a/src/nt/nttable.cpp b/src/nt/nttable.cpp index 638163b..308990b 100644 --- a/src/nt/nttable.cpp +++ b/src/nt/nttable.cpp @@ -136,13 +136,13 @@ size_t NTTable::getNumberValues() return pvLabel->getLength(); } -FieldConstPtr & NTTable::getField(size_t index) +FieldConstPtr NTTable::getField(size_t index) { FieldConstPtrArray fields = pvNTTable->getStructure()->getFields(); return fields[index + offsetFields]; } -PVFieldPtr & NTTable::getPVField(size_t index) +PVFieldPtr NTTable::getPVField(size_t index) { PVFieldPtrArray pvFields = pvNTTable->getPVFields(); return pvFields[index+offsetFields]; diff --git a/src/nt/nttable.h b/src/nt/nttable.h index 69b2fa1..683463d 100644 --- a/src/nt/nttable.h +++ b/src/nt/nttable.h @@ -52,7 +52,7 @@ public: * Get the function field. * @return The pvString or null if no function field. */ - PVStringPtr & getFunction() {return pvFunction;} + PVStringPtr getFunction() {return pvFunction;} /** * Attach a pvTimeStamp. * @param pvTimeStamp The pvTimeStamp that will be attached. @@ -69,22 +69,22 @@ public: * Get the pvStructure. * @return PVStructurePtr. */ - PVStructurePtr & getPVStructure(){return pvNTTable;} + PVStructurePtr getPVStructure(){return pvNTTable;} /** * Get the timeStamp. * @return PVStructurePtr which may be null. */ - PVStructurePtr & getTimeStamp(){return pvTimeStamp;} + PVStructurePtr getTimeStamp(){return pvTimeStamp;} /** * Get the alarm. * @return PVStructurePtr which may be null. */ - PVStructurePtr & getAlarm() {return pvAlarm;} + PVStructurePtr getAlarm() {return pvAlarm;} /** * Get the label field. * @return The pvStringArray for the label. */ - PVStringArrayPtr & getLabel() {return pvLabel;} + PVStringArrayPtr getLabel() {return pvLabel;} /** * Get the the number of fields that follow the label field. * @return The number of fields. @@ -95,13 +95,13 @@ public: * @param index The index of the field desired. * @return The FieldConstPtr for the field. */ - FieldConstPtr & getField(size_t index); + FieldConstPtr getField(size_t index); /** * Get the PVField for a field that follows the label field. * @param index The index of the field desired. * @return The PVFieldPtr for the field. */ - PVFieldPtr & getPVField(size_t index); + PVFieldPtr getPVField(size_t index); private: NTTable(PVStructurePtr const & pvStructure); PVStructurePtr pvNTTable;