News. - What is DAR? - The bindings. - API Documentation. - Related works. - Project site. - What is the logo? - Public key.
Main Page   Modules   Data Structures   File List   Data Fields   Globals  

User interaction
[Class_wrapper]

The libdar library uses the class user_interaction for performing interactive input and output during operation execution. More...

Data Structures

struct  dar_user_interaction_struct
 Storage container for passing callback functions to the library. More...


Typedefs

typedef void *(* dar_warning_callback )(char *msg, void *context)
 Callback signature for function used to display a warning or message to the use.

typedef bool(* dar_answer_callback )(char *msg, void *context)
 Callback signature for function used to query the user for a "yes" or "no" answer.

typedef char *(* dar_string_callback )(char *msg, bool echo, void *context)
 Callback signature for function used to query the user for a string.

typedef void *(* dar_listing_callback )(char *flag, char *perm, char *uid, char *gid, char *size, char *date, char *filename, bool is_dir, bool has_children, void *context)
 Callback signature for function used to send detailed listing information to the library client.


Functions

NAMESPACE_LIBDAR_START bool dar_user_interaction_struct_is_valid (dar_user_interaction_struct obj)
 Returns true if the required callbacks are implemented.

Detailed Description

The libdar library uses the class user_interaction for performing interactive input and output during operation execution.

In the C++ library interaction can be implemented by overriding the class or creating callbacks using function pointers.

The C binding allows callback implementation using function pointers only. The signatures for these callbacks are defined as typedefs and can be passed to library calls using a container struct.

Not all callbacks are required. The primary callbacks dar_warning_callback, dar_answer_callback, and dar_string_callback must be implemented. If seperated listing information is desired, dar_listing_callback may be implemented. If this optional callback is not desired, the field in the container structure may be set to NULL.

Before passing the callback to a library call it is possible to check if it is valid using the function dar_user_interaction_struct_is_valid.

Typedef Documentation

typedef bool(* dar_answer_callback)(char* msg, void* context)
 

Callback signature for function used to query the user for a "yes" or "no" answer.

This is the equivalent to the libdary function pause. Is is renamed to provide a clearer idea of what it does.

Parameters:
msg  The question posed by the library. String will be freed by caller.
context  An arbitrary value or object belonging to the library user. Can be used to store configuration parameters or contextual data or objects. The pointer returned is the same as the value stored in the context field of the dar_user_interaction_struct.
Returns:
True will return a yes answer; otherwise no.

Definition at line 111 of file user_interaction.h.

typedef void*(* dar_listing_callback)( char* flag, char* perm, char* uid, char* gid, char* size, char* date, char* filename, bool is_dir, bool has_children, void* context )
 

Callback signature for function used to send detailed listing information to the library client.

There are several types of data that are returned for each archive entry.

  • Filename
  • Permissions
  • File owner
  • File size
  • File type (found in the first byte of permissions field)
  • Last modification date
  • If file has children
  • Archival status
The fields returned in the listing have the following format: 

FLAG FIELD:
   Inclusion, Extended Attributes, and compression flags
   are three bracketed strings placed back to back.

   Format:
   
      [data ][ EA  ][compr]

   Data:
      [Saved]  - File is saved in archive.
      [InRef]  - Represents files in an extracted catalog.
      [     ]  - File is not saved in the archive.
   
   Extended Attributes:
      [Saved]  - All Extended Attributes are saved.
      [     ]  - EA data saved in a reference archive.
     '       ' - No EA data is saved.
     
   Compression:
      [     ]  - File is not compressed.
      [Worse]  - Compressed file is larger than original.
      [-----]  - File not compressed (not a regular file).
      [ XXX%]  - File compression percentage.
      
PERMISSIONS FIELD:
   Permission and file type data in a typical `ls' fashion.
   File type can be determined from the first byte of
   the permissions field. See `man 2 stat' for more
   information about file type characters.
   
   Format:
   
      -rwxrwxrwx
      ^----------- File type. In addition to the
                   standard characters, 'h' is used
                   for "hard links". These are any
                   regular file with more than one
                   hard link saved in the archive.
                   Multiple links to the same inode
                   would be restored during extraction.
                   
      -rwxrwxrwx
       ^  ^  ^---- Owner, group, and world permissions.
       
UID FIELD and GID FIELD:
   User and group identification are stored by number in
   the archive. The library performs name lookup and outputs
   the IDs and a string.
Parameters:
flag  Indicates listing status in the archive; If the archive contains Extended Attributes, is compressed, is contained in the archive.
perm  File type and permissions. Format is equivalent to the typical unix listing format.
uid  Owner's username.
gid  Owner's group name.
size  File size in bytes.
date  File modification date of archive entry.
filename  File name.
is_dir  True if file entry is a directory; false otherwise.
has_children  True if file is a directory and has entries in it; false otherwise.
context  An arbitrary value or object belonging to the library user. Can be used to store configuration parameters or contextual data or objects. The pointer returned is the same as the value stored in the context field of the dar_user_interaction_struct.

Definition at line 225 of file user_interaction.h.

typedef char*(* dar_string_callback)(char* msg, bool echo, void* context)
 

Callback signature for function used to query the user for a string.

One usage example is querying for a password. The library will specify whether it is neccessary to mask typed text during input (for a password or other confidential data).

Parameters:
msg  A question or message indicating what data is required from the user. String will be freed by the caller.
echo  Indicates if input text must be shadowed.
context  An arbitrary value or object belonging to the library user. Can be used to store configuration parameters or contextual data or objects. The pointer returned is the same as the value stored in the context field of the dar_user_interaction_struct.
Returns:
The text requested by the caller. If returned text is NULL the library call that initiated the callback will terminate, returning an exception. String will be freed by the caller.

Definition at line 132 of file user_interaction.h.

typedef void*(* dar_warning_callback)(char* msg, void* context)
 

Callback signature for function used to display a warning or message to the use.

This callback will be used to display content listings when a listing callback is not provided.

Parameters:
msg  Warning or message from library. String will be freed by caller.
context  An arbitrary value or object belonging to the library user. Can be used to store configuration parameters or contextual data or objects. The pointer returned is the same as the value stored in the context field of the dar_user_interaction_struct.

Definition at line 94 of file user_interaction.h.

API Copyright © 2005, Wesley Leggette - See Sourceforge project page for contact details.
Documents generated on Mon Mar 21 13:26:21 2005 by doxygen 1.2.18