nsfdb.h

IBM Lotus C++ API 7.0a for IBM Lotus Notes/Domino Directory Release --------- ------------------

STATUS LNPUBLIC NSFGetTransLogStyle(WORD far * LogType);
STATUS LNPUBLIC NSFBeginArchivingLogs(void);
STATUS LNPUBLIC NSFEndArchivingLogs(void);
STATUS LNPUBLIC  NSFGetFirstLogToArchive(UNID far * LogID, DWORD far * LogNumber, char far * LogPath);
STATUS LNPUBLIC NSFGetNextLogToArchive(UNID far * LogID, DWORD far * LogNumber, char far * LogPath);
STATUS LNPUBLIC NSFDoneArchivingLog(UNID far * LogID, DWORD far * LogSequenceNumber);
/* Wait for any other media recovery to finish, vs. return immed if busy */
#define  DBRECOVER_WAIT				0x0001
/* Make recovered db a new instance so it will not conflict with original */
#define  DBRECOVER_ZAP_ID			0x0002
/* Refresh a backup to the current level, mutually exclusive with DBRECOVER_ZAP_ID */
#define  DBRECOVER_REFRESH_BACKUP	0x0004
/* Recover database to a point in time, mutually exclusive with DBRECOVER_REFRESH_BACKUP */
#define  DBRECOVER_POINT_IN_TIME	0x0008
/* Give recovered db a new replica id so it will not conflict with original */
#define  DBRECOVER_ZAP_REPLICAID	0x0010
/* Make recovered db a new instance if another copy of the DB is on-line */
#define  DBRECOVER_ZAP_ID_IF_NECESSARY 0x0020
/* Allow alternate path from which to recover old log extents */
#define	 DBRECOVER_ALT_RETRIEVE_PATH 0x0040

STATUS LNPUBLIC NSFRecoverDatabases(const char far *		dbNames, 
									  LOGRESTORECALLBACKFUNCTION restoreCB,
									  DWORD					Flags, /* DBRECOVER_* flags */
									  WORD far *			errDbIndex,
									  TIMEDATE far *		recoveryTime);

STATUS LNPUBLIC NSFRecoverDatabasesWithCallback(const char far *	dbNames, 
									  LOGRESTORECALLBACKFUNCTION	restoreCB,
									  DWORD							Flags, /* DBRECOVER_* flags */
									  WORD far *					errDbIndex,
									  TIMEDATE far *				recoveryTime,
									  NOTERESTORECALLBACKFUNCTION	noteCB,
									  void far *					userParm);


/* rmmisc.cpp */

/* Return BOOL if span specified, else actual amount of log to process */
STATUS LNPUBLIC NSFIsNewBackupNeeded(const char far *		dbName, 
									 DWORD					comfortSpan, /* Requested Pad Log span in K */
									 DWORD far *			backupNeeded);
STATUS LNPUBLIC NSFDbCreateNoteID(DBHANDLE hDB, BOOL fData, NOTEID *retNoteID);
STATUS LNPUBLIC NSFDbAddItemName(DBHANDLE hDB, WORD type, char *string, WORD length, DWORD *rtnItemNumber); 

/*	Database Hook Drivers
*
* NSF hook drivers enable the API programmer to construct a set of
* subroutines, packaged as a DLL, that "hook" several NSF functions
* related to reading, modifying, and deleting notes.  The principal
* application of these hook drivers is intended to be auditing, that is,
* logging accesses to a database, however they can also be programmed
* to modify the contents of the notes and/or refuse requests.
*
* Hook Driver Packaging and Concurrency Requirements
*
* Like all Notes low-level subsystems, hook drivers must obey strict 
* rules to fit into their computing environment:
*
*    1. The drivers should be available on multiple computing platforms
*
*    2. The drivers are packaged as Dynamic Link Libraries under 
*    Windows, NT, and OS/2. Under Windows, the DEF file must specify the data 
*    as being MOVEABLE SINGLE so that it doesn't occupy GlobalDOS memory, and 
*    because Windows doesn't support multi-instance dynamic link libraries. 
*    For NT and OS/2, we recommend MULTIPLE data, but you can use whatever you 
*    wish.
*
*        For all four environments, Notes uses either LoadLibrary or 
*    DosLoadModule to load the driver. You must decide upon a mnemonic name 
*    for your driver, a maximum of 7 characters that is preferably 
*    nationality-neutral (obscure in all languages), such as NTAUDIT. In order
*    to load the library, Notes prefixes this name with 
*    _ under Windows, $ under OS/2 1.x, I under OS/2 2, and N under NT, 
*    and post-fixes the name with .DLL. The DLL is installed into Notes by 
*    simply placing its executable into the Notes Program Directory.
*
*        Notes automatically loads the hook drivers at initialization.
*    The list of hook drivers to be loaded is specified in NOTES.INI in a
*    variable called NSF_HOOKS with a comma separator. Thus, in order to load
*    three hook drivers, the variable might be specified as
*    NSF_HOOKS=drivera,driverb,driverc. Note that it isn't necessary to
*    specify the prefix character or the suffix .DLL.
*
*        Because of instantiation requirements of the operating systems, 
*    the library is loaded once per process. At load time, the first entry 
*    point address (entry point @1) is obtained by ordinal, and the driver's 
*    Init() function is invoked. The principal use of this function is to plug 
*    a data structure with vectors to other hook driver subroutines, 
*    including its Term() function which will be called by Notes when the 
*    process exits (or performs NotesTerm()).
*
*        Remember that in some environments (such as Windows), you must
*    export, in your DEF file, all of your functions that Notes will call
*    through these vectors. This is because Windows uses the fact that it's
*    exported to generate a thunk that sets up the DLL's DS appropriately on
*    all of these entry points.
*
*    3. All code executed by all entry points to the drivers must 
*    be 100% re-entrant by both multiple threads within a single process and 
*    multiple processes. In Windows, if you Yield() or make a call to a
*    Notes API function, you may also be preempted by another process that
*    does a hook driver call, so reentrancy is a requirement even in Windows.
*    (Notes makes heavy use of multiple threads and multiple processes, so
*    this must be treated as a required feature, not as something that can
*    be done "later".)
*
* Following is the data structure passed to your hook driver's Init routine.
* When your routine is called, the hModule is filled in (just in case you
* need it to load resources), and the rest of the vectors are zero'ed.
* If you don't need to hook any of these vectors, leave them NULL.  Otherwise,
* plug the vectors in your Init routine.
*
*/

typedef struct dbhookvec
	{

	/*	Module handle of the hook library */

	HMODULE hModule;

	/*	Initialization vector.  This is simply a pointer to the routine
		exported as ordinal #1 in your DLL.  You needn't plug this
		vector because it's plugged before calling through it to do
		driver initializations.  This routine is called once for each
		process that does a NotesInit(). */

	STATUS (LNCALLBACKPTR Init)(struct dbhookvec far *vec);

	/*	Termination vector.  This is called once for each process that
		did an Init call, just prior to the process's exiting.  */

	STATUS (LNCALLBACKPTR Term)(struct dbhookvec far *vec);

	/*	Note open hook.  This routine is called just AFTER a note is opened
		by the NSF subsystem.  It is called for both local and remote
		databases.  UserName is the name of the user doing the open.
		GroupList may be NULL, but when it's not it contains a list of
		the groups that the user is in.  hDB and NoteID can be used
		to identify the database and note (use NSFDbPathGet to get the
		pathname of the database).  OpenFlags are the flags originally
		passed into NSFNoteOpen.  hNote is the handle to the note that
		is about to be returned to the caller.  Your hook driver may
		modify the contents of the note, or may return an error from
		this routine if you wish to fail the open call.  You may use any
		standard Notes error code to fail the call. */

	STATUS (LNCALLBACKPTR NoteOpen)(struct dbhookvec far *vec, char far *UserName, LIST far *GroupList, DBHANDLE hDB, NOTEID NoteID, NOTEHANDLE hNote, WORD OpenFlags);

	/*	Note add/update hook, also handles deletion
		This routine is called just BEFORE a note is updated
		by the NSF subsystem.  It is called for both local and remote
		databases.  UserName is the name of the user doing the open.
		GroupList may be NULL, but when it's not it contains a list of
		the groups that the user is in.  hDB and NoteID can be used
		to identify the database and note (use NSFDbPathGet to get the
		pathname of the database).  pUpdateFlags is a pointer to a WORD
		of UpdateFlags originally passed into NSFNoteUpdate.  The hook
		may examine and modify the UpdateFlags WORD before returning,
		thus modifying the flags that will be passed into NSFNoteUpdate.
		hNote is the handle to the note that is about to be updated.
		Your hook driver may modify the contents of the note, or may
		return an error from this routine if you wish to fail the update
		call.  You may use any standard Notes error code to fail the call.
		Note that you can use the following algorithm to determine
		precisely the operation being performed:

		*	if (NoteID == NOTEID_ADD
		*			|| NoteID == NOTEID_ADD_OR_REPLACE
		*			|| NoteID == NOTEID_ADD_UNID)
		*		{
		*		if ((*pUpdateFlags) & UPDATE_DELETED)
		*			; ** Adding a new "deleted note stub" to a database **
		*		else
		*			; ** Adding a new document to a database **
		*		}
		*	else
		*		{
		*		if ((*pUpdateFlags) & UPDATE_DELETED)
		*			; ** Deleting an existing document from the database. **
		*			  ** Note that in this case, the contents of the hNote **
		*			  ** may be nil and should be disregarded; because of **
	    *			  ** this, there's no way to tell the class of a note **
		*			  ** being deleted at this point **
		*		else
		*			; ** Updating an existing document in the database **
		*		}

		*/

	STATUS (LNCALLBACKPTR NoteUpdate)(struct dbhookvec far *vec, char far *UserName, LIST far *GroupList, DBHANDLE hDB, NOTEID NoteID, NOTEHANDLE hNote, WORD far *pUpdateFlags);

	/*	Note stamp (Categorization) hook.
		This routine is called just BEFORE a set of notes is Categorized
		by the NSF subsystem.  It is called for both local and remote
		databases.  UserName is the name of the user doing the categorization.
		GroupList may be NULL, but when it's not it contains a list of
		the groups that the user is in.  hDB and hTable can be used
		to identify the database and notes (use NSFDbPathGet to get the
		pathname of the database).  ItemName and Data indicate the data
		being used in the categorization.  Your hook routine may return
		an error if you wish to fail the Stamp call.  You may use any
		standard Notes error code to fail the call. */

	STATUS (LNCALLBACKPTR DbStampNotes)(struct dbhookvec far *vec, char far *UserName, LIST far *GroupList, DBHANDLE hDB, HANDLE hIDTable, char far *ItemName, WORD ItemNameLength, void far *Data, WORD Length);

	/*	Flags used by Notes to describe the hook driver -- RESERVED */

	DWORD	Flags;

	} DBHOOKVEC;

STATUS LNPUBLIC NSFDbDirGet(DBHANDLE hDB, char *retDir);
STATUS LNPUBLIC NSFDbIsLocallyEncrypted (DBHANDLE hDB, BOOL *pRetval);
STATUS LNPUBLIC NSFGetOrgDir(char *UserName, char *retDir);

/* End of Note Storage File Database Definitions */

#ifdef __cplusplus
}
#endif

#endif


#if defined(OS400) && (__OS400_TGTVRM__ >= 510)
#pragma datamodel(pop)
#endif