GnomeDbParameter

GnomeDbParameter — Represents a GdaValue with various attributes

Synopsis




            GnomeDbParameter;
GType       gnome_db_parameter_get_type     (void);
GObject*    gnome_db_parameter_new          (GnomeDbDict *dict,
                                             GnomeDbServerDataType *type);
GObject*    gnome_db_parameter_new_copy     (GnomeDbParameter *orig);
GObject*    gnome_db_parameter_new_with_dest_field
                                            (GnomeDbField *field,
                                             GnomeDbServerDataType *type);
void        gnome_db_parameter_add_dest_field
                                            (GnomeDbParameter *param,
                                             GnomeDbField *field);
GSList*     gnome_db_parameter_get_dest_fields
                                            (GnomeDbParameter *param);
GnomeDbServerDataType* gnome_db_parameter_get_data_type
                                            (GnomeDbParameter *param);
const GdaValue* gnome_db_parameter_get_value
                                            (GnomeDbParameter *param);
void        gnome_db_parameter_set_value    (GnomeDbParameter *param,
                                             const GdaValue *value);
gboolean    gnome_db_parameter_set_value_str
                                            (GnomeDbParameter *param,
                                             const gchar *value);
void        gnome_db_parameter_declare_invalid
                                            (GnomeDbParameter *param);
gboolean    gnome_db_parameter_is_valid     (GnomeDbParameter *param);
const GdaValue* gnome_db_parameter_get_default_value
                                            (GnomeDbParameter *param);
void        gnome_db_parameter_set_default_value
                                            (GnomeDbParameter *param,
                                             const GdaValue *value);
void        gnome_db_parameter_set_not_null (GnomeDbParameter *param,
                                             gboolean not_null);
gboolean    gnome_db_parameter_get_not_null (GnomeDbParameter *param);
gboolean    gnome_db_parameter_set_source_field
                                            (GnomeDbParameter *param,
                                             GnomeDbField *field,
                                             GError **error);
GnomeDbField* gnome_db_parameter_get_source_field
                                            (GnomeDbParameter *param);
void        gnome_db_parameter_add_dependency
                                            (GnomeDbParameter *param,
                                             GnomeDbParameter *depend_on);
void        gnome_db_parameter_del_dependency
                                            (GnomeDbParameter *param,
                                             GnomeDbParameter *depend_on);
GSList*     gnome_db_parameter_get_dependencies
                                            (GnomeDbParameter *param);
void        gnome_db_parameter_replace_ref  (GnomeDbParameter *param,
                                             GHashTable *replacements);
void        gnome_db_parameter_bind_to_param
                                            (GnomeDbParameter *param,
                                             GnomeDbParameter *bind_to);
GnomeDbParameter* gnome_db_parameter_get_bind_param
                                            (GnomeDbParameter *param);
gboolean    gnome_db_parameter_requires_user_input
                                            (GnomeDbParameter *param);
void        gnome_db_parameter_set_user_input_required
                                            (GnomeDbParameter *param,
                                             gboolean input_required);

Object Hierarchy


  GObject
   +----GnomeDbBase
         +----GnomeDbParameter

Implemented Interfaces

GnomeDbParameter implements GnomeDbReferer.

Properties


  "full-bind"            gpointer              : Read / Write
  "handler-plugin"       gchararray            : Read / Write
  "simple-bind"          gpointer              : Read / Write
  "use-default-value"    gboolean              : Read / Write

Description

A GnomeDbParameter object basically conveys a value (as a GdaValue) and several attributes specifying the value itself.

Parameters are usually used in conjunction with the GnomeDbDataModel interface and with queries which require parameters for their execution.

Also a parameter can be set to an alias of another parameter, in which case that parameter and the one of which it is an alias will always be synchronized regarding their value and attributes. This feature is usefull when a parameter required by a query needs to be synchronized to an already existing parameter.

Details

GnomeDbParameter

typedef struct _GnomeDbParameter GnomeDbParameter;


gnome_db_parameter_get_type ()

GType       gnome_db_parameter_get_type     (void);

Returns :

gnome_db_parameter_new ()

GObject*    gnome_db_parameter_new          (GnomeDbDict *dict,
                                             GnomeDbServerDataType *type);

Creates a new parameter of type type

dict : a GnomeDbDict object
type : the GnomeDbServerDataType requested
Returns : a new GnomeDbParameter object

gnome_db_parameter_new_copy ()

GObject*    gnome_db_parameter_new_copy     (GnomeDbParameter *orig);

Copy constructor.

orig : a GnomeDbParameter object to copy
Returns : a new GnomeDbParameter object

gnome_db_parameter_new_with_dest_field ()

GObject*    gnome_db_parameter_new_with_dest_field
                                            (GnomeDbField *field,
                                             GnomeDbServerDataType *type);

Creates a new parameter to be passed to field for the operations where a parameter is required; other GnomeDbField can also be added by using the gnome_db_parameter_add_dest_field() method.

field : the GnomeDbField object the parameter is for
type : the GnomeDbServerDataType requested
Returns : a new GnomeDbParameter object

gnome_db_parameter_add_dest_field ()

void        gnome_db_parameter_add_dest_field
                                            (GnomeDbParameter *param,
                                             GnomeDbField *field);

Adds a GnomeDbField object for which the parameter is for

param : a GnomeDbParameter object
field : the GnomeDbField object the parameter is for

gnome_db_parameter_get_dest_fields ()

GSList*     gnome_db_parameter_get_dest_fields
                                            (GnomeDbParameter *param);

Get the GnomeDbField objects which created param (and which will use its value)

param : a GnomeDbParameter object
Returns : the list of GnomeDbField object; it must not be changed or free'd

gnome_db_parameter_get_data_type ()

GnomeDbServerDataType* gnome_db_parameter_get_data_type
                                            (GnomeDbParameter *param);

Get the requested data type for param.

param : a GnomeDbParameter object
Returns : the data type

gnome_db_parameter_get_value ()

const GdaValue* gnome_db_parameter_get_value
                                            (GnomeDbParameter *param);

Get the value held into the parameter

param : a GnomeDbParameter object
Returns : the value (a NULL value returns a GDA_VALUE_TYPE_NULL GdaValue)

gnome_db_parameter_set_value ()

void        gnome_db_parameter_set_value    (GnomeDbParameter *param,
                                             const GdaValue *value);

param :
value :

gnome_db_parameter_set_value_str ()

gboolean    gnome_db_parameter_set_value_str
                                            (GnomeDbParameter *param,
                                             const gchar *value);

Same function as gnome_db_parameter_set_value() except that the value is provided as a string, and may return FALSE if the string did not represent a correct value for the data type of the parameter.

param : a GnomeDbParameter object
value : a value to set the parameter to, as a string
Returns : TRUE if no error occured

gnome_db_parameter_declare_invalid ()

void        gnome_db_parameter_declare_invalid
                                            (GnomeDbParameter *param);

Forces a parameter to be invalid; to set it valid again, a new value must be assigned to it using gnome_db_parameter_set_value().

param : a GnomeDbParameter object

gnome_db_parameter_is_valid ()

gboolean    gnome_db_parameter_is_valid     (GnomeDbParameter *param);

Get the validity of param (that is, of the value held by param)

param : a GnomeDbParameter object
Returns : TRUE if param's value can safely be used

gnome_db_parameter_get_default_value ()

const GdaValue* gnome_db_parameter_get_default_value
                                            (GnomeDbParameter *param);

Get the default value held into the parameter. WARNING: the default value does not need to be of the same type as the one required by param.

param : a GnomeDbParameter object
Returns : the default value

gnome_db_parameter_set_default_value ()

void        gnome_db_parameter_set_default_value
                                            (GnomeDbParameter *param,
                                             const GdaValue *value);

param :
value :

gnome_db_parameter_set_not_null ()

void        gnome_db_parameter_set_not_null (GnomeDbParameter *param,
                                             gboolean not_null);

Sets if the parameter can have a NULL value. If not_null is TRUE, then that won't be allowed

param : a GnomeDbParameter object
not_null :

gnome_db_parameter_get_not_null ()

gboolean    gnome_db_parameter_get_not_null (GnomeDbParameter *param);

Get wether the parameter can be NULL or not

param : a GnomeDbParameter object
Returns : TRUE if the parameter cannot be NULL

gnome_db_parameter_set_source_field ()

gboolean    gnome_db_parameter_set_source_field
                                            (GnomeDbParameter *param,
                                             GnomeDbField *field,
                                             GError **error);

Sets a limit on the possible values for the param parameter: the value must be among the values of field within the GnomeDbEntity to which field belongs (the GnomeDbEntity can either be a GnomeDbDataModel which already has some data, or a GnomeDbQuery which will be converted to a GnomeDbResultset (which itself is a GnomeDbDataModel) to have some actual data).

field must be of the same type as the requested type for param.

field is not copied, just referenced.

param : a GnomeDbParameter object
field : a GnomeDbField object or NULL
error : location to store error, or NULL
Returns : TRUE if no error occurred

gnome_db_parameter_get_source_field ()

GnomeDbField* gnome_db_parameter_get_source_field
                                            (GnomeDbParameter *param);

param :
Returns :

gnome_db_parameter_add_dependency ()

void        gnome_db_parameter_add_dependency
                                            (GnomeDbParameter *param,
                                             GnomeDbParameter *depend_on);

Tell param that its value will depend on the value of depend_on

param : a GnomeDbParameter object
depend_on : a GnomeDbParameter object

gnome_db_parameter_del_dependency ()

void        gnome_db_parameter_del_dependency
                                            (GnomeDbParameter *param,
                                             GnomeDbParameter *depend_on);

Remove the depend_on dependency from param

param : a GnomeDbParameter object
depend_on : a GnomeDbParameter object

gnome_db_parameter_get_dependencies ()

GSList*     gnome_db_parameter_get_dependencies
                                            (GnomeDbParameter *param);

Get the list of GnomeDbParameter param depends on

param : a GnomeDbParameter object
Returns : the list of parameters (the list should not be modified)

gnome_db_parameter_replace_ref ()

void        gnome_db_parameter_replace_ref  (GnomeDbParameter *param,
                                             GHashTable *replacements);

Replace references to some objects by references to some other objects, as listed in replacements.

param : a GnomeDbParameter object
replacements : the (objects to be replaced, replacing object) pairs

gnome_db_parameter_bind_to_param ()

void        gnome_db_parameter_bind_to_param
                                            (GnomeDbParameter *param,
                                             GnomeDbParameter *bind_to);

Sets param to change when bind_to changes (and does not make bind_to change when param changes)

param : a GnomeDbParameter
bind_to : a GnomeDbParameter or NULL

gnome_db_parameter_get_bind_param ()

GnomeDbParameter* gnome_db_parameter_get_bind_param
                                            (GnomeDbParameter *param);

Get the parameter which makes param change its value when the param's value is changed.

param : a GnomeDbParameter
Returns : the GnomeDbParameter or NULL

gnome_db_parameter_requires_user_input ()

gboolean    gnome_db_parameter_requires_user_input
                                            (GnomeDbParameter *param);

Tells if the parameter is configured in a way that even if there is a value, it requires that the user at least validates that value, or change it.

param : a GnomeDbParameter
Returns : TRUE if user input is required

gnome_db_parameter_set_user_input_required ()

void        gnome_db_parameter_set_user_input_required
                                            (GnomeDbParameter *param,
                                             gboolean input_required);

Sets if the user input is required for param (even though it may already have a value) and be valid.

param : a GnomeDbParameter
input_required :

Property Details

The "full-bind" property

  "full-bind"            gpointer              : Read / Write


The "handler-plugin" property

  "handler-plugin"       gchararray            : Read / Write

Default value: NULL


The "simple-bind" property

  "simple-bind"          gpointer              : Read / Write


The "use-default-value" property

  "use-default-value"    gboolean              : Read / Write

Default value: FALSE