Long Term Operation Wait Callback

This file contains the definition of a GWEN_WAITCALLBACK. More...

Virtual Functions

#define GWEN_WaitCallback_Enter(id)   GWEN_WaitCallback_Enter_u(id, __FILE__, __LINE__)
#define GWEN_WaitCallback_EnterWithText(id, txt, units, flags)   GWEN_WaitCallback_EnterWithText_u(id, txt, units, flags, __FILE__, __LINE__)
GWENHYWFAR_API GWEN_WAITCALLBACK_RESULT GWEN_WaitCallback ()
GWENHYWFAR_API void GWEN_WaitCallback_Enter_u (const char *id, const char *file, int line)
GWENHYWFAR_API void GWEN_WaitCallback_EnterWithText_u (const char *id, const char *txt, const char *units, GWEN_TYPE_UINT32 flags, const char *file, int line)
GWENHYWFAR_API void GWEN_WaitCallback_free (GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API void GWEN_WaitCallback_Leave ()
GWENHYWFAR_API void GWEN_WaitCallback_Log (GWEN_LOGGER_LEVEL logLevel, const char *s)
GWENHYWFAR_API GWEN_WAITCALLBACK_RESULT GWEN_WaitCallbackProgress (GWEN_TYPE_UINT64 pos)

Prototypes For Virtual Functions

typedef GWEN_WAITCALLBACK_RESULT(*) GWEN_WAITCALLBACK_CHECKABORTFN (GWEN_WAITCALLBACK *ctx, unsigned int level)
typedef GWEN_WAITCALLBACK *(*) GWEN_WAITCALLBACK_INSTANTIATEFN (GWEN_WAITCALLBACK *ctx)
typedef void(*) GWEN_WAITCALLBACK_LOGFN (GWEN_WAITCALLBACK *ctx, unsigned int level, GWEN_LOGGER_LEVEL loglevel, const char *s)

Informational Functions

GWENHYWFAR_API int GWEN_WaitCallback_GetDistance (const GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API GWEN_TYPE_UINT32 GWEN_WaitCallback_GetFlags (const GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API int GWEN_WaitCallback_GetNestingLevel (const GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API void GWEN_WaitCallback_SetProgressPos (GWEN_TYPE_UINT64 pos)
GWENHYWFAR_API void GWEN_WaitCallback_SetProgressTotal (GWEN_TYPE_UINT64 total)

Functions To Be Used By Inheritors

GWENHYWFAR_API const char * GWEN_WaitCallback_GetId (const GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API GWEN_TYPE_UINT64 GWEN_WaitCallback_GetProgressPos (const GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API GWEN_TYPE_UINT64 GWEN_WaitCallback_GetProgressTotal (const GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API const char * GWEN_WaitCallback_GetText (const GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API const char * GWEN_WaitCallback_GetUnits (const GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API time_t GWEN_WaitCallback_LastCalled (const GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API time_t GWEN_WaitCallback_LastEntered (const GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API GWEN_WAITCALLBACKGWEN_WaitCallback_new (const char *id)
GWENHYWFAR_API void GWEN_WaitCallback_SetCheckAbortFn (GWEN_WAITCALLBACK *ctx, GWEN_WAITCALLBACK_CHECKABORTFN fn)
GWENHYWFAR_API void GWEN_WaitCallback_SetDistance (GWEN_WAITCALLBACK *ctx, int d)
GWENHYWFAR_API void GWEN_WaitCallback_SetInstantiateFn (GWEN_WAITCALLBACK *ctx, GWEN_WAITCALLBACK_INSTANTIATEFN fn)
GWENHYWFAR_API void GWEN_WaitCallback_SetLogFn (GWEN_WAITCALLBACK *ctx, GWEN_WAITCALLBACK_LOGFN fn)

Defines

#define GWEN_WAITCALLBACK_FLAGS_IMMEDIATELY   0x00000002
#define GWEN_WAITCALLBACK_FLAGS_NO_REUSE   0x00000001
#define GWEN_WAITCALLBACK_ID_FAST   "GWEN_WAITCALLBACK_ID_FAST"
#define GWEN_WAITCALLBACK_ID_SIMPLE_PROGRESS   "GWEN_WAITCALLBACK_ID_SIMPLE_PROGRESS"
#define GWEN_WAITCALLBACK_LEVEL_REUSED   9999
#define GWEN_WAITCALLBACK_PROGRESS_NONE   ((GWEN_TYPE_UINT64)(-1))
#define GWEN_WAITCALLBACK_PROGRESS_ONE   ((GWEN_TYPE_UINT64)(-2))

Enumerations

enum  GWEN_WAITCALLBACK_RESULT { GWEN_WaitCallbackResult_Continue = 0, GWEN_WaitCallbackResult_Abort }

Functions

GWENHYWFAR_API int GWEN_WaitCallback_Register (GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API int GWEN_WaitCallback_Unregister (GWEN_WAITCALLBACK *ctx)

Detailed Description

This file contains the definition of a GWEN_WAITCALLBACK.

WaitCallbacks are called during long term operations to give the user the opportunity to abort the operation. The default implementation does nothing. But an application can use such a callback to:

Wait callbacks are organized in callback-contexts which must be entered and left.


Define Documentation

#define GWEN_WaitCallback_Enter ( id   )     GWEN_WaitCallback_Enter_u(id, __FILE__, __LINE__)

Enters the callback of the given name. If there is no callback of that name below the currently active callback context then it will be faked. This simply means that a new default context is created which still calls the currently active context (but with level!=0). If the context does exist its function GWEN_WAITCALLBACK_INSTANTIATEFN will be called and the resulting context becomes the active one.

#define GWEN_WaitCallback_EnterWithText ( id,
txt,
units,
flags   )     GWEN_WaitCallback_EnterWithText_u(id, txt, units, flags, __FILE__, __LINE__)

This macro internally calls GWEN_WaitCallback_EnterWithText_u. It therefore does the same as GWEN_WaitCallback_Enter, but it stores the given text internally to be retrieved by the implemention of a specific callback and presented to the user.

#define GWEN_WAITCALLBACK_FLAGS_IMMEDIATELY   0x00000002

Show the progress window immediately (normally some GUIs hold back the windows until after a few seconds to avoid flickering).

#define GWEN_WAITCALLBACK_FLAGS_NO_REUSE   0x00000001

Normally Gwen tries to reuse already open WaitCallbacks instead of creating new ones. If this flag is given then a new WaitCallback will be created in any case.

#define GWEN_WAITCALLBACK_ID_FAST   "GWEN_WAITCALLBACK_ID_FAST"

Use this callback id for operations which do not need a GUI. Applications should implement this callback without opening a window.

#define GWEN_WAITCALLBACK_ID_SIMPLE_PROGRESS   "GWEN_WAITCALLBACK_ID_SIMPLE_PROGRESS"

This id can be used for any simple progress operation. GUI implementations for this callback might choose to show the associated text (GWEN_WaitCallback_GetText) and provide a simple progress bar.

#define GWEN_WAITCALLBACK_LEVEL_REUSED   9999

This depth level is used upon entering of a waitcallback which is reused (because there already is a waitcallback with the enter-id). In such a case Gwen calls the the log callback function with this level and the text given to .

#define GWEN_WAITCALLBACK_PROGRESS_NONE   ((GWEN_TYPE_UINT64)(-1))

This value tells the callback mechanism that there has been no progress. It is used for keep-alive calls.

#define GWEN_WAITCALLBACK_PROGRESS_ONE   ((GWEN_TYPE_UINT64)(-2))

This value increments the progress counter by one.


Typedef Documentation

typedef GWEN_WAITCALLBACK_RESULT(*) GWEN_WAITCALLBACK_CHECKABORTFN(GWEN_WAITCALLBACK *ctx, unsigned int level)

Checks whether the user wants to abort the current action.

Parameters:
ctx context This function is optional.
level If the context given to GWEN_WaitCallback_Enter did not exist then a new default context has been created which uses the functions (like this one) of the at that time active context. For such an artificially derived context the level represents the current level below the context given as parameter ctx. So if the level is 0 then the given context actually is the currently active one.

typedef GWEN_WAITCALLBACK*(*) GWEN_WAITCALLBACK_INSTANTIATEFN(GWEN_WAITCALLBACK *ctx)

Uses the given context as a template to instantiate a new context. For GUI callbacks this function can be used to open a window (such as progress dialogs etc). This function must be set.

Parameters:
ctx context

typedef void(*) GWEN_WAITCALLBACK_LOGFN(GWEN_WAITCALLBACK *ctx, unsigned int level, GWEN_LOGGER_LEVEL loglevel, const char *s)

Logs a message to the given callback. A GUI program could use this function to write the given string to an open window. This function is optional.

Parameters:
ctx context
level see GWEN_WAITCALLBACK_CHECKABORTFN. If the level value is GWEN_WAITCALLBACK_LEVEL_REUSED then the log message is the text given to GWEN_WaitCallback_EnterWithText for reused callbacks.
loglevel a higher level results in a more detailed output. Loglevels are defined from 0 (the most important level) and 10 (the least important level). Libgwenhywfar itself does not use this function.
s log string


Enumeration Type Documentation

enum GWEN_WAITCALLBACK_RESULT

Result of GWEN_WAITCALLBACK_CHECKABORTFN.

Enumerator:
GWEN_WaitCallbackResult_Continue  tells the caller that it is ok to continue
GWEN_WaitCallbackResult_Abort  tells the caller to abort


Function Documentation

GWENHYWFAR_API GWEN_WAITCALLBACK_RESULT GWEN_WaitCallback (  ) 

Checks whether the user wants to abort the current action. This in fact calls the function GWEN_WAITCALLBACK_CHECKABORTFN stored in the current waitcallback context.

GWENHYWFAR_API void GWEN_WaitCallback_Enter_u ( const char *  id,
const char *  file,
int  line 
)

Don't call this function directly, better use the macro GWEN_WaitCallback_Enter

GWENHYWFAR_API void GWEN_WaitCallback_EnterWithText_u ( const char *  id,
const char *  txt,
const char *  units,
GWEN_TYPE_UINT32  flags,
const char *  file,
int  line 
)

Don't call this function directly, better use the macro GWEN_WaitCallback_EnterWithText

GWENHYWFAR_API void GWEN_WaitCallback_free ( GWEN_WAITCALLBACK ctx  ) 

GWENHYWFAR_API int GWEN_WaitCallback_GetDistance ( const GWEN_WAITCALLBACK ctx  ) 

Returns the proposed distance in milliseconds between two calls to the callback (defaults to 0). You can use the value returned here for a call to select(2).

Parameters:
ctx context to inspect (if 0 then the currently active one will be inspected)

GWENHYWFAR_API GWEN_TYPE_UINT32 GWEN_WaitCallback_GetFlags ( const GWEN_WAITCALLBACK ctx  ) 

Returns the flags which were given upon entering of the given context.

GWENHYWFAR_API const char* GWEN_WaitCallback_GetId ( const GWEN_WAITCALLBACK ctx  ) 

GWENHYWFAR_API int GWEN_WaitCallback_GetNestingLevel ( const GWEN_WAITCALLBACK ctx  ) 

Resturns the nesting level of the given context

GWENHYWFAR_API GWEN_TYPE_UINT64 GWEN_WaitCallback_GetProgressPos ( const GWEN_WAITCALLBACK ctx  ) 

Returns the current progress position (as set by GWEN_WaitCallback_SetProgressPos). This can be used by the callback context to correctly display a progress bar.

GWENHYWFAR_API GWEN_TYPE_UINT64 GWEN_WaitCallback_GetProgressTotal ( const GWEN_WAITCALLBACK ctx  ) 

Returns the progress total (as set by GWEN_WaitCallback_SetProgressTotal). This can be used by the callback context to correctly display a progress bar.

GWENHYWFAR_API const char* GWEN_WaitCallback_GetText ( const GWEN_WAITCALLBACK ctx  ) 

GWENHYWFAR_API const char* GWEN_WaitCallback_GetUnits ( const GWEN_WAITCALLBACK ctx  ) 

GWENHYWFAR_API time_t GWEN_WaitCallback_LastCalled ( const GWEN_WAITCALLBACK ctx  ) 

Returns the time when the callback function was last called (or 0 if it has never been called)

GWENHYWFAR_API time_t GWEN_WaitCallback_LastEntered ( const GWEN_WAITCALLBACK ctx  ) 

Returns the time when the callback context was last entered (or 0 if it never has been).

GWENHYWFAR_API void GWEN_WaitCallback_Leave (  ) 

Leaves the currently active context (by freeing it) and reinstates the previously active one.

GWENHYWFAR_API void GWEN_WaitCallback_Log ( GWEN_LOGGER_LEVEL  logLevel,
const char *  s 
)

Sends the given log string to the currently active context. Internally calls GWEN_WAITCALLBACK_LOGFN.

GWENHYWFAR_API GWEN_WAITCALLBACK* GWEN_WaitCallback_new ( const char *  id  ) 

Creates a new callback. This function should only be used by inheriting "classes".

GWENHYWFAR_API int GWEN_WaitCallback_Register ( GWEN_WAITCALLBACK ctx  ) 

GWENHYWFAR_API void GWEN_WaitCallback_SetCheckAbortFn ( GWEN_WAITCALLBACK ctx,
GWEN_WAITCALLBACK_CHECKABORTFN  fn 
)

Sets the checkAbort function (see GWEN_WAITCALLBACK_CHECKABORTFN).

GWENHYWFAR_API void GWEN_WaitCallback_SetDistance ( GWEN_WAITCALLBACK ctx,
int  d 
)

Sets the proposed distance in milliseconds between two calls to the callback. This value is never enforced by the callback mechanism itself.

GWENHYWFAR_API void GWEN_WaitCallback_SetInstantiateFn ( GWEN_WAITCALLBACK ctx,
GWEN_WAITCALLBACK_INSTANTIATEFN  fn 
)

Sets the instantiate function (see GWEN_WAITCALLBACK_INSTANTIATEFN).

GWENHYWFAR_API void GWEN_WaitCallback_SetLogFn ( GWEN_WAITCALLBACK ctx,
GWEN_WAITCALLBACK_LOGFN  fn 
)

Sets the log function (see GWEN_WAITCALLBACK_LOGFN).

GWENHYWFAR_API void GWEN_WaitCallback_SetProgressPos ( GWEN_TYPE_UINT64  pos  ) 

You can use this to feed a progress dialog. This value can later be used by the callback function to properly display a progress bar.

Parameters:
pos current progress position

GWENHYWFAR_API void GWEN_WaitCallback_SetProgressTotal ( GWEN_TYPE_UINT64  total  ) 

You can use this to initialize a progress dialog. This value can later be used by the callback function to properly display a progress bar. if the special value GWEN_WAITCALLBACK_PROGRESS_NONE is used here then no progress bar is requested. Instead a text box might be implemented by the application which shows the ProgressPos as an absolute number.

GWENHYWFAR_API int GWEN_WaitCallback_Unregister ( GWEN_WAITCALLBACK ctx  ) 

GWENHYWFAR_API GWEN_WAITCALLBACK_RESULT GWEN_WaitCallbackProgress ( GWEN_TYPE_UINT64  pos  ) 

This is basically a combination of the functions GWEN_WaitCallback_SetProgressPos and GWEN_WaitCallback.

Parameters:
pos current progress position


Generated on Sat Sep 16 11:19:16 2006 for gwenhywfar by  doxygen 1.4.7