QOF: Merge: Merging QofBook structures

QOF 0.7.5

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

Files | Data Structures | Enumerations
Merge: Merging QofBook structures
Query Object Framework

## Files
file | qofbookmerge.h
| API for merging two `QofBook` structures with collision handling.

## Data Structures
struct | QofBookMergeRule
| One rule per entity, built into a single GList for the entire merge. More...
struct | QofBookMergeData
| mergeData contains the essential context data for any merge. More...

## Enumerations
enum | QofBookMergeResult { MERGE_UNDEF, MERGE_ABSOLUTE, MERGE_NEW, MERGE_REPORT, MERGE_DUPLICATE, MERGE_UPDATE, MERGE_INVALID }
| Results of collisions and user resolution. More...

## qof_book_merge API
typedef void(* | QofBookMergeRuleForeachCB) (QofBookMergeData *, QofBookMergeRule *, guint)
| Definition of the dialogue control callback routine. More...
QofBookMergeData * | qof_book_merge_init (QofBook *importBook, QofBook *targetBook)
| Initialise the QofBookMerge process. More...
void | qof_book_merge_rule_foreach (QofBookMergeData *mergeData, QofBookMergeRuleForeachCB callback, QofBookMergeResult mergeResult)
| Dialogue Control Callback. More...
gchar * | qof_book_merge_param_as_string (QofParam *qtparam, QofEntity *qtEnt)
| provides easy string access to parameter data for dialogue use More...
QofBookMergeData * | qof_book_merge_update_result (QofBookMergeData *mergeData, QofBookMergeResult tag)
| called by dialogue callback to set the result of user intervention More...
gint | qof_book_merge_commit (QofBookMergeData *mergeData)
| Commits the import data to the target book. More...
void | qof_book_merge_abort (QofBookMergeData *mergeData)
| Abort the merge and free all memory allocated by the merge. More...

## Detailed Description

Collision handling principles.

1. Always check for a ::GUID first and compare. qofbookmerge only accepts valid QofBook data and therefore ALL objects in the import book will include valid GUID's.
2. If the original import data did not contain a GUID (e.g. an external non-GnuCash source) the GUID values will have been created during the import and will not match any existing GUID's in the target book so objects that do not have a GUID match cannot be assumed to be MERGE_NEW - parameter values must be checked.
3. If import contains data from closed books, store the data from the closed books in the current book as active. i.e. re-open the books.

If a GUID match exists, set qof_book_merge_rule::mergeAbsolute to TRUE.

1. If ALL parameters in the import object match the target object with the same GUID, set ::qof_book_merge_result to MERGE_ABSOLUTE.
2. If any parameters differ, set MERGE_UPDATE.

If the import object GUID does not match an existing object, mergeAbsolute is unchanged from the default FALSE The parameter values of the object are compared to other objects of the same type in the target book.

1. If the same data exists in the target book with a different GUID, the object is tagged as DUPLICATE.
2. If the data has changed, the object is tagged as REPORT.
3. If the data does not match, the object is tagged as NEW

More information is at http://code.neil.williamsleesmill.me.uk/

Each foreach function uses g_return_if_fail checks to protect the target book. If any essential data is missing, the loop returns without changing the target book. Note that this will not set or return an error value. However, g_return is only used for critical errors that arise from programming errors, not for invalid import data which should be cleaned up before creating the import QofBook.

Only qof_book_merge_update_result and qof_book_merge_commit return any error values to the calling process. qof_book_merge_init returns a pointer to the QofBookMergeData struct - the calling process needs to make sure this is non-NULL to know that the Init has been successful.

Todo:
  Prior to libqof2 rationalise internal variable names.

## Typedef Documentation

typedef void(* QofBookMergeRuleForeachCB) (QofBookMergeData *, QofBookMergeRule *, guint)

Definition of the dialogue control callback routine.

All MERGE_REPORT rules must be offered for user intervention using this template.
Commit will fail if any rules are still tagged as MERGE_REPORT.

Calling processes are free to also offer MERGE_NEW, MERGE_UPDATE, MERGE_DUPLICATE and MERGE_ABSOLUTE for user intervention. Attempting to query MERGE_INVALID rules will cause an error.

For an example, consider test_rule_loop, declared as:

`void test_rule_loop(QofBookMergeData *mergeData, QofBookMergeRule *rule, guint remainder);
void test_rule_loop(QofBookMergeData *mergeData, QofBookMergeRule *rule, guint remainder)
{
g_return_if_fail(rule != NULL);
g_return_if_fail(mergeData != NULL); printf("Rule Result %s", rule->mergeType);
qof_book_merge_update_result(mergeData, rule, MERGE_UPDATE);
}`

The dialogue is free to call qof_book_merge_update_result in the loop or at the end as long as the link between the rule and the result is maintained, e.g. by using a GHashTable.
The parameters are:

- data : pointer to the QofBookMergeData metadata context returned by init.
- rule : pointer to the QofBookMergeRule that generated the collision report
- remainder : guint value returned from g_slist_length for the number of other rules remaining with the same result. This might be useful for a progress dialogue, it might not. When updating MERGE_REPORT, remainder must equal zero before calling qof_book_merge_commit or the import will abort.
  If the dialogue sets any rule result to MERGE_INVALID, the import will abort when qof_book_merge_commit is called. It is the responsibility of the calling function to handle the error code from qof_book_merge_commit, close the dialogue and return. The merge routines in these files will already have halted the merge operation and freed any memory allocated to merge structures before returning the error code. There is no need for the dialogue process to report back to QofBookMerge in this situation.

Definition at line 321 of file qofbookmerge.h.

## Enumeration Type Documentation

enum QofBookMergeResult

Results of collisions and user resolution.

All rules are initialised as MERGE_UNDEF. Once the comparison is complete, each object within the import will be updated.

MERGE_ABSOLUTE, MERGE_NEW, MERGE_DUPLICATE and MERGE_UPDATE can be reported to the user along with all MERGE_REPORT objects for confirmation. It may be useful later to allow MERGE_ABSOLUTE, MERGE_NEW, MERGE_DUPLICATE and MERGE_UPDATE to not be reported, if the user sets a preferences option for each result. (Always accept new items: Y/N default NO, ignores all MERGE_NEW if set to Y etc.) This option would not require any changes to qofbookmerge.

MERGE_NEW, MERGE_DUPLICATE and MERGE_UPDATE are only actioned after conflicts are resolved by the user using a dialog and all MERGE_REPORT objects are re-assigned to one of MERGE_NEW, MERGE_DUPLICATE or MERGE_UPDATE. There is no automatic merge, even if no entities are tagged as MERGE_REPORT, the calling process must still check for REPORT items using qof_book_merge_rule_foreach and call qof_book_merge_commit.

MERGE_INVALID data should be rare and allows for user-abort - the imported file/source may be corrupted and the prescence of invalid data should raise concerns that the rest of the data may be corrupted, damaged or otherwise altered. If any entity is tagged as MERGE_INVALID, the merge operation will abort and leave the target book completely unchanged.

MERGE_ABSOLUTE is only used for a complete match. The import object contains the same data in the same parameters with no omissions or amendments. If any data is missing, amended or added, the data is labelled MERGE_UPDATE.

Every piece of data has a corresponding result. Only when the count of items labelled MERGE_REPORT is equal to zero are MERGE_NEW and MERGE_UPDATE items added to the existing book.
MERGE_DUPLICATE items are silently ignored. Aborting the dialogue/process (by the user or in a program crash) at any point before the final commit leaves the existing book completely untouched.

Enumerator
MERGE_UNDEF | default value before comparison is made.
MERGE_ABSOLUTE | GUID exact match, no new data - ignore
MERGE_NEW | import object does not exist in the target book - add
MERGE_REPORT | import object needs user intervention - report
MERGE_DUPLICATE | import object with different GUID exactly matches existing GUID - ignore
MERGE_UPDATE | import object matches an existing entity but includes new or modified parameter data - update
MERGE_INVALID | import object didn't match registered object or parameter types or user decided to abort - abort

Definition at line 125 of file qofbookmerge.h.

126 {
127 MERGE_UNDEF,
128 MERGE_ABSOLUTE,
129 MERGE_NEW,
131 MERGE_REPORT,
132 MERGE_DUPLICATE,
134 MERGE_UPDATE,
136 MERGE_INVALID
138 } QofBookMergeResult;
MERGE_INVALID
Definition: qofbookmerge.h:136
MERGE_NEW
Definition: qofbookmerge.h:129
MERGE_DUPLICATE
Definition: qofbookmerge.h:132
MERGE_UPDATE
Definition: qofbookmerge.h:134
MERGE_ABSOLUTE
Definition: qofbookmerge.h:128
MERGE_UNDEF
Definition: qofbookmerge.h:127
QofBookMergeResult
QofBookMergeResult
Results of collisions and user resolution.
Definition: qofbookmerge.h:125
MERGE_REPORT
Definition: qofbookmerge.h:131

## Function Documentation

void qof_book_merge_abort | ( | QofBookMergeData * | mergeData | ) |

Abort the merge and free all memory allocated by the merge.

Sometimes, setting MERGE_INVALID is insufficient: e.g. if the user aborts the merge from outside the functions dealing with the merge ruleset. This function causes an immediate abort - the calling process must start again at Init if a new merge is required.

Definition at line 970 of file qofbookmerge.c.

971 {
972 QofBookMergeRule *currentRule;
973
974 g_return_if_fail (mergeData != NULL);
975 while (mergeData->mergeList != NULL)
976 {
977 currentRule = mergeData->mergeList->data;
978 g_slist_free (currentRule->linkedEntList);
979 g_slist_free (currentRule->mergeParam);
980 g_free (mergeData->mergeList->data);
981 if (currentRule)
982 {
983 g_slist_free (currentRule->linkedEntList);
984 g_slist_free (currentRule->mergeParam);
985 g_free (currentRule);
986 }
987 mergeData->mergeList = g_list_next (mergeData->mergeList);
988 }
989 g_list_free (mergeData->mergeList);
990 g_slist_free (mergeData->mergeObjectParams);
991 g_slist_free (mergeData->targetList);
992 if (mergeData->orphan_list != NULL)
993 g_slist_free (mergeData->orphan_list);
994 g_hash_table_destroy (mergeData->target_table);
995 g_free (mergeData);
996 }
QofBookMergeData::mergeList
GList * mergeList
Definition: qofbookmerge.h:213
QofBookMergeRule::mergeParam
GSList * mergeParam
Definition: qofbookmerge.h:178
QofBookMergeData::target_table
GHashTable * target_table
Definition: qofbookmerge.h:232
QofBookMergeRule::linkedEntList
GSList * linkedEntList
Definition: qofbookmerge.h:179
QofBookMergeRule
One rule per entity, built into a single GList for the entire merge.
Definition: qofbookmerge.h:164
QofBookMergeData::mergeObjectParams
GSList * mergeObjectParams
Definition: qofbookmerge.h:211
QofBookMergeData::orphan_list
GSList * orphan_list
Definition: qofbookmerge.h:224
QofBookMergeData::targetList
GSList * targetList
Definition: qofbookmerge.h:215

gint qof_book_merge_commit | ( | QofBookMergeData * | mergeData | ) |

Commits the import data to the target book.

The last function in the API and the final part of any QofBookMerge operation.

qof_book_merge_commit will abort the entire merge operation if any rule is set to MERGE_INVALID. It is the responsibility of the calling function to handle the error code from qof_book_mergeCommit, close the dialogue and return. qof_book_merge_commit will already have halted the merge operation and freed any memory allocated to all merge structures before returning the error code. There is no way for the dialogue process to report back to qof_book_merge in this situation.

qof_book_merge_commit checks for any entities still tagged as MERGE_REPORT and then proceeds to import all entities tagged as MERGE_UPDATE or MERGE_NEW into the target book.
This final process cannot be UNDONE!

Parameters

  mergeData | the merge context, QofBookMergeData*

Returns
  - -2 if any rules are tagged as MERGE_INVALID
    - mergeData will have been g_free'd).
    - note that this will be before any operations are done on the target QofBook.
  - -1 if mergeData is invalid or no merge has been initialised with qof_book_merge_init - the calling process must check the value of mergeData
  - +1 if some entities are still tagged as MERGE_REPORT - use ::qof_book_merge_update_rule and try again (mergeData is retained).
  - 0 on success - mergeData will have been freed.

Definition at line 1164 of file qofbookmerge.c.

1165 {
1166 QofBookMergeRule *currentRule;
1167 GList *check, *node;
1168
1169 g_return_val_if_fail (mergeData != NULL, -1);
1170 g_return_val_if_fail (mergeData->mergeList != NULL, -1);
1171 g_return_val_if_fail (mergeData->targetBook != NULL, -1);
1172 if (mergeData->abort == TRUE)
1173 return -1;
1174 check = g_list_copy (mergeData->mergeList);
1175 g_return_val_if_fail (check != NULL, -1);
1176 for (node = check; node != NULL; node = node->next)
1177 {
1178 currentRule = node->data;
1179 if (currentRule->mergeResult == MERGE_INVALID)
1180 {
1181 qof_book_merge_abort (mergeData);
1182 g_list_free (check);
1183 return (-2);
1184 }
1185 if (currentRule->mergeResult == MERGE_REPORT)
1186 {
1187 g_list_free (check);
1188 return 1;
1189 }
1190 }
1191 g_list_free (check);
1192 qof_book_merge_commit_foreach (qof_book_merge_commit_rule_loop,
1193 MERGE_NEW, mergeData);
1194 qof_book_merge_commit_foreach (qof_book_merge_commit_rule_loop,
1195 MERGE_UPDATE, mergeData);
1196 /* Placeholder for QofObject merge_helper_cb - all objects
1197 and all parameters set */
1198 while (mergeData->mergeList != NULL)
1199 {
1200 currentRule = mergeData->mergeList->data;
1201 g_slist_free (currentRule->mergeParam);
1202 g_slist_free (currentRule->linkedEntList);
1203 mergeData->mergeList = g_list_next (mergeData->mergeList);
1204 }
1205 g_list_free (mergeData->mergeList);
1206 g_slist_free (mergeData->mergeObjectParams);
1207 g_slist_free (mergeData->targetList);
1208 if (mergeData->orphan_list != NULL)
1209 g_slist_free (mergeData->orphan_list);
1210 g_hash_table_destroy (mergeData->target_table);
1211 g_free (mergeData);
1212 return 0;
1213 }
QofBookMergeData::mergeList
GList * mergeList
Definition: qofbookmerge.h:213
MERGE_INVALID
Definition: qofbookmerge.h:136
MERGE_NEW
Definition: qofbookmerge.h:129
QofBookMergeRule::mergeParam
GSList * mergeParam
Definition: qofbookmerge.h:178
QofBookMergeData::target_table
GHashTable * target_table
Definition: qofbookmerge.h:232
QofBookMergeRule::mergeResult
QofBookMergeResult mergeResult
Definition: qofbookmerge.h:188
QofBookMergeRule::linkedEntList
GSList * linkedEntList
Definition: qofbookmerge.h:179
MERGE_UPDATE
Definition: qofbookmerge.h:134
QofBookMergeRule
One rule per entity, built into a single GList for the entire merge.
Definition: qofbookmerge.h:164
QofBookMergeData::abort
gboolean abort
Definition: qofbookmerge.h:221
QofBookMergeData::targetBook
QofBook * targetBook
Definition: qofbookmerge.h:219
qof_book_merge_abort
void qof_book_merge_abort(QofBookMergeData *mergeData)
Abort the merge and free all memory allocated by the merge.
Definition: qofbookmerge.c:970
QofBookMergeData::mergeObjectParams
GSList * mergeObjectParams
Definition: qofbookmerge.h:211
QofBookMergeData::orphan_list
GSList * orphan_list
Definition: qofbookmerge.h:224
MERGE_REPORT
Definition: qofbookmerge.h:131
QofBookMergeData::targetList
GSList * targetList
Definition: qofbookmerge.h:215

QofBookMergeData* qof_book_merge_init | ( | QofBook * | importBook,
|  | QofBook * | targetBook
| ) |  |

Initialise the QofBookMerge process.

First function of the QofBookMerge API. Every merge must begin with init.

Requires the book to import (QofBook *) and the book to receive the import, the target book (QofBook *). Returns a pointer to QofBookMergeData which must be checked for a NULL before continuing.
Process:

    -# Invoke the callback ::qof_book_merge_foreach_type on every registered
    object class definition.
    -# Callback obtains the registered parameter list for each object type.
    This provides run time access to all registered objects and all object
    parameters without any changes to QofBookMerge - no registered object or
    parameter is omitted from any merge operation.
    -# Use ::qof_object_foreach to invoke the callback ::qof_book_merge_foreach,
    one object at a time on every instance stored in mergeBook. This is the
    first point where real data from the import book is accessed.
    -# qof_book_merge_foreach obtains the ::GUID for the object from the import
    book and runs the first check on the original book, checking for any exact
    GUID match. With the full parameter list, the rules for this object can be
    created. If there is a GUID match, the data in each parameter of the import
    object is compared with the same semantic object in the original book. If
    there is no GUID in the import object or no GUID match with the original
    book, the original book is searched to find a parameter match - checking
    for a ::MERGE_DUPLICATE result.
    -# ::qof_book_merge_compare sets the ::QofBookMergeResult of the comparison.
    -# Inserts the completed rule into QofBookMergeData::mergeList GSList.

Returns
  NULL in case of error, otherwise a QofBookMergeData* metadata context.

Definition at line 933 of file qofbookmerge.c.

934 {
935 QofBookMergeData *mergeData;
936 QofBookMergeRule *currentRule;
937 GList *check;
938
939 g_return_val_if_fail ((importBook != NULL)
940 && (targetBook != NULL), NULL);
941 mergeData = g_new0 (QofBookMergeData, 1);
942 mergeData->abort = FALSE;
943 mergeData->mergeList = NULL;
944 mergeData->targetList = NULL;
945 mergeData->mergeBook = importBook;
946 mergeData->targetBook = targetBook;
947 mergeData->mergeObjectParams = NULL;
948 mergeData->orphan_list = NULL;
949 mergeData->target_table =
950 g_hash_table_new (g_direct_hash, qof_book_merge_rule_cmp);
951 currentRule = g_new0 (QofBookMergeRule, 1);
952 mergeData->currentRule = currentRule;
953 qof_object_foreach_type (qof_book_merge_foreach_type, mergeData);
954 g_return_val_if_fail (mergeData->mergeObjectParams, NULL);
955 if (mergeData->orphan_list != NULL)
956 qof_book_merge_match_orphans (mergeData);
957 for (check = mergeData->mergeList; check != NULL; check = check->next)
958 {
959 currentRule = check->data;
960 if (currentRule->mergeResult == MERGE_INVALID)
961 {
962 mergeData->abort = TRUE;
963 return (NULL);
964 }
965 }
966 return mergeData;
967 }
QofBookMergeData::mergeList
GList * mergeList
Definition: qofbookmerge.h:213
QofBookMergeData::mergeBook
QofBook * mergeBook
Definition: qofbookmerge.h:217
MERGE_INVALID
Definition: qofbookmerge.h:136
QofBookMergeData::target_table
GHashTable * target_table
Definition: qofbookmerge.h:232
QofBookMergeRule::mergeResult
QofBookMergeResult mergeResult
Definition: qofbookmerge.h:188
QofBookMergeRule
One rule per entity, built into a single GList for the entire merge.
Definition: qofbookmerge.h:164
QofBookMergeData::abort
gboolean abort
Definition: qofbookmerge.h:221
QofBookMergeData::currentRule
QofBookMergeRule * currentRule
Definition: qofbookmerge.h:222
QofBookMergeData::targetBook
QofBook * targetBook
Definition: qofbookmerge.h:219
QofBookMergeData::mergeObjectParams
GSList * mergeObjectParams
Definition: qofbookmerge.h:211
QofBookMergeData::orphan_list
GSList * orphan_list
Definition: qofbookmerge.h:224
qof_object_foreach_type
void qof_object_foreach_type(QofForeachTypeCB cb, gpointer user_data)
Definition: qofobject.c:140
QofBookMergeData::targetList
GSList * targetList
Definition: qofbookmerge.h:215
QofBookMergeData
mergeData contains the essential context data for any merge.
Definition: qofbookmerge.h:209

gchar* qof_book_merge_param_as_string | ( | QofParam * | qtparam,
|  | QofEntity * | qtEnt
| ) |  |

provides easy string access to parameter data for dialogue use

Uses the param_getfcn to retrieve the parameter value as a string, suitable for display in dialogues and user intervention output. Within a QofBookMerge context, only the parameters used in the merge are available, i.e. parameters where both param_getfcn and param_setfcn are not NULL.

Note that the object type description (a full text version of the object name) is also available to the dialogue as QofBookMergeRule::mergeLabel.

This allows the dialog to display the description of the object and all parameter data.

Deprecated:
  replace with qof_util_param_as_string

Definition at line 1010 of file qofbookmerge.c.

1011 {
1012 gchar *param_string;
1013 gchar param_sa[GUID_ENCODING_LENGTH + 1];
1014 QofType paramType;
1015 const GUID *param_guid;
1016 QofTime *param_qt;
1017 QofNumeric param_numeric, (*numeric_getter) (QofEntity *, QofParam *);
1018 gdouble param_double, (*double_getter) (QofEntity *, QofParam *);
1019 gboolean param_boolean, (*boolean_getter) (QofEntity *, QofParam *);
1020 gint32 param_i32, (*int32_getter) (QofEntity *, QofParam *);
1021 gint64 param_i64, (*int64_getter) (QofEntity *, QofParam *);
1022 gchar param_char, (*char_getter) (QofEntity *, QofParam *);
1023
1024 param_string = NULL;
1025 paramType = qtparam->param_type;
1026 if (safe_strcmp (paramType, QOF_TYPE_STRING) == 0)
1027 {
1028 param_string = qtparam->param_getfcn (qtEnt, qtparam);
1029 if (param_string == NULL)
1030 param_string = "";
1031 return param_string;
1032 }
1033 if (safe_strcmp (paramType, QOF_TYPE_TIME) == 0)
1034 {
1035 QofDate *qd;
1036
1037 param_qt = qof_time_copy (
1038 qtparam->param_getfcn (qtEnt, qtparam));
1039 if (!param_qt)
1040 return NULL;
1041 qd = qof_date_from_qtime (param_qt);
1042 param_string = qof_date_print (qd, QOF_DATE_FORMAT_UTC);
1043 qof_date_free (qd);
1044 qof_time_free (param_qt);
1045 return param_string;
1046 }
1047 #ifndef QOF_DISABLE_DEPRECATED
1048 if (safe_strcmp (paramType, QOF_TYPE_DATE) == 0)
1049 {
1050 Timespec param_ts, (*date_getter) (QofEntity *, QofParam *);
1051 time_t param_t;
1052 gchar param_date[QOF_DATE_STRING_LENGTH];
1053
1054 date_getter =
1055 (Timespec (*)(QofEntity *, QofParam *)) qtparam->param_getfcn;
1056 param_ts = date_getter (qtEnt, qtparam);
1057 param_t = timespecToTime_t (param_ts);
1058 strftime (param_date, QOF_DATE_STRING_LENGTH, QOF_UTC_DATE_FORMAT,
1059 gmtime (&param_t));
1060 param_string = g_strdup (param_date);
1061 return param_string;
1062 }
1063 #endif
1064 if ((safe_strcmp (paramType, QOF_TYPE_NUMERIC) == 0) ||
1065 (safe_strcmp (paramType, QOF_TYPE_DEBCRED) == 0))
1066 {
1067 numeric_getter =
1068 (QofNumeric (*)(QofEntity *,
1069 QofParam *)) qtparam->param_getfcn;
1070 param_numeric = numeric_getter (qtEnt, qtparam);
1071 param_string = g_strdup (qof_numeric_to_string (param_numeric));
1072 return param_string;
1073 }
1074 if (safe_strcmp (paramType, QOF_TYPE_GUID) == 0)
1075 {
1076 param_guid = qtparam->param_getfcn (qtEnt, qtparam);
1077 guid_to_string_buff (param_guid, param_sa);
1078 param_string = g_strdup (param_sa);
1079 return param_string;
1080 }
1081 if (safe_strcmp (paramType, QOF_TYPE_INT32) == 0)
1082 {
1083 int32_getter =
1084 (gint32 (*)(QofEntity *, QofParam *)) qtparam->param_getfcn;
1085 param_i32 = int32_getter (qtEnt, qtparam);
1086 param_string = g_strdup_printf ("%d", param_i32);
1087 return param_string;
1088 }
1089 if (safe_strcmp (paramType, QOF_TYPE_INT64) == 0)
1090 {
1091 int64_getter =
1092 (gint64 (*)(QofEntity *, QofParam *)) qtparam->param_getfcn;
1093 param_i64 = int64_getter (qtEnt, qtparam);
1094 param_string = g_strdup_printf ("%" G_GINT64_FORMAT, param_i64);
1095 return param_string;
1096 }
1097 if (safe_strcmp (paramType, QOF_TYPE_DOUBLE) == 0)
1098 {
1099 double_getter =
1100 (double (*)(QofEntity *, QofParam *)) qtparam->param_getfcn;
1101 param_double = double_getter (qtEnt, qtparam);
1102 param_string = g_strdup_printf ("%f", param_double);
1103 return param_string;
1104 }
1105 if (safe_strcmp (paramType, QOF_TYPE_BOOLEAN) == 0)
1106 {
1107 boolean_getter =
1108 (gboolean (*)(QofEntity *, QofParam *)) qtparam->param_getfcn;
1109 param_boolean = boolean_getter (qtEnt, qtparam);
1110 /* Boolean values need to be lowercase for QSF validation. */
1111 if (param_boolean == TRUE)
1112 param_string = g_strdup ("true");
1113 else
1114 param_string = g_strdup ("false");
1115 return param_string;
1116 }
1117 /* "kvp" contains repeating values, cannot be a single string for the frame. */
1118 if (safe_strcmp (paramType, QOF_TYPE_KVP) == 0)
1119 return param_string;
1120 if (safe_strcmp (paramType, QOF_TYPE_CHAR) == 0)
1121 {
1122 char_getter =
1123 (gchar (*)(QofEntity *, QofParam *)) qtparam->param_getfcn;
1124 param_char = char_getter (qtEnt, qtparam);
1125 param_string = g_strdup_printf ("%c", param_char);
1126 return param_string;
1127 }
1128 return NULL;
1129 }
QOF_TYPE_DATE
#define QOF_TYPE_DATE
Definition: deprecated.h:336
QOF_DATE_FORMAT_UTC
#define QOF_DATE_FORMAT_UTC
QOF UTC format, xsd:date compatible. QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ".
Definition: qofdate.h:277
Timespec
struct timespec64 Timespec
QofNumeric
struct _QofNumeric QofNumeric
A rational-number type.
Definition: qofnumeric.h:61
qof_date_free
void qof_date_free(QofDate *date)
Definition: qofdate.c:608
_QofParam
Definition: qofclass.h:195
QOF_UTC_DATE_FORMAT
#define QOF_UTC_DATE_FORMAT
UTC date format string.
Definition: qofdate.h:244
qof_date_from_qtime
QofDate * qof_date_from_qtime(const QofTime *qt)
Definition: qofdate.c:850
QofEntity_s
Definition: qofid.h:147
qof_date_print
gchar * qof_date_print(const QofDate *date, QofDateFormat df)
Convert a QofDate to a timestamp according to the specified date format.
Definition: qofdate.c:547
qof_time_copy
QofTime * qof_time_copy(const QofTime *qt)
Create a copy of a QofTime.
Definition: qoftime.c:223
timespec64
Definition: qoftime.h:97
GUID_ENCODING_LENGTH
#define GUID_ENCODING_LENGTH
Definition: guid.h:64
QofDate_s
Full range replacement for struct tm.
Definition: qofdate.h:138
qof_time_free
void qof_time_free(QofTime *qt)
Free a QofTime when no longer required.
Definition: qoftime.c:56
_QofNumeric
Definition: qofnumeric.h:52
guid_to_string_buff
gchar * guid_to_string_buff(const GUID *guid, gchar *buff)
QofType
const gchar * QofType
Definition: qofclass.h:150
_GUID
Definition: guid.h:53
qof_numeric_to_string
gchar * qof_numeric_to_string(QofNumeric n)
Definition: qofnumeric.c:1089
QofTime
struct QofTime64 QofTime
Use a 64-bit signed int QofTime.
Definition: qoftime.h:120
timespecToTime_t
time_t timespecToTime_t(Timespec ts)
Definition: deprecated.c:315
safe_strcmp
gint safe_strcmp(const gchar *da, const gchar *db)
Definition: qofutil.c:72

void qof_book_merge_rule_foreach | ( | QofBookMergeData * | mergeData,
|  | QofBookMergeRuleForeachCB | callback,
|  | QofBookMergeResult | mergeResult
| ) |  |

Dialogue Control Callback.

This function is designed to be used to iterate over all rules tagged with a specific QofBookMergeResult value.

Parameters

  callback | external loop of type QofBookMergeRuleForeachCB
  mergeResult | QofBookMergeResult value to look up.
  mergeData | QofBookMergeData merge context.

Note : MERGE_NEW causes a new entity to be created in the target book at commit which is then assigned as the targetEnt of that rule. If mergeResult == MERGE_NEW, the rules returned by qof_book_merge_rule_foreach will have a NULL set for the targetEnt. This is because commit has not yet been called and no changes can be made to the target book. The calling process must handle the NULL targetEnt and NOT call any param_getfcn routines for the target entity. The import entity is available for display.

Uses qof_book_get_collection with the QofBookMergeRule::mergeType object type to return a collection of QofEntity entities from either the QofBookMergeData::mergeBook or QofBookMergeData::targetBook. Then uses qof_collection_lookup_entity to lookup the QofBookMergeRule::importEnt and again the qof_book_mergeRule::targetEnt to return the two specific entities.

Definition at line 1216 of file qofbookmerge.c.

1218 {
1219 struct QofBookMergeRuleIterate qiter;
1220 QofBookMergeRule *currentRule;
1221 GList *matching_rules, *node;
1222
1223 g_return_if_fail (cb != NULL);
1224 g_return_if_fail (mergeData != NULL);
1225 currentRule = mergeData->currentRule;
1226 g_return_if_fail (mergeResult > 0);
1227 g_return_if_fail (mergeResult != MERGE_INVALID);
1228 g_return_if_fail (mergeData->abort == FALSE);
1229 qiter.fcn = cb;
1230 qiter.data = mergeData;
1231 matching_rules = NULL;
1232 for (node = mergeData->mergeList; node != NULL; node = node->next)
1233 {
1234 currentRule = node->data;
1235 if (currentRule->mergeResult == mergeResult)
1236 matching_rules = g_list_prepend (matching_rules,
1237 currentRule);
1238 }
1239 qiter.remainder = g_list_length (matching_rules);
1240 g_list_foreach (matching_rules, qof_book_merge_rule_cb, &qiter);
1241 g_list_free (matching_rules);
1242 }
QofBookMergeData::mergeList
GList * mergeList
Definition: qofbookmerge.h:213
MERGE_INVALID
Definition: qofbookmerge.h:136
QofBookMergeRule
One rule per entity, built into a single GList for the entire merge.
Definition: qofbookmerge.h:164
QofBookMergeData::abort
gboolean abort
Definition: qofbookmerge.h:221
QofBookMergeData::currentRule
QofBookMergeRule * currentRule
Definition: qofbookmerge.h:222

QofBookMergeData* qof_book_merge_update_result | ( | QofBookMergeData * | mergeData,
|  | QofBookMergeResult | tag
| ) |  |

called by dialogue callback to set the result of user intervention

Set any rule result to MERGE_INVALID to abort the import when qof_book_merge_commit is called, without changing the target book.

The calling process should make it absolutely clear that a merge operation cannot be undone and that a backup copy should always be available before a merge is initialised.

Recommended method: Only offer three options to the user per rule:

1. Allow import data to be merged into target data
   - change MERGE_REPORT to MERGE_UPDATE
2. Allow import data without an exact match to be added as new
   - change MERGE_REPORT to MERGE_NEW IF mergeAbsolute = FALSE
3. Ignore import data and leave target data unchanged
   - change MERGE_REPORT to MERGE_ABSOLUTE or MERGE_DUPLICATE

Handle the required result changes in code: Check the value of qof_book_mergeRule::mergeAbsolute and use these principles:

To ignore entities tagged as:

- MERGE_REPORT, you must check the value of mergeAbsolute.
  - if mergeAbsolute is TRUE, change MERGE_REPORT to MERGE_ABSOLUTE
  - if mergeAbsolute is FALSE, change MERGE_REPORT to MERGE_DUPLICATE
- MERGE_NEW, set MERGE_DUPLICATE.
- MERGE_UPDATE, you must check the value of mergeAbsolute.
  - if mergeAbsolute is TRUE, change MERGE_UPDATE to MERGE_ABSOLUTE
  - if mergeAbsolute is FALSE, change MERGE_UPDATE to MERGE_DUPLICATE

To merge entities that are not pre-set to MERGE_NEW, set MERGE_UPDATE.
Attempting to merge an entity when the pre-set value was MERGE_NEW will force a change back to MERGE_NEW because no suitable target exists for the merge.

To add entities, check mergeAbsolute is FALSE and set MERGE_NEW.
An entity only be added if mergeAbsolute is FALSE. Attempting to add an entity when mergeAbsolute is TRUE will always force a MERGE_UPDATE.

It is not possible to update the same rule more than once.

1. MERGE_NEW is reserved for new objects and is only pre-set if all parameters, including GUID, have already failed to match any relevant object. qof_book_mergeCommit will create new entities for all rules tagged as MERGE_NEW.
   - if mergeAbsolute is TRUE and the user wants to import the data, requests to set MERGE_NEW will be forced to MERGE_UPDATE because an entity with that GUID already exists in the target book.
   - if MERGE_NEW is pre-set, requests to change to MERGE_UPDATE will be ignored because a new entity is needed.
2. MERGE_UPDATE is reserved for existing objects - qof_book_mergeCommit will require a matching entity to update and will force a change to back to MERGE_NEW if none is known to exist, using the principle above.
3. MERGE_INVALID will cause an abort of the merge process.
4. MERGE_UNDEF and MERGE_REPORT cannot be set - the entity result will be unchanged.
5. MERGE_DUPLICATE and MERGE_ABSOLUTE are handled identically but are semantically different - QofBookMergeRule::mergeAbsolute is used to dictate which to set:
   - if mergeAbsolute is TRUE but MERGE_DUPLICATE is requested, force a change to MERGE_ABSOLUTE.
   - if mergeAbsolute is FALSE but MERGE_ABSOLUTE is requested, force a change to MERGE_DUPLICATE.

qof_book_merge_commit only commits entities tagged with MERGE_NEW and MERGE_UPDATE results.
Entities tagged with MERGE_ABSOLUTE and MERGE_DUPLICATE results are ignored.

The calling process must check the return value and call ::qof_book_merge_abort(mergeData) if non-zero.

Parameters

  mergeData | the merge context, QofBookMergeData*
  tag | the result to attempt to set, QofBookMergeResult

Returns
  -1 if supplied parameters are invalid or NULL, 0 on success.

Definition at line 1132 of file qofbookmerge.c.

1134 {
1135 QofBookMergeRule *resolved;
1136
1137 g_return_val_if_fail ((mergeData != NULL), NULL);
1138 g_return_val_if_fail ((tag > 0), NULL);
1139 g_return_val_if_fail ((tag != MERGE_REPORT), NULL);
1140 resolved = mergeData->currentRule;
1141 g_return_val_if_fail ((resolved != NULL), NULL);
1142 if ((resolved->mergeAbsolute == TRUE) && (tag == MERGE_DUPLICATE))
1143 tag = MERGE_ABSOLUTE;
1144 if ((resolved->mergeAbsolute == TRUE) && (tag == MERGE_NEW))
1145 tag = MERGE_UPDATE;
1146 if ((resolved->mergeAbsolute == FALSE) && (tag == MERGE_ABSOLUTE))
1147 tag = MERGE_DUPLICATE;
1148 if ((resolved->mergeResult == MERGE_NEW) && (tag == MERGE_UPDATE))
1149 tag = MERGE_NEW;
1150 if (resolved->updated == FALSE)
1151 resolved->mergeResult = tag;
1152 resolved->updated = TRUE;
1153 if (tag >= MERGE_INVALID)
1154 {
1155 mergeData->abort = TRUE;
1156 mergeData->currentRule = resolved;
1157 return NULL;
1158 }
1159 mergeData->currentRule = resolved;
1160 return mergeData;
1161 }
MERGE_INVALID
Definition: qofbookmerge.h:136
MERGE_NEW
Definition: qofbookmerge.h:129
MERGE_DUPLICATE
Definition: qofbookmerge.h:132
QofBookMergeRule::mergeResult
QofBookMergeResult mergeResult
Definition: qofbookmerge.h:188
MERGE_UPDATE
Definition: qofbookmerge.h:134
QofBookMergeRule
One rule per entity, built into a single GList for the entire merge.
Definition: qofbookmerge.h:164
QofBookMergeData::abort
gboolean abort
Definition: qofbookmerge.h:221
MERGE_ABSOLUTE
Definition: qofbookmerge.h:128
QofBookMergeRule::mergeAbsolute
gboolean mergeAbsolute
Definition: qofbookmerge.h:167
QofBookMergeData::currentRule
QofBookMergeRule * currentRule
Definition: qofbookmerge.h:222
QofBookMergeRule::updated
gboolean updated
Definition: qofbookmerge.h:171
MERGE_REPORT
Definition: qofbookmerge.h:131