.TH "doc_tutorials_changetracking_md" 3elektra "Fri Aug 4 2023" "Version 0.11.0" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
doc_tutorials_changetracking_md \- Changetracking 
 Elektra provides developers of applications and plugins a way to determine changes made to a \fCKeySet\fP relative to the last known state of the key database\&. This can be useful if you are writing a plugin that works with changes of the configuration\&.
.SH "Basics"
.PP
The two headers you have to use are \fCkdbchangetracking\&.h\fP and \fCkdbdiff\&.h\fP\&. Those declare the \fCelektraChangeTracking*\fP and \fCelektraDiff*\fP functions\&.
.PP
The two main data structures you will encounter are \fCChangeTrackingContext\fP and \fCElektraDiff\fP\&.
.SH "Getting the difference between KeySets"
.PP
If all you want to do is get the difference between two in-memory \fCKeySet\fP objects, use the function \fCelektraDiffCalculate\fP\&.
.PP
.PP
.nf
KeySet * originalKeySet;
KeySet * modifiedKeySet;
Key * parentKey;

// Calculate the difference of the keys below and including parentKey
ElektraDiff * diff = elektraDiffCalculate (modifiedKeySet, originalKeySet, parentKey);

// Extract useful information, see section 'Working with the diff'

elektraDiffDel (diff);
.fi
.PP
.SH "Getting the changes within a transaction in a plugin"
.PP
If you are writing a plugin, you can use \fCelektraChangeTrackingGetContextFromPlugin\fP to get the current \fCChangeTrackingContext\fP\&. Then, use \fCelektraChangeTrackingCalculateDiff\fP to calculate the changes to the KDB\&.
.PP
.PP
.nf
int myPluginSet (Plugin * handle, KeySet * returned, Key * parentKey)
{
        const ChangeTrackingContext * ctx = elektraChangeTrackingGetContextFromPlugin (handle);
        ElektraDiff * diff = elektraChangeTrackingCalculateDiff (returned, ctx, parentKey);

        // Don't be impatient, we will soon look into what we can do with the diff

        elektraDiffDel (diff);
        return 1;
}
.fi
.PP
.SH "Getting the changes as an application developer"
.PP
If you are elektrifying your app, you can use \fCelektraChangeTrackingGetContextFromKdb\fP to get the current \fCChangeTrackingContext\fP for your KDB instance\&. Then, use \fCelektraChangeTrackingCalculateDiff\fP to calculate the changes to the KDB\&.
.PP
.PP
.nf
KDB * kdb;
KeySet * myKeySet;

const ChangeTrackingContext * ctx = elektraChangeTrackingGetContextFromKdb (kdb);
ElektraDiff * diff = elektraChangeTrackingCalculateDiff (myKeySet, ctx, parentKey);

// Don't be impatient, we will soon look into what we can do with the diff

elektraDiffDel (diff);
.fi
.PP
.SH "Working with the diff"
.PP
Congratulations! You've got your diff! Now what? Elektra provides you with different functions to determine added, removed and modified keys, as well as added, removed and modified metadata\&.
.PP
You can use the following methods to reason about changes to the keyset as a whole:
.PP
.PP
.nf
// Get keys that are in modifiedKeySet but not in originalKeySet
KeySet * addedKeys = elektraDiffGetAddedKeys (diff);

// Get keys that are in originalKeySet but not in modifiedKeySet
KeySet * removedKeys = elektraDiffGetRemovedKeys (diff);

// Get keys that are in both KeySets, but have either different values or different metadata\&.
// The returned keys will have the old values and metadata
KeySet * modifiedKeys = elektraDiffGetModifiedKeys (diff);

ksDel (addedKeys);
ksDel (removedKeys);
ksDel (modifiedKeys);
.fi
.PP
.PP
Use these methods to get information about single keys:
.PP
.PP
.nf
Key * myKey; // A key that we want to check\&.

// whether the value of myKey has been changed
bool valueChanged = elektraDiffKeyValueChanged (diff, myKey);

// determine if only the metadata of myKey has been changed
bool onlyMetaChanged = elektraDiffKeyOnlyMetaChanged (diff, myKey);

// get all metadata that has been added to myKey
KeySet * addedMeta = elektraDiffGetAddedMetaKeys (diff, myKey);

// get all metadata that has been removed from myKey
KeySet * removedMeta = elektraDiffGetRemovedMetaKeys (diff, myKey);

// get all metadata that has been modified\&.
// the returned keyset will contain the old metadata
KeySet * modifiedMeta = elektraDiffGetModifiedMetaKeys (diff, myKey);

ksDel (addedMeta);
ksDel (removedMeta);
ksDel (modifiedMeta);
.fi
.PP