propman.h

Open DMT Client C Source code

utBool propSetAltBuffer(Key_t key, void *buf, int bufLen);

// Name:
//   Return a point to the location where the specified property value is stored.
// Description:
//   This function will return a pointer to the buffer used to store data for this
//   property.  The capacity of the buffer will be placed in 'maxLen'.
// Return:
//   A pointer and length of the property storage area if the key is valid, null otherwise.
void *propGetPointer(Key_t key, UInt16 *maxLen, UInt16 *dtaLen);

// Name:
//   Set a callback function for the setting or getting of property values.
// Description:
//   This function allows inserting a call-back function which will be called just
//   before a property value is retrieved, or just after a property value is set.
//   The 'mode' argument is a simple bitmask where 0x1 specifies that the function
//   is to be called for property 'Get' operations just before the property is
//   retrieved, 0x2 specifies that the function is to be called for property 'Set'
//   operations just after the property is set.  This allows refreshing the value
//   of a property (such as the system time, etc.) just before the property value
//   is passed to the server, or setting other internal client state when the server
//   sets a specific property.
// Return:
//   void
void propSetNotifyFtn(PropertyRefresh_t mode, void (*ftn)(PropertyRefresh_t,Key_t,UInt8*,int));

// Name:
//   Set a callback function for execution of a command
// Description:
//   This function specifies the call-back function for the various 'command' type
//   properties.  The specified function will be called when the corresponding
//   command property is 'set'.
// Return:
//   utTrue if the key is valid, false otherwise.
utBool propSetCommandFtn(Key_t key, CommandError_t (*cmd)(int pi, Key_t key, const UInt8 *data, int dataLen));

// Name:
//   Return a pointer to the KeyValue_t entry
// Description:
//   These functions return a pointer to the KeyValue_t entry for the specified key
//   (propGetKeyValueEntry), or for the specified index (propGetKeyValueAt).
KeyValue_t *propGetKeyValueEntry(Key_t key);
KeyValue_t *propGetKeyValueEntryByName(const char *keyName);
KeyValue_t *propGetKeyValueAt(int ndx);

// Name:
//   Get maximum number of indexed fields in property
// Description:
//   Returns the maximum number of indexed fields available in the property.
// Return:
//   The maximum number of indexed items in the specified property, or -1 if the
//   property key was not found.
Int16 propGetIndexSize(Key_t key);

// Name:
//   Get/Set binary encoded property values.
// Description:
//   These functions are for setting/getting byte arrays based on the data type
//   and are designed specifically for the protocol property payload.
//   These functions obey the KVA_READONLY/KVA_WRITEONLY attributes
// Return:
//   Values >=0 indicates the number of bytes used from the buffer for the
//   'propSetValueCmd' function, or the number of bytes placed into the buffer for the
//   'propGetValue' function.  Values <0 indicate an error, which will match one
//   of the errors listed in the PME_xxxx defines.
PropertyError_t propSetValueCmd(int pi, Key_t key, const UInt8 *data, int dataLen);
PropertyError_t propSetValueFromString(Key_t key, const char *s);  /* EXPERIMENTAL */
PropertyError_t propGetValue(Key_t key, UInt8 *data, int dataLen);

PropertyError_t propGetPropertyPacket(int protoNdx, Packet_t *pkt, Key_t key, UInt8 *args, int argLen);
// Name:
//   Get/Set integer value
// Description:
//   These functions are for getting/setting 32-bit integers from within code
//   These functions DO NOT obey the KVA_READONLY/KVA_WRITEONLY attributes
// Return:
//   propGetUInt32AtIndex & propGetUInt32 return the integer value of the property,
//   or the default 'dft' value if the key is not found, or the property value is
//   empty, or if an error occurs.  propSetUInt32AtIndex, propAddUInt32AtIndex,
//   propSetUInt32, and propAddUInt32 return utTrue if the operation was successful,
//   and utFalse otherwise.  propAddUInt32AtIndex returns the updated value back
//   into location pointed to by 'val'.
UInt32 propGetUInt32AtIndex(Key_t key, int ndx, UInt32 dft);
utBool propSetUInt32AtIndex(Key_t key, int ndx, UInt32 val);
utBool propSetUInt32AtIndexRefresh(Key_t key, int ndx, UInt32 val, utBool refresh);
utBool propAddUInt32AtIndex(Key_t key, int ndx, UInt32 *val);
UInt32 propGetUInt32(Key_t key, UInt32 dft);
utBool propSetUInt32(Key_t key, UInt32 val);
utBool propAddUInt32(Key_t key, UInt32 val);

// Name:
//   Get/Set boolean value
// Description:
//   These functions are for getting/setting boolean values from within code.
//   These are essentially wrappers around calls retrieving integers with a 
//   case to 'utBool'.  
//   These functions DO NOT obey the KVA_READONLY/KVA_WRITEONLY attributes
// Return:
//   These functions return utTrue if the operation was successful, utFalse otherwise.
utBool propGetBooleanAtIndex(Key_t key, int ndx, utBool dft);
utBool propSetBooleanAtIndex(Key_t key, int ndx, utBool val);
utBool propGetBoolean(Key_t key, utBool dft);
utBool propSetBoolean(Key_t key, utBool val);

// Name:
//   Get/Set double value
// Description:
//   These functions are for getting/setting double values from within code.
//   These are essentially wrappers around calls retrieving integers, with a 
//   fixed decimal position and a case to a double.  
//   These functions DO NOT obey the KVA_READONLY/KVA_WRITEONLY attributes.
// Return:
//   propGetDoubleAtIndex & propGetDouble return the double value if this key
//   is valid, and the default 'dft' value otherwise.  propSetDoubleAtIndex,
//   propAddDoubleAtIndex, propSetDouble, and propAddDouble return utTrue if
//   the operation was successful, and utFalse otherwise.  propAddDoubleAtIndex
//   returns the updated value back into location pointed to by 'val'.
double propGetDoubleAtIndex(Key_t key, int ndx, double dft);
utBool propSetDoubleAtIndex(Key_t key, int ndx, double val);
utBool propAddDoubleAtIndex(Key_t key, int ndx, double *val);
double propGetDouble(Key_t key, double dft);
utBool propSetDouble(Key_t key, double val);
utBool propAddDouble(Key_t key, double val);

// Name:
//   Get/Set string value
// Description:
//   These functions are for getting/setting string values from within code.
//   These functions DO NOT obey the KVA_READONLY/KVA_WRITEONLY attributes.
// Return:
//   propGetString returns the property string value if the key is valid,
//   or the default 'dft' value otherwise.  propSetString returns utTrue if
//   the operation was successful, utFalse otherwise.
const char *propGetString(Key_t key, const char *dft);
utBool propSetString(Key_t key, const char *val);

// Name:
//   Get/Set binary value
// Description:
//   These functions are for getting/setting binary values from within code.
//   These functions DO NOT obey the KVA_READONLY/KVA_WRITEONLY attributes.
// Return:
//   propGetBinary returns the property binary value if the key is valid,
//   or the default 'dft' value otherwise.  propSetBinary returns utTrue if
//   the operation was successful, utFalse otherwise.
const UInt8 *propGetBinary(Key_t key, const UInt8 *dft, UInt16 *maxLen, UInt16 *dtaLen);
utBool propSetBinary(Key_t key, const UInt8 *val, UInt16 dtaLen);

// Name:
//   Get/Set GPS value
// Description:
//   These functions are for getting/setting GPSOdometer_t values from within code.
//   These functions DO NOT obey the KVA_READONLY/KVA_WRITEONLY attributes.
// Return:
//   propGetGPS returns the property GPS value if the key is valid,
//   or the default 'dft' value otherwise.  propSetGPS returns utTrue if
//   the operation was successful, utFalse otherwise.
const GPSOdometer_t *propGetGPS(Key_t key, const GPSOdometer_t *dft);
utBool propSetGPS(Key_t key, const GPSOdometer_t *gps);

// Name:
//   Return true if properties have been changed since last save.
// Description:
//   This function indicates whether the current property values should be saved.
// Return:
//   true if at least one property has changed since last save, false otherwise.
utBool propHasChanged();

// Name:
//   Clear all property changed flags
// Description:
//   This function resets all property attributes to a "non-changed" state
void propClearChanged();

// Name:
//   Save <key>=<value> property list
// Description:
//   This function is for saving the contents of the property list to a file.
// Return:
//   true if save was successful
utBool propSaveProperties(const char *propFile, utBool all);

// Name:
//   Print <keName>=<value> property list
// Description:
//   This function is for printing the list of properties for debug purposes.
// Return:
//   true if printing was successful
utBool propPrintProperties(FILE *file, utBool all);

// Name:
//   Load <key>=<value> list
// Description:
//   This function is for loading the contents of the property list from a file.
// Return:
//   void
utBool propLoadProperties(const char *propFile, utBool showProps);

// ----------------------------------------------------------------------------

const char *propGetAccountID();
const char *propGetDeviceID(int protoNdx);

// ----------------------------------------------------------------------------

#ifdef __cplusplus
}
#endif
#endif