ndmp.api

网络数据管理协议的开发

#                              -*- Mode: Text -*- 
# ndmp.api
# 
# Description     : NDMP SDK backup/recover module API description.
# 
# Copyright (c) 1996,1997 PDC, Network Appliance. All Rights Reserved.
# 
# $Id: ndmp.api,v 1.4 1997/02/23 00:28:33 tim Exp $
# 

The NDMP daemon provided by the SDK is designed to simplify the 
addition of backup/recover modules.
The backup/recover module provided by the SDK is quite rudimentary and is
only intended to help developers understand how to design and implement
an NDMP server.

A commercial quality NDMP server would likely contain one or more
backup/recover modules that implement data formats such as tar, cpio, dump,
or possibly a proprietary format.

Backup/recover modules interface to the SDK NDMP daemon via the
backup/recover module API.

The architecture of a backup/recover module is not dictated by the SDK.
However, a module is expected to conform to one of the following models:
  o Concurrent model. In this model, the module performs the backup/recover
    operation concurrent with the NDMP connection process. The NDMP
    connection process will concurrently handle NDMP message requests
    from the backup management client and data from a remote mover
    while the backup/recover operation is in progress.
  o Sequential model. In this model, the backup/recover operation runs
    in the context of the NDMP connection process. Since the NDMP
    connection process must process NDMP requests and mover data while
    the backup/recover operation is in progress, the module must
    periodically return control to the NDMP connection process.

Some examples of how a module may be designed:
  o A module may be designed to run in the context of the NDMP daemon
    connection process.
  o A module may be designed to be run in the context of one or more
    threads created by the NDMP daemon.
  o A module may be designed to spawn and exec an existing backup/recover
    application and then communicate with the application via a pipe.

The SDK is currently designed to static link modules.
However, the API is designed to make it easy to change the SDK
to support dynamic relocatable modules.

A module must simply implement and conform to the SDK defined
backup/recover module API.
The API consists of a set of SDK provided functions and a specification of
functions that must be provided by the backup/recover module.

NDMP daemon provided API functions:

/*
 * NDMP daemon callback functions.
 * Called by backup/recover modules.
 */
typedef char*
NdmpdGetEnvFunc(void*                   daemonCookie,
                char*                   varName);

This function returns the value of the named environment variable.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.
0 is returned if the named variable does not exist in the environment
variable list.

-------------------------
typedef int
NdmpdAddEnvFunc(void*                   daemonCookie,
                char*                   name,
                char*                   value);

This function is used to add an environment variable to the environment
variable list.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.

-------------------------
typedef ndmp_name*
NdmpdGetNameFunc(void*                  daemonCookie,
                 u_long                 nameIndex);

This function returns the Nth name from the recover file name list where
N is nameIndex. A 0 is returned if nameIndex is greater than or equal to
the list length.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.

-------------------------
typedef int
NdmpdDispatchFunc(void*                 daemonCookie);

This function is only used by sequential model modules. It passes control
back to the daemon so that the daemon can process pending NDMP requests as
well as monitor file descriptors registered via NdmpdAddFileHandlerFunc.
The function may call ModuleAbortFunc. A typical module will set an
abort flag within ModuleAbortFunc and check this flag after returning
from NdmpdDispatchFunc.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.
A value of -1 is returned if the operation has been aborted or the connection
to the NDMP client has been closed. Otherwise, 0 is returned.

-------------------------
typedef void
NdmpdDoneFunc(void*                     daemonCookie,
              int                       error);

This function is used to notify the daemon that the backup/recover operation
has completed. The error argument indicates the completion status of the
operation. 0 should be returned if the operation completes successfully.
Otherwise error should be set to an appropriate unix errno value.
EINTR should be set if the operation is aborted via ModuleAbortFunc.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.

-------------------------
typedef int
NdmpdLogFunc(void*                      daemonCookie,
             char*                      format,
             ...);

This function is used to send log messages to the NDMP client.
The arguments are printf style arguments.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.
A 0 is returned if the message is successfully sent to the NDMP client.
Otherwise, -1 is returned.

-------------------------
#define	NDMPD_SELECT_MODE_READ      1
#define	NDMPD_SELECT_MODE_WRITE     2
#define	NDMPD_SELECT_MODE_EXCEPTION 4

typedef void
NdmpdFileHandlerFunc(void*     cookie,
                     int       fd,
                     u_long    mode);

typedef int
NdmpdAddFileHandlerFunc(void*                  daemonCookie,
                        void*                  cookie,
                        int                    fd,
                        u_long                 mode,
                        NdmpdFileHandlerFunc*  func);

This function is only used by sequential model modules.
It is used to add a file descriptor to the set of descriptors
that is monitored by NdmpdDispatchFunc. The file handler
will be called when the file descriptor is read for I/O. 
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.
cookie is an opaque data pointer that is passed to the file hander when
the handler is called.
fd is the file descriptor.
mode is a mask describing the type of monitoring that should be done on fd.
A 0 is returned if the file handler is successfully added.
Otherwise, -1 is returned.

-------------------------
typedef int
NdmpdRemoveFileHandlerFunc(void*              daemonCookie,
                           int                fd,

This function removes a file descriptor previously added
via NdmpdAddFileHandlerFunc.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.
fd is the file descriptor.

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

This function is used to send backup data to the daemon. data points to
the data to be sent. length is the length of the data.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.
0 is returned if the data was sucessfully sent. -1 is returned upon error.

-------------------------
typedef int
NdmpdFileHistoryPathFunc(void*          daemonCookie,
                         char*          name,
                         struct stat*   fileStat,
                         u_longlong_t   fh_info);

This function is used to send file history path entries to the NDMP client.
Backup modules that do file based backup should use this function for
reporting file history.
daemonCookie is the daemonCookie from the module params structures passed
to the ModuleStartFunc.