SolarCapture C Bindings User Guide  SF-115721-CD
Draft 2A
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
attr.h File Reference

sc_attr: Control optional behaviours and tunables. More...

Functions

int sc_attr_alloc (struct sc_attr **attr_out)
 Allocate an attribute object. More...
 
void sc_attr_free (struct sc_attr *attr)
 Free an attribute object. More...
 
void sc_attr_reset (struct sc_attr *attr)
 Return attributes to their default values. More...
 
int sc_attr_set_int (struct sc_attr *attr, const char *name, int64_t val)
 Set an attribute to an integer value. More...
 
int sc_attr_set_str (struct sc_attr *attr, const char *name, const char *val)
 Set an attribute to a string value. More...
 
int sc_attr_set_from_str (struct sc_attr *attr, const char *name, const char *val)
 Set an attribute from a string value. More...
 
int sc_attr_set_from_fmt (struct sc_attr *attr, const char *name, const char *fmt,...) __attribute__((format(printf
 Set an attribute to a string value (with formatting). More...
 
int struct sc_attrsc_attr_dup (const struct sc_attr *attr)
 Duplicate an attribute object. More...
 
int sc_attr_doc (const char *attr_name_opt, const char ***docs_out, int *docs_len_out)
 Returns documentation for attributes. Used by solar_capture_doc. More...
 
struct sc_objectsc_attr_to_object (const struct sc_attr *attr)
 Convert an sc_attr to an sc_object. More...
 
struct sc_attrsc_attr_from_object (struct sc_object *obj)
 Convert an sc_object to an sc_attr. More...
 

Detailed Description

sc_attr: Control optional behaviours and tunables.

Function Documentation

int sc_attr_alloc ( struct sc_attr **  attr_out)

Allocate an attribute object.

Parameters
attr_outThe attribute object is returned here.
Returns
0 on success, or a negative error code:
-ENOMEM if memory could not be allocated
-EINVAL if the SC_ATTR environment variable is malformed.
int sc_attr_doc ( const char *  attr_name_opt,
const char ***  docs_out,
int *  docs_len_out 
)

Returns documentation for attributes. Used by solar_capture_doc.

Parameters
attr_name_optThe attribute name.
docs_outOn success, the resulting doc string output.
docs_len_outOn success, the length of the doc string output.
Returns
0 on success, or a negative error code.
int struct sc_attr* sc_attr_dup ( const struct sc_attr attr)

Duplicate an attribute object.

Parameters
attrThe attribute object.
Returns
A new attribute object.

This function is useful when you want to make non-destructive changes to an existing attribute object.

void sc_attr_free ( struct sc_attr attr)

Free an attribute object.

Parameters
attrThe attribute object.
struct sc_attr* sc_attr_from_object ( struct sc_object obj)

Convert an sc_object to an sc_attr.

Parameters
objAn sc_object instance or NULL
Returns
NULL if obj is NULL otherwise the sc_attr.

Also returns NULL if obj is not of type SC_OBJ_C_ATTR.

void sc_attr_reset ( struct sc_attr attr)

Return attributes to their default values.

Parameters
attrThe attribute object.
int sc_attr_set_from_fmt ( struct sc_attr attr,
const char *  name,
const char *  fmt,
  ... 
)

Set an attribute to a string value (with formatting).

Parameters
attrThe attribute object.
nameName of the attribute.
fmtFormat string for the new attribute value.
Returns
0 on success, or a negative error code:
-ENOENT if name is not a valid attribute name
-EINVAL if it is not possible to convert val to a valid value for the attribute -EOVERFLOW if val is not within the range of values this attribute can take.

This function behaves exactly as sc_attr_set_from_str(), except that the string value is generated from a printf()-style format string.

int sc_attr_set_from_str ( struct sc_attr attr,
const char *  name,
const char *  val 
)

Set an attribute from a string value.

Parameters
attrThe attribute object.
nameName of the attribute.
valNew value for the attribute.
Returns
0 on success, or a negative error code:
-ENOENT if name is not a valid attribute name
-EINVAL if it is not possible to convert val to a valid value for the attribute -EOVERFLOW if val is not within the range of values this attribute can take.
int sc_attr_set_int ( struct sc_attr attr,
const char *  name,
int64_t  val 
)

Set an attribute to an integer value.

Parameters
attrThe attribute object.
nameName of the attribute.
valNew value for the attribute.
Returns
0 on success, or a negative error code:
-ENOENT if name is not a valid attribute name
-EOVERFLOW if val is not within the range of values this attribute can take.
int sc_attr_set_str ( struct sc_attr attr,
const char *  name,
const char *  val 
)

Set an attribute to a string value.

Parameters
attrThe attribute object.
nameName of the attribute.
valNew value for the attribute (may be NULL).
Returns
0 on success, or a negative error code:
-ENOENT if name is not a valid attribute name
-ENOMSG if the attribute is not a string attribute.
struct sc_object* sc_attr_to_object ( const struct sc_attr attr)

Convert an sc_attr to an sc_object.

Parameters
attrAn sc_attr instance or NULL
Returns
NULL if attr is NULL otherwise the sc_object.