OpenSync  0.22
Functions
OpenSync Hashtables

A Hashtable can be used to detect changes. More...

Functions

OSyncHashTableosync_hashtable_new (void)
 Creates a new hashtable. More...
 
void osync_hashtable_free (OSyncHashTable *table)
 Frees a hashtable. More...
 
void osync_hashtable_forget (OSyncHashTable *table)
 Makes a hashtable forget. More...
 
osync_bool osync_hashtable_load (OSyncHashTable *table, OSyncMember *member, OSyncError **error)
 Loads a hashtable from disk. More...
 
void osync_hashtable_close (OSyncHashTable *table)
 Closes a previously loaded table. More...
 
int osync_hashtable_num_entries (OSyncHashTable *table)
 Returns the number of entries in this hashtable. More...
 
osync_bool osync_hashtable_nth_entry (OSyncHashTable *table, int i, char **uid, char **hash)
 Gets the nth entry from the table. More...
 
void osync_hashtable_update_hash (OSyncHashTable *table, OSyncChange *change)
 Update the hash for a entry. More...
 
void osync_hashtable_report (OSyncHashTable *table, const char *uid)
 Report a item. More...
 
void osync_hashtable_report_deleted (OSyncHashTable *table, OSyncContext *context, const char *objtype)
 Report all deleted items. More...
 
char ** osync_hashtable_get_deleted (OSyncHashTable *table, const char *objtype)
 Get the uid of all deleted items. More...
 
void osync_hashtable_get_hash (OSyncHashTable *table, OSyncChange *chg)
 Get the hash value from the hash table. More...
 
OSyncChangeType osync_hashtable_get_changetype (OSyncHashTable *table, const char *uid, const char *objtype, const char *hash)
 Gets the changetype for a given uid and hash. More...
 
osync_bool osync_hashtable_detect_change (OSyncHashTable *table, OSyncChange *change)
 Gets the changetype of an object and sets it directly. More...
 
void osync_hashtable_set_slow_sync (OSyncHashTable *table, const char *objtype)
 Resets the hashtable for a given object type. More...
 

Detailed Description

A Hashtable can be used to detect changes.

Hashtables can be used to detect changes since the last invokation. They do this by keeping track of all reported uids and the hashes of the objects.

Hashes are strings that change when the objects is updated or when the content of the object changes. So hashes can either be a real hash like an MD5 or something like a timestamp. The only important thing is that the hash changes once the item gets updated.

The hashtable works like this:

Now you can query and alter the table. You can ask if a item has changed by doing:

After you are done call:

The hashtable works like this:

First the items are reported with a certain uid or hash. If the uid does not yet exist in the database it is reported as ADDED. if the uid exists and the hash is different it is reported as MODIFIED. if the uid exists but the hash is the same it means that the object is UNMODIFIED.

To be able to report deleted objects the hashtables keeps track of the uids you reported. After you are done with asking the hashtable for changes you can ask it for deleted objects. All items that are in the hashtable but where not reported by you have to be DELETED.

Function Documentation

OSyncHashTable* osync_hashtable_new ( void  )

Creates a new hashtable.

Hashtables can be used to detect what has been changed since the last sync

Returns
A new hashtable

Definition at line 93 of file opensync_hashtable.c.

void osync_hashtable_free ( OSyncHashTable table)

Frees a hashtable.

Parameters
tableThe hashtable to free

Definition at line 107 of file opensync_hashtable.c.

void osync_hashtable_forget ( OSyncHashTable table)

Makes a hashtable forget.

You can ask the hashtable to detect the changes. In the end you can ask the hashtable for all items that have been deleted since the last sync. For this the hashtable maintains a internal table of items you already reported and reports the items it didnt see yet as deleted. This function resets the internal table so it start to report deleted items again

Parameters
tableThe hashtable

Definition at line 124 of file opensync_hashtable.c.

Referenced by osync_hashtable_close().

osync_bool osync_hashtable_load ( OSyncHashTable table,
OSyncMember member,
OSyncError **  error 
)

Loads a hashtable from disk.

Parameters
tableThe hashtable
memberThe member for which to load the table
errorAn error struct
Returns
TRUE if successfull, FALSE otherwise

Definition at line 138 of file opensync_hashtable.c.

void osync_hashtable_close ( OSyncHashTable table)

Closes a previously loaded table.

This function also makes the hashtable "forget"

Parameters
tableThe hashtable

Definition at line 150 of file opensync_hashtable.c.

int osync_hashtable_num_entries ( OSyncHashTable table)

Returns the number of entries in this hashtable.

Parameters
tableThe hashtable
Returns
The number of entries

Definition at line 164 of file opensync_hashtable.c.

osync_bool osync_hashtable_nth_entry ( OSyncHashTable table,
int  i,
char **  uid,
char **  hash 
)

Gets the nth entry from the table.

This is mainly usefull for debugging or special purposes

Parameters
tableThe hashtable
iThe number of the entry to return
uidA pointer to a char * that will hold the uid. The caller is responible for freeing
hashA pointer to a char * that will hold the hash. The caller is responible for freeing
Returns
TRUE if successfull, FALSE otherwise

Definition at line 182 of file opensync_hashtable.c.

void osync_hashtable_update_hash ( OSyncHashTable table,
OSyncChange change 
)

Update the hash for a entry.

Updates the hash for a entry in the hashtable. Do this after you see that a hash has changed, for example after reading it during get_changes or after you wrote it

Parameters
tableThe hashtable
changeThe change with the new hash information

Definition at line 208 of file opensync_hashtable.c.

Referenced by osync_hashtable_report_deleted().

void osync_hashtable_report ( OSyncHashTable table,
const char *  uid 
)

Report a item.

When you use this function the item is marked as reported, so it will not get listed as deleted. Use this function if there are problems accessing an object for example so that the object does not get reported as deleted accidently.

Parameters
tableThe hashtable
uidThe uid to report

Definition at line 244 of file opensync_hashtable.c.

void osync_hashtable_report_deleted ( OSyncHashTable table,
OSyncContext *  context,
const char *  objtype 
)

Report all deleted items.

Parameters
tableThe hashtable
contextThe context in which to report the changes
objtypeThe object type which to report, NULL for all

Definition at line 261 of file opensync_hashtable.c.

char** osync_hashtable_get_deleted ( OSyncHashTable table,
const char *  objtype 
)

Get the uid of all deleted items.

Parameters
tableThe hashtable
objtypeThe object type which to report, NULL for all
Returns
An Null terminated array of uids. The uids and this array have to be freed.

Definition at line 290 of file opensync_hashtable.c.

void osync_hashtable_get_hash ( OSyncHashTable table,
OSyncChange chg 
)

Get the hash value from the hash table.

Definition at line 303 of file opensync_hashtable.c.

OSyncChangeType osync_hashtable_get_changetype ( OSyncHashTable table,
const char *  uid,
const char *  objtype,
const char *  hash 
)

Gets the changetype for a given uid and hash.

This functions does not report the object so if you only use this function it will get reported as deleted! Please use osync_hashtable_report() for reporting and object.

Parameters
tableThe hashtable
uidThe uid to lookup
hashThe hash to compare
Returns
The changetype

Definition at line 323 of file opensync_hashtable.c.

Referenced by osync_hashtable_detect_change().

osync_bool osync_hashtable_detect_change ( OSyncHashTable table,
OSyncChange change 
)

Gets the changetype of an object and sets it directly.

This functions also call report

Parameters
tableThe hashtable
changeThe change to check
Returns
TRUE if the object was not changed, FALSE if it was changed or added

Definition at line 354 of file opensync_hashtable.c.

void osync_hashtable_set_slow_sync ( OSyncHashTable table,
const char *  objtype 
)

Resets the hashtable for a given object type.

Parameters
tableThe hashtable
objtypeThe object type to slow-sync, NULL for all

Definition at line 373 of file opensync_hashtable.c.