Long Term Operation Wait Callback
[Basic Stuff]

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

Virtual Functions

#define GWEN_WaitCallback_Enter(id)   GWEN_WaitCallback_Enter_u(id, __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_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 (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 (GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API GWEN_TYPE_UINT64 GWEN_WaitCallback_GetProgressPos (GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API GWEN_TYPE_UINT64 GWEN_WaitCallback_GetProgressTotal (GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API time_t GWEN_WaitCallback_LastCalled (GWEN_WAITCALLBACK *ctx)
GWENHYWFAR_API time_t GWEN_WaitCallback_LastEntered (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_PROGRESS_NONE   ((GWEN_TYPE_UINT64)(0xffffffffffffffff))

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_PROGRESS_NONE   ((GWEN_TYPE_UINT64)(0xffffffffffffffff))
 


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
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
 

GWENHYWFAR_API void GWEN_WaitCallback_free GWEN_WAITCALLBACK ctx  ) 
 

GWENHYWFAR_API int GWEN_WaitCallback_GetDistance 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 const char* GWEN_WaitCallback_GetId 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 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 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 time_t GWEN_WaitCallback_LastCalled 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 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.

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 Fri Mar 10 08:15:20 2006 for gwenhywfar by  doxygen 1.4.6