ndmp.api

网络数据管理协议的开发

fileStat is the file attribute data returned by the stat() function.
fh_info specifies the location of the file data within the backup
data stream. It is used by recover modules that support fast file
retrieval by seeking directly to the data stream position of the file data.
If not supported, fh_info should be set to 0.
A 0 is returned if the message is successfully sent to the NDMP client.
Otherwise, -1 is returned.

-------------------------
typedef int
NdmpdFileHistoryDirFunc(void            *daemonCookie,
                        char            *name,
                        u_long          node,
                        u_long          parent);

This function is used to send file history directory entries to the 
NDMP client.
Backup modules that do inode based backup should use this function in
conjunction with NdmpdFileHistoryNodeFunc for reporting file history.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.
name the path component name of the inode.
node is the inode number.
parent is the parent inode number of node.
A 0 is returned if the message is successfully sent to the NDMP client.
Otherwise, -1 is returned.

-------------------------
typedef int
NdmpdFileHistoryNodeFunc(void           *daemonCookie,
                         u_long         node,
                         struct stat    *fileStat,
                         u_longlong_t   fh_info);

This function is used to send file history node entries to the NDMP client.
Backup modules that do inode based backup should use this function in
conjunction with NdmpdFileHistoryDirFunc for reporting file history.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.
node is the inode number. This must match the node from a prior
NdmpdFileHistoryDirFunc.
fileStat is the file attribute data returned by the stat() function.
fh_info specifies the location of the file data within the backup
data stream. It is used by recover modules that support fast file
retrieval by seeking directly to the data stream position of the file data.
If not supported, fh_info should be set to 0.
A 0 is returned if the message is successfully sent to the NDMP client.
Otherwise, -1 is returned.

-------------------------
typedef int
NdmpdSeekFunc(void*                     daemonCookie,
              u_longlong_t              offset,
              u_longlong_t              length);

This function is used to seek to a specific data stream position and 
inform the daemon to initiate a read for the specified length of data.
A large length should be specified if the module desires to read the
entire data stream.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.
noffset is the data stream position to be seeked to.
length is the length of the read that the mover should initiate.

-------------------------
typedef int
NdmpdReadFunc(void*                     daemonCookie,
              char*                     data,
              u_long                    length);

This function is used to read data from the data stream. data is returned
from the current data stream position.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.
data is the location to store the read data.
length is the amount of data to read.

-------------------------
typedef int
NdmpdFileRecoveredFunc(void*            daemonCookie,
                       char*            name,
                       u_short          ssid,
                       int              error);

This function is used to notify the NDMP client that a file has or has not
been successfully recovered.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.
name is the name of the file that was (was not) recovered.
ssid is the selection set id of the file for modules that support
selection set id. If not supported, 0 should be returned.
If the file was successfully recovered, error should be set to 0.
Otherwise, error should be set to a unix errno value that indicates
why the file was not recovered. ENOENT should be used to indicate that the
file was not found on the tape.
A 0 is returned if the message is successfully sent to the NDMP client.
Otherwise, -1 is returned.


Module function specification:

typedef struct NdmpdModuleStats
{
    u_longlong_t    bytesProcessed;
    u_longlong_t    estBytesRemaining;
    u_long          estTimeRemaining;
} NdmpdModuleStats;

/*
 * Parameter structure passed to module start function.
 */
typedef struct  NdmpdModuleParams
{
    void*                       daemonCookie;
    void**                      moduleCookie;
    u_short                     protocolVersion;
    ndmp_data_operation         operation;
    NdmpdModuleStats*           stats;
    NdmpdGetEnvFunc*            getEnvFunc;
    NdmpdAddEnvFunc*            addEnvFunc;
    NdmpdGetNameFunc*           getNameFunc;
    NdmpdDispatchFunc*          dispatchFunc;
    NdmpdDoneFunc*              doneFunc;
    NdmpdLogFunc*               logFunc;
    NdmpdWriteFunc*             writeFunc;
    NdmpdFileHistoryPathFunc*   fileHistoryPathFunc;
    NdmpdFileHistoryDirFunc*    fileHistoryDirFunc;
    NdmpdFileHistoryNodeFunc*   fileHistoryNodeFunc;
    NdmpdReadFunc*              readFunc;
    NdmpdSeekFunc*              seekFunc;
    NdmpdFileRecoveredFunc*     fileRecoveredFunc;
} NdmpdModuleParams;

The daemonCookie is passed back to the daemon as a parameter to each of the
daemon API functions. This cookie is used by the daemon to determine which
module it is being called by.
The moduleCookie should be initialized by the module to a location that
contains module specific data. This cookie is passed to the module as
a parameter to the ModuleAbortFunc.
protocolVersion is the protocol version being used between the NDMP client and
server. Protocol features vary between versions. The module should utilize
protocolVersion to determine what features are available for use during
the data operation. Example: direct access functionality (via ndmpdSeek())
is not available in protocol version 1.
operation indicates whether the operation is a backup or recover operation.
During a backup/recover operation, the module should periodically
update the stats structure. This is an optional feature. If not supported,
modules should simply initialize all stats to 0.
The stats data is returned to the client in response to a data_get_state
request.
The remaining members are pointers to the daemon provided API functions.
Depending on the operation, some of the pointers may be 0.

/*
 * Module function prototypes.
 */
typedef int ModuleStartFunc(NdmpdModuleParams*      params);
typedef int ModuleAbortFunc(void*                   moduleCookie);
typedef int ModuleGetAttrsFunc(u_long*              attributes);

    ModuleGetAttrs
This function is used by the NDMP daemon to determine the attributes
supported by the backup/recover module.
It is called upon receipt of a data_get_butype_attr request.
The module is expected to return a mask of attributes. Refer to the
protocol spec or ndmp.x file for the defined attributes.

    ModuleStartFunc
This function is used by the NDMP daemon to start a backup or recover
operation. The parameter structure argument configures the operation and
contains the pointers to the NDMP daemon provided module API functions.
It is called upon receipt of data_start_backup and data_start_recover
requests.
The function should return a unix errno value if the function is unable to
call the doneFunc. Otherwise, 0 should be returned.
If the module conforms to the sequential model, this function should not
return until after the backup/recover operation has completed and
NdmpdDoneFunc has been called.
If the module conforms to the concurrent model, this function should
return immediately after starting the backup/recover operation.

    ModuleAbortFunc
This function is used by the NDMP daemon to stop a backup or recover
operation. The argument is the cookie from the params structure passed 
to the ModuleStartFunc. The ModuleStartFunc should initialize the
cookie pointer to the address of any module specific data needed
by ModuleAbortFunc.
If the module conforms to the sequential model, this function will be
called from the context of NdmpdDispatchFunc. In this case, a flag 
should simply be set that is checked upon return from NdmpdDispatchFunc.
Upon detecting abort, the module should perform any necessary cleanup
and then call NdmpdDoneFunc with an error code of EINTR.