14.32. Slapi_Task

An opaque structure that represents a task that has been initiated.
Common Directory Server tasks, including importing, exporting, and indexing databases, can be initiated through a special task configuration entry in cn=tasks,cn=config. These task operations are managed using the Slapi_Task structure.
Syntax

  

#include "slapi-plugin.h" 
typedef struct slapi_task Slapi_Task;
Associated typedefs

There are two additional typedef declarations associated with the Slapi_Task structure.

Table 14.15. typedefs for the Slapi_Task Structure

typedef Description
dseCallbackFn Sets callback information for the frontend plug-in.
TaskCallbackFn Defines a callback used by Slapi_Task cancel and destructor functions.
Associated Functions

All of the available functions for Directory Server tasks are listed in Table 14.16, “Functions for the Slapi_Task Structure”.

Table 14.16. Functions for the Slapi_Task Structure

To ... ... Call this function
Create a new server task and returns a pointer to the Slapi_Task structure. slapi_plugin_new_task()
Update a task entry to indicate that the task is running. slapi_task_begin()
Cancel a current task. slapi_task_cancel()
Decrement the task reference count. slapi_task_dec_refcount()
Write that the task is complete and returns the result code. slapi_task_finish()
Retrieve an opaque data pointer from the task. slapi_task_get_data()
Check the current reference count of the task. If a task has multiple threads, this shows whether the individual tasks have completed. slapi_task_get_refcount()
Show the current state of the task. slapi_task_get_state()
Automatically increment the task progress, which updates the task entry. slapi_task_inc_progress()
Increment the task reference count, if the task uses multiple threads. slapi_task_inc_refcount()
Write changes to a log attribute for the task entry. slapi_task_log_notice()
Update the task status attribute in the entry to maintain a running display of the task status. slapi_task_log_status()
Register a task handler function. slapi_plugin_task_register_handler()
Unregister a plug-in task. slapi_plugin_task_unregister_handler()
Set a callback to be used when a task is cancelled. slapi_task_set_cancel_fn()
Append an opaque object pointer to the task process. slapi_task_set_data()
Set a callback to be used when a task is destroyed. slapi_task_set_destructor_fn()
Contain the task's status. slapi_task_status_changed()

14.32.1. dseCallbackFn

Sets callback information for the frontend plug-in.
Syntax

  

#include "slapi-plugin.h"
typedef int (*dseCallbackFn)(Slapi_PBlock *, Slapi_Entry *, Slapi_Entry *,
                            int *, char*, void *);
Returns

This callback must return one of the following messages:

  • SLAPI_DSE_CALLBACK_OK (0) for successful operations, meaning that any directory changes can be performed.
  • SLAPI_DSE_CALLBACK_ERROR (1) for any errors, which means that any directory changes cannot be performed.
  • SLAPI_DSE_CALLBACK_DO_NOT_APPLY (-1), which is returned if there are no errors but the changes should still not be applied. This only applies for modify operations; otherwise, the server itnerprets SLAPI_DSE_CALLBACK_DO_NOT_APPLY as SLAPI_DSE_CALLBACK_ERROR.
See Also

14.32.2. TaskCallbackFn

Defines a callback used specifically by Slapi_Task structure cancel and destructor functions.
Syntax

  

#include "slapi-plugin.h"
typedef void (*TaskCallbackFn)(Slapi_Task *task);
Parameters

This function takes the following parameter:

Parameter Description
task Points to the task operation which is being performed by the server.
Returns

Currently, this callback only returns a success message (0). The actual return values for the functions are not checked by the callback.