OpenSync  0.22
Modules | Data Structures | Typedefs | Enumerations | Functions
OpenSync Engine API

The API of the syncengine available to everyone. More...

Modules

 OpenSync Mapping
 The commands to manipulate mappings.
 

Data Structures

struct  OSyncMemberUpdate
 Struct for the member status callback. More...
 
struct  OSyncChangeUpdate
 Struct for the change status callback. More...
 
struct  OSyncMappingUpdate
 Struct for the mapping status callback. More...
 
struct  OSyncEngineUpdate
 Struct for the engine status callback. More...
 

Typedefs

typedef struct OSyncMemberUpdate OSyncMemberUpdate
 Struct for the member status callback.
 
typedef struct OSyncChangeUpdate OSyncChangeUpdate
 Struct for the change status callback.
 
typedef struct OSyncMappingUpdate OSyncMappingUpdate
 Struct for the mapping status callback.
 
typedef struct OSyncEngineUpdate OSyncEngineUpdate
 Struct for the engine status callback.
 

Enumerations

enum  memberupdatetype {
  MEMBER_CONNECTED, MEMBER_SENT_CHANGES, MEMBER_COMMITTED_ALL, MEMBER_DISCONNECTED,
  MEMBER_CONNECT_ERROR, MEMBER_GET_CHANGES_ERROR, MEMBER_COMMITTED_ALL_ERROR, MEMBER_SYNC_DONE_ERROR,
  MEMBER_DISCONNECT_ERROR
}
 The types of status updates for members. More...
 
enum  changeupdatetype {
  CHANGE_RECEIVED = 1, CHANGE_RECEIVED_INFO = 2, CHANGE_SENT = 3, CHANGE_WRITE_ERROR = 4,
  CHANGE_RECV_ERROR = 5
}
 The types of status updates for changes. More...
 
enum  mappingupdatetype { MAPPING_SOLVED = 1, MAPPING_SYNCED = 2, MAPPING_WRITE_ERROR = 3 }
 The types of status updates for mappings. More...
 
enum  engineupdatetype {
  ENG_ENDPHASE_CON = 1, ENG_ENDPHASE_READ = 2, ENG_ENDPHASE_WRITE = 3, ENG_ENDPHASE_DISCON = 4,
  ENG_ERROR = 5, ENG_SYNC_SUCCESSFULL = 6, ENG_PREV_UNCLEAN = 7, ENG_END_CONFLICTS = 8
}
 The types of status updates for members. More...
 

Functions

osync_bool osengine_reset (OSyncEngine *engine, OSyncError **error)
 This will reset the engine to its initial state. More...
 
OSyncEngine * osengine_new (OSyncGroup *group, OSyncError **error)
 This will create a new engine for the given group. More...
 
void osengine_free (OSyncEngine *engine)
 This will free a engine and all resources associated. More...
 
void osengine_set_conflict_callback (OSyncEngine *engine, void(*function)(OSyncEngine *, OSyncMapping *, void *), void *user_data)
 This will set the conflict handler for the given engine. More...
 
void osengine_set_changestatus_callback (OSyncEngine *engine, void(*function)(OSyncEngine *, OSyncChangeUpdate *, void *), void *user_data)
 This will set the change status handler for the given engine. More...
 
void osengine_set_mappingstatus_callback (OSyncEngine *engine, void(*function)(OSyncMappingUpdate *, void *), void *user_data)
 This will set the mapping status handler for the given engine. More...
 
void osengine_set_enginestatus_callback (OSyncEngine *engine, void(*function)(OSyncEngine *, OSyncEngineUpdate *, void *), void *user_data)
 This will set the engine status handler for the given engine. More...
 
void osengine_set_memberstatus_callback (OSyncEngine *engine, void(*function)(OSyncMemberUpdate *, void *), void *user_data)
 This will set the member status handler for the given engine. More...
 
void osengine_set_message_callback (OSyncEngine *engine, void *(*function)(OSyncEngine *, OSyncClient *, const char *, void *, void *), void *user_data)
 This will set the callback handler for a custom message. More...
 
osync_bool osengine_init (OSyncEngine *engine, OSyncError **error)
 This will initialize a engine. More...
 
void osengine_finalize (OSyncEngine *engine)
 This will finalize a engine. More...
 
osync_bool osengine_synchronize (OSyncEngine *engine, OSyncError **error)
 Starts to synchronize the given OSyncEngine. More...
 
void osengine_flag_only_info (OSyncEngine *engine)
 Sets a flag on the engine that the engine should only request the info about sync objects. More...
 
void osengine_flag_manual (OSyncEngine *engine)
 Sets a flag on the engine that the engine should do single stepping (For debugging) More...
 
void osengine_pause (OSyncEngine *engine)
 This will pause the engine. More...
 
void osengine_abort (OSyncEngine *engine)
 Sets a flag on the engine that the engine should do single stepping (For debugging) More...
 
void osengine_allow_sync_alert (OSyncEngine *engine)
 Allows that the engine can be started by a member. More...
 
void osengine_deny_sync_alert (OSyncEngine *engine)
 Do not allow that the engine can be started by a member. More...
 
osync_bool osengine_sync_and_block (OSyncEngine *engine, OSyncError **error)
 This function will synchronize once and block until the sync has finished. More...
 
osync_bool osengine_wait_sync_end (OSyncEngine *engine, OSyncError **error)
 This function will block until a synchronization has ended. More...
 
void osengine_wait_info_end (OSyncEngine *engine)
 This function will block until all change object information has been received. More...
 
void osengine_one_iteration (OSyncEngine *engine)
 Does one iteration of the engine (For debugging) More...
 
OSyncMapping * osengine_mapping_from_id (OSyncEngine *engine, long long int id)
 Searches for a mapping by its id. More...
 

Detailed Description

The API of the syncengine available to everyone.

This gives you an insight in the public API of the opensync sync engine.

Enumeration Type Documentation

The types of status updates for members.

Enumerator
MEMBER_CONNECTED 

The member just connected

MEMBER_SENT_CHANGES 

The member just sent its changes

MEMBER_COMMITTED_ALL 

The member just wrote its changes

MEMBER_DISCONNECTED 

The member just disconnected

MEMBER_CONNECT_ERROR 

The member had problems connecting

MEMBER_GET_CHANGES_ERROR 

The member had problems getting the changes

MEMBER_COMMITTED_ALL_ERROR 

The member had problems getting the changes

MEMBER_SYNC_DONE_ERROR 

The member had problems during sync_done

MEMBER_DISCONNECT_ERROR 

There was an error while disconnecting

Definition at line 5 of file osengine_status.h.

The types of status updates for changes.

Enumerator
CHANGE_RECEIVED 

The change was just received

CHANGE_RECEIVED_INFO 

The change was just received (Only info)

CHANGE_SENT 

The change was just written

CHANGE_WRITE_ERROR 

There was an problem writing

CHANGE_RECV_ERROR 

There was an problem receiving the change

Definition at line 29 of file osengine_status.h.

The types of status updates for mappings.

Enumerator
MAPPING_SOLVED 

The mapping has just been solved

MAPPING_SYNCED 

The mapping has just been completely synced

MAPPING_WRITE_ERROR 

There was an error writing on of the changes

Definition at line 45 of file osengine_status.h.

The types of status updates for members.

Enumerator
ENG_ENDPHASE_CON 

All clients have connected or had an error during connection

ENG_ENDPHASE_READ 

All clients have sent their changes to the syncengine

ENG_ENDPHASE_WRITE 

All clients have written their changes

ENG_ENDPHASE_DISCON 

All clients have disconnected

ENG_ERROR 

There was an error

ENG_SYNC_SUCCESSFULL 

The sync is done and was successfull (My favorite message)

ENG_PREV_UNCLEAN 

The previous sync was unclean and the engine will perform a slow-sync now

ENG_END_CONFLICTS 

All conflicts have been reported.

Definition at line 57 of file osengine_status.h.

Function Documentation

osync_bool osengine_reset ( OSyncEngine *  engine,
OSyncError **  error 
)

This will reset the engine to its initial state.

This function will reset the engine to its initial state. The engine must not be running at this point.

Parameters
engineA pointer to the engine you want to reset
errorA pointer to a error struct
Returns
TRUE if command was succcessfull, FALSE otherwise

Definition at line 489 of file osengine_engine.c.

Referenced by osengine_new().

OSyncEngine* osengine_new ( OSyncGroup group,
OSyncError **  error 
)

This will create a new engine for the given group.

This will create a new engine for the given group

Parameters
groupA pointer to the group, for which you want to create a new engine
errorA pointer to a error struct
Returns
Pointer to a newly allocated OSyncEngine on success, NULL otherwise

Definition at line 589 of file osengine_engine.c.

void osengine_free ( OSyncEngine *  engine)

This will free a engine and all resources associated.

This will free a engine and all resources associated

Parameters
engineA pointer to the engine, which you want to free

Definition at line 693 of file osengine_engine.c.

void osengine_set_conflict_callback ( OSyncEngine *  engine,
void(*)(OSyncEngine *, OSyncMapping *, void *)  function,
void *  user_data 
)

This will set the conflict handler for the given engine.

The conflict handler will be called everytime a conflict occurs

Parameters
engineA pointer to the engine, for which to set the callback
functionA pointer to a function which will receive the conflict
user_dataPointer to some data that will get passed to the status function as the last argument

Definition at line 745 of file osengine_engine.c.

void osengine_set_changestatus_callback ( OSyncEngine *  engine,
void(*)(OSyncEngine *, OSyncChangeUpdate *, void *)  function,
void *  user_data 
)

This will set the change status handler for the given engine.

The change status handler will be called every time a new change is received, written etc

Parameters
engineA pointer to the engine, for which to set the callback
functionA pointer to a function which will receive the change status
user_dataPointer to some data that will get passed to the status function as the last argument

Definition at line 760 of file osengine_engine.c.

void osengine_set_mappingstatus_callback ( OSyncEngine *  engine,
void(*)(OSyncMappingUpdate *, void *)  function,
void *  user_data 
)

This will set the mapping status handler for the given engine.

The mapping status handler will be called every time a mapping is updated

Parameters
engineA pointer to the engine, for which to set the callback
functionA pointer to a function which will receive the mapping status
user_dataPointer to some data that will get passed to the status function as the last argument

Definition at line 775 of file osengine_engine.c.

void osengine_set_enginestatus_callback ( OSyncEngine *  engine,
void(*)(OSyncEngine *, OSyncEngineUpdate *, void *)  function,
void *  user_data 
)

This will set the engine status handler for the given engine.

The engine status handler will be called every time the engine is updated (started, stoped etc)

Parameters
engineA pointer to the engine, for which to set the callback
functionA pointer to a function which will receive the engine status
user_dataPointer to some data that will get passed to the status function as the last argument

Definition at line 790 of file osengine_engine.c.

void osengine_set_memberstatus_callback ( OSyncEngine *  engine,
void(*)(OSyncMemberUpdate *, void *)  function,
void *  user_data 
)

This will set the member status handler for the given engine.

The member status handler will be called every time a member is updated (connects, disconnects etc)

Parameters
engineA pointer to the engine, for which to set the callback
functionA pointer to a function which will receive the member status
user_dataPointer to some data that will get passed to the status function as the last argument

Definition at line 805 of file osengine_engine.c.

void osengine_set_message_callback ( OSyncEngine *  engine,
void *(*)(OSyncEngine *, OSyncClient *, const char *, void *, void *)  function,
void *  user_data 
)

This will set the callback handler for a custom message.

A custom message can be used to communicate with a plugin directly

Parameters
engineA pointer to the engine, for which to set the callback
functionA pointer to a function which will receive the member status
user_dataA pointer to some user data that the callback function will get passed

Definition at line 820 of file osengine_engine.c.

osync_bool osengine_init ( OSyncEngine *  engine,
OSyncError **  error 
)

This will initialize a engine.

After initialization, the engine will be ready to sync. The threads for the engine, the members are started. If one of the members has a listening server, the server will be started and listening.

Parameters
engineA pointer to the engine, which will be initialized
errorA pointer to a error struct
Returns
TRUE on success, FALSE otherwise. Check the error on FALSE.

Definition at line 837 of file osengine_engine.c.

void osengine_finalize ( OSyncEngine *  engine)

This will finalize a engine.

Finalizing a engine will stop all threads and listening server. The engine can be initialized again.

Parameters
engineA pointer to the engine, which will be finalized

Definition at line 960 of file osengine_engine.c.

Referenced by osengine_init().

osync_bool osengine_synchronize ( OSyncEngine *  engine,
OSyncError **  error 
)

Starts to synchronize the given OSyncEngine.

This function synchronizes a given engine. The Engine has to be created from a OSyncGroup before by using osengine_new(). This function will not block

Parameters
engineA pointer to the engine, which will be used to sync
errorA pointer to a error struct
Returns
TRUE on success, FALSE otherwise. Check the error on FALSE. Note that this just says if the sync has been started successfully, not if the sync itself was successfull

Definition at line 1023 of file osengine_engine.c.

Referenced by osengine_sync_and_block().

void osengine_flag_only_info ( OSyncEngine *  engine)

Sets a flag on the engine that the engine should only request the info about sync objects.

This can be used to see only what has changed. The engine will not request the data itself from the members. Note that some members might not support this behaviour and might send the data anyways.

Parameters
engineA pointer to the engine, for which to set the flag

Definition at line 1074 of file osengine_engine.c.

void osengine_flag_manual ( OSyncEngine *  engine)

Sets a flag on the engine that the engine should do single stepping (For debugging)

This flag can be used to set single stepping on the engine. The engine will pause after each iteration. Use osengine_one_iteration to initialize the next iteration. This is only for debugging purposes.

Parameters
engineA pointer to the engine, for which to set the flag

Definition at line 1086 of file osengine_engine.c.

void osengine_pause ( OSyncEngine *  engine)

This will pause the engine.

This flag can be used to temporarily suspend the engine

Parameters
engineA pointer to the engine, for which to set the flag

Definition at line 1100 of file osengine_engine.c.

void osengine_abort ( OSyncEngine *  engine)

Sets a flag on the engine that the engine should do single stepping (For debugging)

This flag can be used to set single stepping on the engine. The engine will pause after each iteration. Use osengine_one_iteration to initialize the next iteration. This is only for debugging purposes.

Parameters
engineA pointer to the engine, for which to set the flag

Definition at line 1112 of file osengine_engine.c.

void osengine_allow_sync_alert ( OSyncEngine *  engine)

Allows that the engine can be started by a member.

Allow the engine to by started by a member by sending a sync alert.

Parameters
engineThe engine

Definition at line 1123 of file osengine_engine.c.

void osengine_deny_sync_alert ( OSyncEngine *  engine)

Do not allow that the engine can be started by a member.

Do not allow the engine to by started by a member by sending a sync alert.

Parameters
engineThe engine

Definition at line 1134 of file osengine_engine.c.

osync_bool osengine_sync_and_block ( OSyncEngine *  engine,
OSyncError **  error 
)

This function will synchronize once and block until the sync has finished.

This can be used to sync a group and wait for the synchronization end. DO NOT USE osengine_wait_sync_end for this as this might introduce a race condition.

Parameters
engineA pointer to the engine, which to sync and wait for the sync end
errorA pointer to a error struct
Returns
TRUE on success, FALSE otherwise.

Definition at line 1149 of file osengine_engine.c.

osync_bool osengine_wait_sync_end ( OSyncEngine *  engine,
OSyncError **  error 
)

This function will block until a synchronization has ended.

This can be used to wait until the synchronization has ended. Note that this function will always block until 1 sync has ended. It can be used before the sync has started, to wait for one auto-sync to end

Parameters
engineA pointer to the engine, for which to wait for the sync end
errorReturn location for the error if the sync was not successfull
Returns
TRUE on success, FALSE otherwise.

Definition at line 1186 of file osengine_engine.c.

void osengine_wait_info_end ( OSyncEngine *  engine)

This function will block until all change object information has been received.

This will block until the information and not the data has been received.

Parameters
engineA pointer to the engine, for which to wait for the info

Definition at line 1205 of file osengine_engine.c.

void osengine_one_iteration ( OSyncEngine *  engine)

Does one iteration of the engine (For debugging)

Parameters
engineThe engine to iterate

Definition at line 1216 of file osengine_engine.c.

OSyncMapping* osengine_mapping_from_id ( OSyncEngine *  engine,
long long int  id 
)

Searches for a mapping by its id.

Parameters
engineThe engine
idThe id of the mapping
Returns
The mapping or NULL if not found

Definition at line 1228 of file osengine_engine.c.