# 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_WAITCALLBACK * | GWEN_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:

- Check whether the user wants to abort
- Update a GUI thus preventing X toolkits such as QT from freezing

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