333 lines
15 KiB
C++
333 lines
15 KiB
C++
// CkTaskW.h: interface for the CkTaskW class.
|
|
//
|
|
//////////////////////////////////////////////////////////////////////
|
|
|
|
// This header is generated for Chilkat 11.3.0
|
|
|
|
#ifndef _CkTaskW_H
|
|
#define _CkTaskW_H
|
|
|
|
#include "chilkatDefs.h"
|
|
#include "CkString.h"
|
|
#include "CkClassWithCallbacksW.h"
|
|
|
|
class CkByteData;
|
|
class CkBaseProgressW;
|
|
|
|
|
|
|
|
#if !defined(__sun__) && !defined(__sun)
|
|
#pragma pack (push, 8)
|
|
#endif
|
|
|
|
|
|
// CLASS: CkTaskW
|
|
class CK_VISIBLE_PUBLIC CkTaskW : public CkClassWithCallbacksW
|
|
{
|
|
private:
|
|
bool m_cbOwned;
|
|
|
|
private:
|
|
|
|
// Don't allow assignment or copying these objects.
|
|
CkTaskW(const CkTaskW &);
|
|
CkTaskW &operator=(const CkTaskW &);
|
|
|
|
public:
|
|
CkTaskW(void);
|
|
virtual ~CkTaskW(void);
|
|
|
|
|
|
|
|
static CkTaskW *createNew(void);
|
|
|
|
|
|
CkTaskW(bool bCallbackOwned);
|
|
static CkTaskW *createNew(bool bCallbackOwned);
|
|
|
|
|
|
void CK_VISIBLE_PRIVATE inject(void *impl);
|
|
|
|
// May be called when finished with the object to free/dispose of any
|
|
// internal resources held by the object.
|
|
void dispose(void);
|
|
|
|
CkBaseProgressW *get_EventCallbackObject(void) const;
|
|
void put_EventCallbackObject(CkBaseProgressW *progress);
|
|
|
|
|
|
// BEGIN PUBLIC INTERFACE
|
|
|
|
// ----------------------
|
|
// Properties
|
|
// ----------------------
|
|
// true if the task status is canceled , aborted , or completed . A task can only
|
|
// reach the canceled status if it was activated via the Run method, made it onto
|
|
// the internal thread pool thread's queue, was waiting for a pool thread to become
|
|
// available, and was then canceled prior to the task actually starting.
|
|
bool get_Finished(void);
|
|
|
|
// The number of milliseconds between each AbortCheck event callback. The
|
|
// AbortCheck callback allows an application to abort the Wait method. If
|
|
// HeartbeatMs is 0 (the default), no AbortCheck event callbacks will fire. Note:
|
|
// An asynchronous task running in a background thread (in one of the thread pool
|
|
// threads) does not fire events. The task's event callbacks pertain only to the
|
|
// Wait method.
|
|
int get_HeartbeatMs(void);
|
|
// The number of milliseconds between each AbortCheck event callback. The
|
|
// AbortCheck callback allows an application to abort the Wait method. If
|
|
// HeartbeatMs is 0 (the default), no AbortCheck event callbacks will fire. Note:
|
|
// An asynchronous task running in a background thread (in one of the thread pool
|
|
// threads) does not fire events. The task's event callbacks pertain only to the
|
|
// Wait method.
|
|
void put_HeartbeatMs(int newVal);
|
|
|
|
// true if the task status is empty or loaded . When a task is inert, it has been
|
|
// loaded but is not scheduled to run yet.
|
|
bool get_Inert(void);
|
|
|
|
// Determines if the in-memory progress info event log is kept. The default value
|
|
// is false and therefore no log is kept. To enable progress info logging, set
|
|
// this property equal to true (prior to running the task).
|
|
bool get_KeepProgressLog(void);
|
|
// Determines if the in-memory progress info event log is kept. The default value
|
|
// is false and therefore no log is kept. To enable progress info logging, set
|
|
// this property equal to true (prior to running the task).
|
|
void put_KeepProgressLog(bool newVal);
|
|
|
|
// true if the task status is queued or running . When a task is live, it is
|
|
// either already running, or is on the thread pool thread's queue waiting for a
|
|
// thread to become available.
|
|
bool get_Live(void);
|
|
|
|
// Indicates the percent completion while the task is running. The percent
|
|
// completed information is only available in cases where it is possible to know
|
|
// the percentage completed. For some methods, it is never possible to know, such
|
|
// as for methods that establish TCP or TLS connections. For other methods it is
|
|
// always possible to know -- such as for sending email (because the size of the
|
|
// email to be sent is already known). For some methods, it may or may not be
|
|
// possible to know the percent completed. For example, if an HTTP response is
|
|
// chunked , there is no Content-Length header and therefore the receiver has no
|
|
// knowledge of the size of the forthcoming response body.
|
|
//
|
|
// Also, the value of the PercentDoneScale property of the asynchronous method's
|
|
// object determines the scale, such as 0 to 100, or 0 to 1000, etc.
|
|
//
|
|
int get_PercentDone(void);
|
|
|
|
// What would normally be a ProgressInfo event callback (assuming Chilkat supports
|
|
// event callbacks for this language) is instead saved to an in-memory progress log
|
|
// that can be examined and pruned while the task is still running. This property
|
|
// returns the number of progress log entries that are currently available. (Note:
|
|
// the progress log is only kept if the KeepProgressLog property is turned on. By
|
|
// default, the KeepProgressLog is turned off.)
|
|
int get_ProgressLogSize(void);
|
|
|
|
// The LastErrorText for the task's asynchronous method.
|
|
void get_ResultErrorText(CkString &str);
|
|
// The LastErrorText for the task's asynchronous method.
|
|
const wchar_t *resultErrorText(void);
|
|
|
|
// Indicates the data type of the task's result. This property is only available
|
|
// after the task has completed. Possible values are bool , int , string , bytes ,
|
|
// object , and void . For example, if the result data type is bool , then call
|
|
// GetResultBool to get the boolean result of the underlying asynchronous method.
|
|
//
|
|
// For example, if the synchronous version of the method returned a boolean, then
|
|
// in the asynchronous version of the method, the boolean return value is made
|
|
// available via the GetResultBool method.
|
|
//
|
|
void get_ResultType(CkString &str);
|
|
// Indicates the data type of the task's result. This property is only available
|
|
// after the task has completed. Possible values are bool , int , string , bytes ,
|
|
// object , and void . For example, if the result data type is bool , then call
|
|
// GetResultBool to get the boolean result of the underlying asynchronous method.
|
|
//
|
|
// For example, if the synchronous version of the method returned a boolean, then
|
|
// in the asynchronous version of the method, the boolean return value is made
|
|
// available via the GetResultBool method.
|
|
//
|
|
const wchar_t *resultType(void);
|
|
|
|
// The current status of the task. Possible values are:
|
|
// * empty -- The method call and arguments are not yet loaded into the task
|
|
// object. This can only happen if a task was explicitly created instead of being
|
|
// returned by a method ending in Async .
|
|
// * loaded -- The method call and arguments are loaded into the task object.
|
|
// * queued -- The task is in the thread pool's queue of tasks awaiting to be
|
|
// run.
|
|
// * running -- The task is currently running.
|
|
// * canceled -- The task was canceled before it entered the running state.
|
|
// * aborted -- The task was canceled while it was in the running state.
|
|
// * completed -- The task completed. The success or failure depends on the
|
|
// semantics of the method call and the value of the result.
|
|
void get_Status(CkString &str);
|
|
// The current status of the task. Possible values are:
|
|
// * empty -- The method call and arguments are not yet loaded into the task
|
|
// object. This can only happen if a task was explicitly created instead of being
|
|
// returned by a method ending in Async .
|
|
// * loaded -- The method call and arguments are loaded into the task object.
|
|
// * queued -- The task is in the thread pool's queue of tasks awaiting to be
|
|
// run.
|
|
// * running -- The task is currently running.
|
|
// * canceled -- The task was canceled before it entered the running state.
|
|
// * aborted -- The task was canceled while it was in the running state.
|
|
// * completed -- The task completed. The success or failure depends on the
|
|
// semantics of the method call and the value of the result.
|
|
const wchar_t *status(void);
|
|
|
|
// The current status of the task as an integer value. Possible values are:
|
|
// * 1 -- The method call and arguments are not yet loaded into the task
|
|
// object. This can only happen if a task was explicitly created instead of being
|
|
// returned by a method ending in Async .
|
|
// * 2 -- The method call and arguments are loaded into the task object.
|
|
// * 3 -- The task is in the thread pool's queue of tasks awaiting to be run.
|
|
// * 4 -- The task is currently running.
|
|
// * 5 -- The task was canceled before it entered the running state.
|
|
// * 6 -- The task was canceled while it was in the running state.
|
|
// * 7 -- The task completed. The success or failure depends on the semantics
|
|
// of the method call and the value of the result.
|
|
int get_StatusInt(void);
|
|
|
|
// A unique integer ID assigned to this task. The purpose of this property is to
|
|
// help an application identify the task if a TaskCompleted event callback is used.
|
|
int get_TaskId(void);
|
|
|
|
// This is the value of the LastMethodSuccess property of the underlying task
|
|
// object. This property is only valid for those methods where the
|
|
// LastMethodSuccess property would be valid had the method been called
|
|
// synchronously.
|
|
//
|
|
// Important: This property is only meaningful for cases where the underlying
|
|
// method call has a non-boolean return value (such as for methods that return
|
|
// strings, other Chilkat objects, or integers). If the underlying method call
|
|
// returns a boolean, then call the GetResultBool() method instead to get the
|
|
// boolean return value.
|
|
//
|
|
bool get_TaskSuccess(void);
|
|
|
|
// An application may use this property to attach some user-specific information
|
|
// with the task, which may be useful if a TaskCompleted event callback is used.
|
|
void get_UserData(CkString &str);
|
|
// An application may use this property to attach some user-specific information
|
|
// with the task, which may be useful if a TaskCompleted event callback is used.
|
|
const wchar_t *userData(void);
|
|
// An application may use this property to attach some user-specific information
|
|
// with the task, which may be useful if a TaskCompleted event callback is used.
|
|
void put_UserData(const wchar_t *newVal);
|
|
|
|
|
|
|
|
// ----------------------
|
|
// Methods
|
|
// ----------------------
|
|
// Marks an asynchronous task for cancellation. The expected behavior depends on
|
|
// the current status of the task as described here:
|
|
// * loaded - If the task has been loaded but has not yet been queued to run in
|
|
// the thread pool, then there is nothing to do. (There is nothing to cancel
|
|
// because the task's Run method has not yet been called.) The task will remain in
|
|
// the loaded state.
|
|
// * queued - The task is marked for cancellation, is dequeued, and will not
|
|
// run. The task's status changes immediately to canceled .
|
|
// * running - The already-running task is marked for cancellation. The task's
|
|
// status will eventually change to aborted when the asynchronous method
|
|
// returns. At that point in time, the ResultErrorText property will contain
|
|
// the LastErrorText of the method call. In the case where a task is marked for
|
|
// cancellation just at the time it's completing, the task status may instead
|
|
// change to completed .
|
|
// * canceled , aborted , completed - In these cases the task has already
|
|
// finished, and there will be no change in status.
|
|
// Cancel returns true if the task was in the queued or running state when it was
|
|
// marked for cancellation. Cancel returns false if the task was in any other
|
|
// state.
|
|
//
|
|
// Important: Calling the Cancel method marks a task for cancellation. It sets a
|
|
// flag in memory that the running task will soon notice and then abort. It is
|
|
// important to realize that your application is likely calling Cancel from the
|
|
// main UI thread, whereas the asynchronous task is running in a background thread.
|
|
// If the task was in the running state when Cancel was called, it will still be in
|
|
// the running state when Cancel returns. It will take a short amount of time until
|
|
// the task actually aborts. This is because operating systems schedule threads in
|
|
// time slices, and the thread needs one or more time slices to notice the
|
|
// cancellation flag and abort. After calling Cancel, your application might wish
|
|
// to call the Wait method to wait until the task has actually aborted, or it could
|
|
// periodically check the task's status and then react once the status changes to
|
|
// aborted .
|
|
//
|
|
bool Cancel(void);
|
|
|
|
// Removes all entries from the progress info log.
|
|
void ClearProgressLog(void);
|
|
|
|
// Returns the binary bytes result of the task. The bytes are copied to the caller.
|
|
bool CopyResultBytes(CkByteData &outBytes);
|
|
|
|
// Returns the boolean result of the task.
|
|
bool GetResultBool(void);
|
|
|
|
// Returns the binary bytes result of the task. The bytes are transferred to the
|
|
// caller, not copied. Call CopyResultBytes instead to copy the result bytes.
|
|
bool GetResultBytes(CkByteData &outBytes);
|
|
|
|
// Returns the integer result of the task.
|
|
int GetResultInt(void);
|
|
|
|
// Returns the string result of the task.
|
|
bool GetResultString(CkString &outStr);
|
|
// Returns the string result of the task.
|
|
const wchar_t *getResultString(void);
|
|
// Returns the string result of the task.
|
|
const wchar_t *resultString(void);
|
|
|
|
// Returns the name of the Nth progress info event logged. The 1st entry is at
|
|
// index 0.
|
|
bool ProgressInfoName(int index, CkString &outStr);
|
|
// Returns the name of the Nth progress info event logged. The 1st entry is at
|
|
// index 0.
|
|
const wchar_t *progressInfoName(int index);
|
|
|
|
// Returns the value of the Nth progress info event logged. The 1st entry is at
|
|
// index 0.
|
|
bool ProgressInfoValue(int index, CkString &outStr);
|
|
// Returns the value of the Nth progress info event logged. The 1st entry is at
|
|
// index 0.
|
|
const wchar_t *progressInfoValue(int index);
|
|
|
|
// Removes the Nth progress info log entry.
|
|
void RemoveProgressInfo(int index);
|
|
|
|
// {=nodejs}If a taskCompleted callback function is passed in, then the task is
|
|
// started on Node's internal thread pool. If no callback function is passed, then
|
|
// the task is run synchronously. {nodejs=} {=other}Queues the task to run on the
|
|
// internal Chilkat thread pool.{other=}
|
|
bool Run(void);
|
|
|
|
// Runs the task synchronously. Then this method returns after the task has been
|
|
// run.
|
|
bool RunSynchronously(void);
|
|
|
|
// Convenience method to force the calling thread to sleep for a number of
|
|
// milliseconds. (This does not cause the task's background thread to sleep.)
|
|
void SleepMs(int numMs);
|
|
|
|
// Waits for the task to complete. Returns when task has completed, or after maxWaitMs
|
|
// milliseconds have elapsed. (A maxWaitMs value of 0 is to wait indefinitely.) Returns
|
|
// (false) if the task has not yet been started by calling the Run method, or if
|
|
// the maxWaitMs expired. If the task completed, was already completed, was canceled or
|
|
// aborted, then this method returns true.
|
|
bool Wait(int maxWaitMs);
|
|
|
|
|
|
|
|
|
|
|
|
// END PUBLIC INTERFACE
|
|
|
|
|
|
};
|
|
#if !defined(__sun__) && !defined(__sun)
|
|
#pragma pack (pop)
|
|
#endif
|
|
|
|
#endif
|