OssoABookWaitable

OssoABookWaitable — Generic interfaces for object with asynchronous initialization.

Synopsis

                    OssoABookWaitable;
#define             OSSO_ABOOK_WAITABLE_CALLBACK        (callback)
void                (*OssoABookWaitableCallback)        (OssoABookWaitable *waitable,
                                                         const GError *error,
                                                         gpointer data);
                    OssoABookWaitableIface;
OssoABookWaitableClosure* osso_abook_waitable_call_when_ready
                                                        (OssoABookWaitable *waitable,
                                                         OssoABookWaitableCallback callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy);
gboolean            osso_abook_waitable_cancel          (OssoABookWaitable *waitable,
                                                         OssoABookWaitableClosure *closure);
void                osso_abook_waitable_run             (OssoABookWaitable *waitable,
                                                         GMainContext *context,
                                                         GError **error);
void                osso_abook_waitable_notify          (OssoABookWaitable *waitable,
                                                         const GError *error);
void                osso_abook_waitable_reset           (OssoABookWaitable *waitable);
gboolean            osso_abook_waitable_is_ready        (OssoABookWaitable *waitable,
                                                         GError **error);

Object Hierarchy

  GInterface
   +----OssoABookWaitable

Known Derived Interfaces

OssoABookWaitable is required by OssoABookRosterManager.

Known Implementations

OssoABookWaitable is implemented by OssoABookAggregator, OssoABookRoster and OssoABookAccountManager.

Description

This interface provides a generic method for object with asynchronous initialization to inform their clients that they finished initialization.

In order to implement OssoABookWaitable, derived classes should implement a stack of opaque closures (OssoABookWaitableClosure) and the virtual push() and pop() methods for adding or removing closures from the stack. Inherited classes should indicate that they have become ready by calling osso_abook_waitable_notify().

Details

OssoABookWaitable

typedef struct _OssoABookWaitable OssoABookWaitable;

Dummy type for the OssoABookWaitableIface

OSSO_ABOOK_WAITABLE_CALLBACK()

#define             OSSO_ABOOK_WAITABLE_CALLBACK(callback)

OssoABookWaitableCallback ()

void                (*OssoABookWaitableCallback)        (OssoABookWaitable *waitable,
                                                         const GError *error,
                                                         gpointer data);

The type of function that is called when a OssoABookWaitable object becomes ready.

waitable : a OssoABookWaitable that became ready
error : NULL on success, or a GError to report error status
data : additional data registered with osso_abook_waitable_call_when_ready()

OssoABookWaitableIface

typedef struct {
        gboolean                   (* is_ready) (OssoABookWaitable         *waitable,
                                                 const GError             **error);

        void                       (* push)     (OssoABookWaitable         *waitable,
                                                 OssoABookWaitableClosure  *closure);

        OssoABookWaitableClosure * (* pop)      (OssoABookWaitable         *waitable,
                                                 OssoABookWaitableClosure  *closure);
} OssoABookWaitableIface;

Virtual methods of the OssoABookWaitable interface.

is_ready () virtual method for osso_abook_waitable_is_ready()
push () virtual method for pushing a OssoABookWaitableClosure onto the stack
pop () virtual method for poppping a OssoABookWaitableClosure from the stack

osso_abook_waitable_call_when_ready ()

OssoABookWaitableClosure* osso_abook_waitable_call_when_ready
                                                        (OssoABookWaitable *waitable,
                                                         OssoABookWaitableCallback callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy);

Registers the specified callback to be executed when waitable becomes ready. The meaning of 'ready' is dependant on the concrete implementation classes, but once a OssoABookWaitable object becomes ready it does not becom 'unready' again. If waitable is already ready when this function is called, callback will be executed immediately.

OssoABookWaitable : a OssoABookWaitable
callback : a function to call when ready
user_data : additional data to pass to callback
destroy : an optional function to free user_data when no longer needed
Returns : an opaque closure that can be used later to cancel this registration by calling osso_abook_waitable_cancel().

osso_abook_waitable_cancel ()

gboolean            osso_abook_waitable_cancel          (OssoABookWaitable *waitable,
                                                         OssoABookWaitableClosure *closure);

Cancels a previously-registered callback and frees its user data if destroy was specified

waitable : a OssoABookWaitable
closure : a return value from osso_abook_waitable_call_when_ready()
Returns : TRUE if cancel was successful, else FALSE (for example if closure was already called or cancelled)

osso_abook_waitable_run ()

void                osso_abook_waitable_run             (OssoABookWaitable *waitable,
                                                         GMainContext *context,
                                                         GError **error);

This function simply spins a main loop in context until waitable has become ready.

waitable : a OssoABookWaitable
context : a GMainContext to run in
error : return location for an error or NULL on success

osso_abook_waitable_notify ()

void                osso_abook_waitable_notify          (OssoABookWaitable *waitable,
                                                         const GError *error);

Derived classes will call this function in order to indicate that they have transitioned to 'ready'. This function should never be called from outside the implementation of a derived class (to protect agains this, this function will call osso_abook_waitable_is_ready() and if it returns FALSE, waitable will not be considered ready and the registered callbacks will not be executed).

This function will return before the registered callbacks are executed. The callbacks will be executed in an idle handler, and the error parameter will be passed to each callback.

waitable : a OssoABookWaitable
error : a parameter for indicating an error

osso_abook_waitable_reset ()

void                osso_abook_waitable_reset           (OssoABookWaitable *waitable);

Resets waitable by removing all registered callbacks without executing them.

waitable : a OssoABookWaitable

osso_abook_waitable_is_ready ()

gboolean            osso_abook_waitable_is_ready        (OssoABookWaitable *waitable,
                                                         GError **error);

Checks whether waitable is ready or not.

waitable : a OssoABookWaitable
error : a return location for error reporting
Returns : TRUE if waitable is ready, else FALSE
Generated by GTK-Doc V1.10