Diffusion C API  6.4.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
diffusion-recordv2-mutable-record-model.h File Reference

Copyright © 2018 Push Technology Ltd., All Rights Reserved. More...

Typedefs

typedef struct
DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T 
DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T
 Opaque recordv2 mutable record model data type.
 

Functions

bool diffusion_recordv2_mutable_record_model_as_value (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, DIFFUSION_VALUE_T **value, DIFFUSION_API_ERROR *error)
 Creates an immutable DIFFUSION_VALUE_T generated from the model. More...
 
bool diffusion_recordv2_mutable_record_model_field_count (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, const char *record_name, int record_index, const char *field_name, int *field_count, DIFFUSION_API_ERROR *error)
 Returns the actual number of occurrences of a named field within a specified record occurrences. More...
 
bool diffusion_recordv2_mutable_record_model_get_field_value_with_key (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, const char *key, char **field_value, DIFFUSION_API_ERROR *error)
 Get a field value. More...
 
bool diffusion_recordv2_mutable_record_model_get_field_value (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, const char *record_name, int record_index, const char *field_name, int field_index, char **field_value, DIFFUSION_API_ERROR *error)
 Get a field value. More...
 
bool diffusion_recordv2_mutable_record_model_record_count (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, const char *record_name, int *record_count, DIFFUSION_API_ERROR *error)
 Returns the actual number of occurrences of a named record. More...
 
bool diffusion_recordv2_mutable_record_model_add_values (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, char **values, DIFFUSION_API_ERROR *error)
 Adds new values to the end of a variable length field list. More...
 
bool diffusion_recordv2_mutable_record_model_add_values_to_record (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, const char *record_name, int record_index, char **values, DIFFUSION_API_ERROR *error)
 Adds new values to the end of a variable length field list. More...
 
bool diffusion_recordv2_mutable_record_model_add_record (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, DIFFUSION_API_ERROR *error)
 Adds a new initialized record occurrence to the end of a variable multiplicity record list. More...
 
bool diffusion_recordv2_mutable_record_model_clear_variable_fields (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, const char *record_name, int record_index, DIFFUSION_API_ERROR *error)
 Remove all optional instances of a variable multiplicity field. More...
 
bool diffusion_recordv2_mutable_record_model_clear_variable_records (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, DIFFUSION_API_ERROR *error)
 Removes all optional instances of a variable multiplicity record. More...
 
bool diffusion_recordv2_mutable_record_model_remove_field (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, const char *record_name, int record_index, int field_index, DIFFUSION_API_ERROR *error)
 Removes the specified occurrence of a variable multiplicity field. More...
 
bool diffusion_recordv2_mutable_record_model_remove_record (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, int index, DIFFUSION_API_ERROR *error)
 Removes the specified occurrence of a variable multiplicity record. More...
 
bool diffusion_recordv2_mutable_record_model_set_field_value (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, const char *record_name, int record_index, const char *field_name, int field_index, const char *value, DIFFUSION_API_ERROR *error)
 Sets a specified field value. More...
 
bool diffusion_recordv2_mutable_record_model_set_field_value_with_key (const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model, const char *key, const char *value, DIFFUSION_API_ERROR *error)
 Sets a specified field value. More...
 
void diffusion_recordv2_mutable_record_model_free (DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T *mutable_record_model)
 Free a mutable recordv2 model. More...
 

Detailed Description

Copyright © 2018 Push Technology Ltd., All Rights Reserved.

Use is subject to license terms.

NOTICE: All information contained herein is, and remains the property of Push Technology. The intellectual and technical concepts contained herein are proprietary to Push Technology and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law.

This is a mutable data model of RecordV2 DIFFUSION_VALUE_T data based upon a DIFFUSION_RECORDV2_SCHEMA_T.

An initial version of such a model can be created from a schema using the diffusion_recordv2_schema_create_mutable_model function. A model created in this way will have all mandatory fields set to default values.

The model may then be updated as required and then at any time a pointer DIFFUSION_VALUE_T struct can be generated from the current state using the diffusion_recordv2_mutable_record_model_as_value function. The DIFFUSION_VALUE_T pointer may then be used to update a topic, by retrieving its bytes values using diffusion_value_get_raw_bytes. The supplied bytes can then be written into a BUF_T with write_diffusion_recordv2_value ready to be used in an update.

Function Documentation

bool diffusion_recordv2_mutable_record_model_add_record ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
DIFFUSION_API_ERROR error 
)

Adds a new initialized record occurrence to the end of a variable multiplicity record list.

As the only variable multiplicity record can be the last one there is no need to name the record. This method will add to the list of occurrences of the last defined record. The record will be initialized with default values appropriate to the schema definition and may then have individual field items set separately.

Parameters
mutable_record_modelthe mutable record model
errorpopulated if an error occurs. Can be NULL.
Returns
true if the record was successfully added to the mutable record model. False otherwise.
bool diffusion_recordv2_mutable_record_model_add_values ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
char **  values,
DIFFUSION_API_ERROR error 
)

Adds new values to the end of a variable length field list.

This is a convenience method for adding to the end of the last record and is therefore useful when there is only one record type.

Parameters
mutable_record_modelthe mutable record model value a NULL terminated array of values to be added
errorpopulated if an error occurs. Can be NULL.
Returns
true if the values were successfully added to the mutable record model. False otherwise.
bool diffusion_recordv2_mutable_record_model_add_values_to_record ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
const char *  record_name,
int  record_index,
char **  values,
DIFFUSION_API_ERROR error 
)

Adds new values to the end of a variable length field list.

This can only be used for a variable multiplicity field which can only be the last field in a record and therefore the field does not need to be named.

Parameters
mutable_record_modelthe mutable record model
record_namethe name of the record to add values to
record_indexthe record's index
valuesa NULL terminated array of values to be added
errorpopulated if an error occurs. Can be NULL.
Returns
true if the values were successfully added to the record within the mutable record model. False otherwise.
bool diffusion_recordv2_mutable_record_model_as_value ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
DIFFUSION_VALUE_T **  value,
DIFFUSION_API_ERROR error 
)

Creates an immutable DIFFUSION_VALUE_T generated from the model.

Parameters
mutable_record_modelthe mutable record model to generate the value from
valuepointer to a pointer which will have its value set to the DIFFUSION_VALUE_T
errorpopulated if an error occurs. Can be NULL.
Returns
true if the mutable record model was transformed into a DIFFUSION_VALUE_T. False otherwise.
bool diffusion_recordv2_mutable_record_model_clear_variable_fields ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
const char *  record_name,
int  record_index,
DIFFUSION_API_ERROR error 
)

Remove all optional instances of a variable multiplicity field.

As a variable repeating field can only be the last or only field within a record then the field name does not need to be specified. This will only remove field occurrences down to the minimum number of occurrences specified by the schema. If the last or only field within the record is not defined as variable multiplicity, this would have no effect.

Parameters
mutable_record_modelthe mutable record model
record_namethe name of the record
record_indexthe record's index
errorpopulated if an error occurs. Can be NULL.
Returns
true if the variable fields in the mutable record model were cleared. False otherwise.
bool diffusion_recordv2_mutable_record_model_clear_variable_records ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
DIFFUSION_API_ERROR error 
)

Removes all optional instances of a variable multiplicity record.

As a variable repeating record can only be the last or only record then the record name does not need to be specified. This will only remove record occurrences down to the minimum number of occurrences specified by the schema. If the last or only record is not defined as variable multiplicity, this would have no effect.

Parameters
mutable_record_modelthe mutable record model
errorpopulated if an error occurs. Can be NULL.
Returns
true if the variable records in the mutable record model were cleared. False otherwise.
bool diffusion_recordv2_mutable_record_model_field_count ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
const char *  record_name,
int  record_index,
const char *  field_name,
int *  field_count,
DIFFUSION_API_ERROR error 
)

Returns the actual number of occurrences of a named field within a specified record occurrences.

For all but variable fields this simply returns the schema defined number of occurrences of the field.

Parameters
mutable_record_modelthe mutable record model to retrieve the field count from
record_namethe record's name
record_indexthe record index
field_namethe field name
field_countpointer to a variable which will have its value set to the field count
errorpopulated if an error occurs. Can be NULL.
Returns
true if the mutable record model's field count was successfully retrieved. False otherwise.
void diffusion_recordv2_mutable_record_model_free ( DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model)

Free a mutable recordv2 model.

Parameters
mutable_record_modelmutable record model to be freed
bool diffusion_recordv2_mutable_record_model_get_field_value ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
const char *  record_name,
int  record_index,
const char *  field_name,
int  field_index,
char **  field_value,
DIFFUSION_API_ERROR error 
)

Get a field value.

Parameters
mutable_record_modelthe mutable record model
record_namethe record name
record_indexthe record index
field_namethe field name
field_indexthe field index
field_valuepointer to a variable which will have its value set to the field value. Must be freed after use.
errorpopulated if an error occurs. Can be NULL.
Returns
true if the mutable record model's field value was successfully retrieved. False otherwise.
bool diffusion_recordv2_mutable_record_model_get_field_value_with_key ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
const char *  key,
char **  field_value,
DIFFUSION_API_ERROR error 
)

Get a field value.

This allows an item to be addressed using a key of the form recordName(recordIndex).fieldName(fieldIndex). Indexes may be omitted in which case 0 is assumed. The record part may also be omitted in which case the first occurrence of the first record is assumed.

Parameters
mutable_record_modelthe mutable record model to retrieve the field value from
keythe key
field_valuepointer to the field_value variable which will have its value set to the field value.
errorpopulated if an error occurs. Can be NULL.
Returns
true if the mutable record model's field value was successfully retrieved. False otherwise.
bool diffusion_recordv2_mutable_record_model_record_count ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
const char *  record_name,
int *  record_count,
DIFFUSION_API_ERROR error 
)

Returns the actual number of occurrences of a named record.

If the record is not variable, this is the same as the defined number of occurrences in the schema.

Parameters
mutable_record_modelthe mutable record model
record_namethe record name
record_countpointer to a variable which will have its value set to the record count.
errorpopulated if an error occurs. Can be NULL.
Returns
true if the mutable record model's record count was successfully retrieved. False otherwise.
bool diffusion_recordv2_mutable_record_model_remove_field ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
const char *  record_name,
int  record_index,
int  field_index,
DIFFUSION_API_ERROR error 
)

Removes the specified occurrence of a variable multiplicity field.

A variable multiplicity field must be the last or only field within a record and therefore the field name is not required.

Parameters
mutable_record_modelthe mutable record model
record_namethe name of the record
record_indexthe record's index
field_indexthe field's index
errorpopulated if an error occurs. Can be NULL.
Returns
true if the field within the record in the mutable record model was removed. False otherwise.
bool diffusion_recordv2_mutable_record_model_remove_record ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
int  index,
DIFFUSION_API_ERROR error 
)

Removes the specified occurrence of a variable multiplicity record.

A variable multiplicity record must be the last or only record within a schema and therefore the record name is not required.

Parameters
mutable_record_modelthe mutable record model
errorpopulated if an error occurs. Can be NULL.
Returns
true if the record in the mutable record model were cleared. False otherwise.
bool diffusion_recordv2_mutable_record_model_set_field_value ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
const char *  record_name,
int  record_index,
const char *  field_name,
int  field_index,
const char *  value,
DIFFUSION_API_ERROR error 
)

Sets a specified field value.

Parameters
mutable_record_modelthe mutable record model
record_namethe name of the record
record_indexthe record's index
field_namethe name of the field
field_indexthe field's index
valuethe value to set the field to
errorpopulated if an error occurs. Can be NULL.
Returns
true if the field in the mutable record model has been set. False otherwise.
bool diffusion_recordv2_mutable_record_model_set_field_value_with_key ( const DIFFUSION_RECORDV2_MUTABLE_RECORD_MODEL_T mutable_record_model,
const char *  key,
const char *  value,
DIFFUSION_API_ERROR error 
)

Sets a specified field value.

This allows an item to be addressed using a key of the form recordName(recordIndex).fieldName(fieldIndex). Indexes may be omitted in which case 0 is assumed. The record part may also be omitted in which case the first occurrence of the first record is assumed.

Parameters
mutable_record_modelthe mutable record model
key
valuethe value to set the field to
errorpopulated if an error occurs. Can be NULL.
Returns
true if the field in the mutable record model has been set. False otherwise.