<commit_before>\chapter{Synchronization Plugins}
Synchronization Plugins are modules which provides access to a certain device,
application or protocol. All of those plugins provide independent of the
synchronized content/format or connection type, the same functions:
\begin{itemize}
\item initialize. This function parse the plugin configuration and initializes
the plugin. If the plugin acts as server, it also initializes this one and 
listen for incoming connections.
\item finalize. This function releases all gained memory by the plugin and stops
the listening server if present. 
\item discover. This function is intended to get called initially to gain
information about the target application, device or system. In detail it detects
all supported formats and individual capabilities of this format, if possible.
And basic information about the target application/device like version, vendor,
product, etc. ...
%\item usable. This function is intended to check if the target
%application/device is usable.
\end{itemize}

\begin{figure}
 \centering
 \includegraphics[bb=0 0 661 960, scale=0.60]{simple-sync-sequence}
 % simple-sync-sequence.png: 661x960 pixel, 72dpi, 23.32x33.87 cm, bb=0 0 661 960
 \caption{Plugin Synchronization Sequence}
 \label{fig:SimpleSyncSequence}
\end{figure}

Those function are called "Generic Functions" and MUST be implemented by 
plugin.

\section{Generic Functions}
The Generic Functions are the only functions, which got called synchronously by 
the OpenSync Framework.
\subsection{Initialization}
\subsection{Finalize}
\subsection{Discover}
%\subsection{Usable}
\section{Sink Functions}
All ">Sink Functions"< are called asynchronously, not like the "Generic
Functions", and have to reply with OSyncContext functions if the task was 
executed or not. It's very important that the ">Sink Functions"< reply the
request by the OpenSync Framework with the OSyncContext functions. Even on
error condition the Sink Function have to reply with a special OSyncContext
error function. Otherwise the OpenSync Framework until the timeout for this
function call is reached, which may take sometime for some usually time 
consuming functions\\
The Main Sink, which is Object Type neutral, doesn't have any required Sink 
Functions. For the Object Type Sink are the implementation of some Sink 
Functions required:

\begin{center}
% use packages: array
\begin{tabular}{ll}
\textbf{Function} & \textbf{Implementation} \\ 
Connect & O \\ 
Get Changes & M \\ 
Commit / Batch Commit & M (only Commit \textbf{or} Batch Commit) \\ 
Committed All & O (only available in combination with Commit)\\ 
Synchronization Done & O \\ 
Disconnect & O
\end{tabular}
\end{center}

The Plugin don't have to register a Main Sink if there is no need for Object 
Type neutral tasks.
\subsection{Connect}
The Connect function is available for all Object Type Sinks and could be used to
establish Object Type specific connection. If the connection establishment is an
Object Type neutral task (e.g. Bluetooth, USB, ...) and needded to be done only
once, only the Main Sink should be used. This avoids problems with shared access
to an interface, since a connect function would be called for each Object Type
for the same interface.\\
This function MUST only establish a connection to the device or ressource. After
the connection got established successful the plugin MUST reply the context with
\verb|osync_context_reply_success()|. On error the plugin replies a 
human-readable
(aka. userfriendly) error message with \verb|osync_context_reply_error()|.
\subsection{Get Changes}
The Get Changes function get called by the OpenSync Framework to request changes
since last synchronization or all entries of the Object Type specific ressource.
Later one MUST be done when a Slow Sync got requested by the OpenSync
Synchronization framework. If a Slow Sync got requested for this Sink MUST be
checked with \verb|osync_objtype_sink_get_slowsync()|. On a Slow Sync the 
Changetype (for all changes) is \verb|OSYNC_CHANGE_TYPE_ADDED|. On a regular 
(fast sync) synchronization it's up to the Get Changes function to determine 
the Changetype. Every change have to be reported with 
\verb|osync_context_report_change()|. On a error the Sink Function have to 
reply the context with \verb|osync_context_report_error()| and stop/leave this 
function ASAP. If the protocol, application or device isn't able to report 
changed entries since last sync, the OpenSync Helper Hashtable should be used 
to determine the Changetype of the entry.
\subsection{Commit}
This function get called with a single OSyncChange object, which MUST be
committed to the application or device. If the commit failed the context MUST be
replied with \verb|osync_context_report_error()|. On success the context get 
replied with \verb|osync_context_success()|. If Hashtable is already involved in
the Get Changes functions, then the Commit function has to update the entries 
for the Hashtable for entries which get committed.
\subsection{Batch Commit}
The batch commit function is intended for protocols, device or application which
only allow batch committing (sending all changes at once). This function get
called with an array of changes which have of be committed all at once.
\subsection{Committed All}
This function got called after all entries got committed, even if error appeared
while committing. This function get not called if Batch Commit function is
registered for this Sink.
\subsection{Synchronization Done}
This function got called only after a successful synchronization.
\subsection{Disconnect}
This function MUST only handle the disconnect of the sink. Don't do further
cleanup here, the finalize function is intended for releasing memory and
cleanup. The disconnect function might never get called when even the connect
function failed.
\section{Properties}
Each Synchronization Plugin has properties which get set within the
\verb|get_sync_info()| function. The properties are:

\begin{itemize}
\item Name, short name of the plugin should be less then 15 characters. This
name isn't visible to the user, at least not for rich OpenSync Frontends.
\item Longname, is the name of the plugin which is visible to the user in
rich OpenSync frontends. Should not be longer then 50 characters.
\item Description, about the Plugin visible to the end user in OpenSync
Frontends, and should additionally help to choose the right plugin.
\item Configuration Type, defines if the plugins needs any configuration or if
the configuration is optional or simply not needed.
\item Process Type, defines how the plugin get started: threaded, forked or by <commit_msg>Mention the use osync_hashtable_save() for the plugin sync_done() function.<commit_after>\chapter{Synchronization Plugins}
Synchronization Plugins are modules which provides access to a certain device,
application or protocol. All of those plugins provide independent of the
synchronized content/format or connection type, the same functions:
\begin{itemize}
\item initialize. This function parse the plugin configuration and initializes
the plugin. If the plugin acts as server, it also initializes this one and 
listen for incoming connections.
\item finalize. This function releases all gained memory by the plugin and stops
the listening server if present. 
\item discover. This function is intended to get called initially to gain
information about the target application, device or system. In detail it detects
all supported formats and individual capabilities of this format, if possible.
And basic information about the target application/device like version, vendor,
product, etc. ...
%\item usable. This function is intended to check if the target
%application/device is usable.
\end{itemize}

\begin{figure}
 \centering
 \includegraphics[bb=0 0 661 960, scale=0.60]{simple-sync-sequence}
 % simple-sync-sequence.png: 661x960 pixel, 72dpi, 23.32x33.87 cm, bb=0 0 661 960
 \caption{Plugin Synchronization Sequence}
 \label{fig:SimpleSyncSequence}
\end{figure}

Those function are called "Generic Functions" and MUST be implemented by 
plugin.

\section{Generic Functions}
The Generic Functions are the only functions, which got called synchronously by 
the OpenSync Framework.
\subsection{Initialization}
\subsection{Finalize}
\subsection{Discover}
%\subsection{Usable}
\section{Sink Functions}
All ">Sink Functions"< are called asynchronously, not like the "Generic
Functions", and have to reply with OSyncContext functions if the task was 
executed or not. It's very important that the ">Sink Functions"< reply the
request by the OpenSync Framework with the OSyncContext functions. Even on
error condition the Sink Function have to reply with a special OSyncContext
error function. Otherwise the OpenSync Framework until the timeout for this
function call is reached, which may take sometime for some usually time 
consuming functions\\
The Main Sink, which is Object Type neutral, doesn't have any required Sink 
Functions. For the Object Type Sink are the implementation of some Sink 
Functions required:

\begin{center}
% use packages: array
\begin{tabular}{ll}
\textbf{Function} & \textbf{Implementation} \\ 
Connect & O \\ 
Get Changes & M \\ 
Commit / Batch Commit & M (only Commit \textbf{or} Batch Commit) \\ 
Committed All & O (only available in combination with Commit)\\ 
Synchronization Done & O \\ 
Disconnect & O
\end{tabular}
\end{center}

The Plugin don't have to register a Main Sink if there is no need for Object 
Type neutral tasks.
\subsection{Connect}
The Connect function is available for all Object Type Sinks and could be used to
establish Object Type specific connection. If the connection establishment is an
Object Type neutral task (e.g. Bluetooth, USB, ...) and needded to be done only
once, only the Main Sink should be used. This avoids problems with shared access
to an interface, since a connect function would be called for each Object Type
for the same interface.\\
This function MUST only establish a connection to the device or ressource. After
the connection got established successful the plugin MUST reply the context with
\verb|osync_context_reply_success()|. On error the plugin replies a 
human-readable
(aka. userfriendly) error message with \verb|osync_context_reply_error()|.
\subsection{Get Changes}
The Get Changes function get called by the OpenSync Framework to request changes
since last synchronization or all entries of the Object Type specific ressource.
Later one MUST be done when a Slow Sync got requested by the OpenSync
Synchronization framework. If a Slow Sync got requested for this Sink MUST be
checked with \verb|osync_objtype_sink_get_slowsync()|. On a Slow Sync the 
Changetype (for all changes) is \verb|OSYNC_CHANGE_TYPE_ADDED|. On a regular 
(fast sync) synchronization it's up to the Get Changes function to determine 
the Changetype. Every change have to be reported with 
\verb|osync_context_report_change()|. On a error the Sink Function have to 
reply the context with \verb|osync_context_report_error()| and stop/leave this 
function ASAP. If the protocol, application or device isn't able to report 
changed entries since last sync, the OpenSync Helper Hashtable should be used 
to determine the Changetype of the entry.
\subsection{Commit}
This function get called with a single OSyncChange object, which MUST be
committed to the application or device. If the commit failed the context MUST be
replied with \verb|osync_context_report_error()|. On success the context get 
replied with \verb|osync_context_success()|. If Hashtable is already involved in
the Get Changes functions, then the Commit function has to update the entries 
for the Hashtable for entries which get committed.
\subsection{Batch Commit}
The batch commit function is intended for protocols, device or application which
only allow batch committing (sending all changes at once). This function get
called with an array of changes which have of be committed all at once.
\subsection{Committed All}
This function got called after all entries got committed, even if error appeared
while committing. This function get not called if Batch Commit function is
registered for this Sink.
\subsection{Synchronization Done}
This function got called only after a successful synchronization.
When using Hashtable \verb|osync_hashtable_save()| should get called, to
do persistent store of the Hashtable.
\subsection{Disconnect}
This function MUST only handle the disconnect of the sink. Don't do further
cleanup here, the finalize function is intended for releasing memory and
cleanup. The disconnect function might never get called when even the connect
function failed.
\section{Properties}
Each Synchronization Plugin has properties which get set within the
\verb|get_sync_info()| function. The properties are:

\begin{itemize}
\item Name, short name of the plugin should be less then 15 characters. This
name isn't visible to the user, at least not for rich OpenSync Frontends.
\item Longname, is the name of the plugin which is visible to the user in
rich OpenSync frontends. Should not be longer then 50 characters.
\item Description, about the Plugin visible to the end user in OpenSync
Frontends, and should additionally help to choose the right plugin.
\item Configuration Type, defines if the plugins needs any configuration or if
the configuration is optional or simply not needed.
\item Process Type, defines how the plugin get started: threaded, forked or by 
{'fraction_non_alphanumeric': 0.05038270045329568, 'fraction_numerical': 0.0057962398751579105, 'mean_word_length': 4.949602122015915, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3191385', 'n_tokens_mistral': 3466, 'n_tokens_neox': 3339, 'n_words': 1870}