nsfdata.h

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

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

/*********************************************************************/
/*                                                                   */
/* Licensed Materials - Property of IBM                              */
/*                                                                   */
/* L-GHUS-5VMPGW, L-GHUS-5S3PEE                                      */
/* (C) Copyright IBM Corp. 1989, 2005  All Rights Reserved           */
/*                                                                   */
/* US Government Users Restricted Rights - Use, duplication or       */
/* disclosure restricted by GSA ADP Schedule Contract with           */
/* IBM Corp.                                                         */
/*                                                                   */
/*********************************************************************/


#ifndef NSF_DATA_DEFS
#define NSF_DATA_DEFS

#include "pool.h"

#ifdef __cplusplus
extern "C" {
#endif
/* Note Storage File Data Definitions */

/*	Define some synonyms for self-documentation of templates */

#define DBHANDLE HANDLE
#define NOTEHANDLE HANDLE
#define ITEMDEFTABLEHANDLE HANDLE
#define ITEMDEFTABLEEXTHANDLE HANDLE
#define FORMULAHANDLE HANDLE
typedef void far * HCOMPUTE;

/*	Reserved NoteIDs */

#define NOTEID_RESERVED		0x80000000L		/*	Reserved Note ID, used for
												categories in NIFReadEntries
												and for deleted notes in a
												lot of interfaces. */
#define NOTEID_ADD			0x00000000L		/*	Reserved NoteID used as input
												to NoteUpdate, to add a new
												note (gets error if UNID assigned
												to new note already exists). */
#define NOTEID_ADD_OR_REPLACE 0x80000000L	/*	Reserved NoteID used as input
												to NoteUpdate, to update if
												note UNID already exists, or
												add note if doesn't exist. */
#define NOTEID_ADD_UNID		0x80000001L		/*	Reserved NoteID used as input
												to NoteUpdate.  Try to preserve
												the specified note UNID, but if
												it already exists, assign a new
												one.  (Note that the UNID in the
												hNote IS updated.) */
#define NOTEID_NULL_FOLDER	0x00000000L		/*	Used for null folder ids. */

/*	An RRV "file position" is defined to be a DWORD, 4 bytes long. */

#define RRV_ALIGNMENT 4L			/* most typical RRV alignment (DBTABLE.C) */
#define	RRV_DELETED NOTEID_RESERVED	/* indicates a deleted note (DBTABLE.C) */

#define	NOTEID_NO_PARENT	0x00000000L		/*	Reserved Note ID, used to indicate
												that this note has no parent in the
												response hierarchy. */

/*	This is the structure that identifies a database.  It is used for both
	the creation date/time and the originator date/time. */

typedef TIMEDATE DBID;

/*	This is the structure that identifies a note within a database.  It is
	simply a file position (RRV) that is guaranteed never to change WITHIN
	this file.  A replicated note, however, may have a different note id
	in two separate files. */

typedef DWORD NOTEID;

/*	This is the structure that identifies ALL replicas of the same note.  The
	"File" member contains a totally unique (random) number, generated at
	the time the note is created.  The "Note" member contains the date/time
	when the very first copy of the note was stored into the first NSF.  The
	"Sequence" member is a sequence number used to keep track of the most
	recent version of the note for replicated data purposes.  The
	"SequenceTime" member is a sequence number qualifier, that allows the
	replicator to determine which note is later given identical Sequence's.
	Both are required for the following reason.  The sequence number is needed
	to prevent someone from locking out future edits by setting the time/date
	to the future.  The sequence time qualifies the sequence number for two
	reasons:  1)  It prevents two concurrent updates from looking like
	no update at all and 2) it forces all systems to reach the same decision
	as to which update is the "latest" version.

	Time/dates associated with notes:

		OID.Note				Can be Timedate when the note was created
								(but not guaranteed to be - look for $CREATED
								item first for note creation time)
								Obtained by NSFNoteGetInfo(_NOTE_OID) or
								OID in SEARCH_MATCH.
		OID.SequenceTime		Timedate of last revision
								Obtained by NSFNoteGetInfo(_NOTE_OID) or
								OID in SEARCH_MATCH.
		NOTE.EditModified		Timedate when added to (or last updated in)
								this database.
								(Obtained by NSFNoteGetInfo(_NOTE_MODIFIED) or
								ID.Note in SEARCH_MATCH.


*/

#define MAXSEQNO			0x00FFFFFFL	/* Maximum sequence number for a note */
#define	OID_SEQNO_MASK		0x00FFFFFFL	/* Mask used to extract sequence # */
#define	OID_NO_REPLICATE	0x80000000L	/* Never replicate outward, currently used ONLY for deleted stubs */

typedef struct ORIGINATORID_tag {
	DBID File;					/* Unique (random) number */
								/* (Even though this field is called "File", */
								/*  it doesn't have anything to do with the file!) */
	TIMEDATE Note;				/* Can be Original Note Creation time/date */
								/*	(see OID.Note comment above) */
								/* (THE ABOVE 2 FIELDS MUST BE FIRST - UNID */
								/*  COPIED FROM HERE ASSUMED AT OFFSET 0) */
	DWORD Sequence;				/* LOW ORDER: sequence number, 1 for first version */
								/* HIGH ORDER WORD: flags, as above */
	TIMEDATE SequenceTime;		/* time/date when sequence number was bumped */
} ORIGINATORID;					/* 28 bytes */

#define OID ORIGINATORID


/*  Replication flags

	NOTE:  Please note the distinction between REPLFLG_DISABLE and
	REPLFLG_NEVER_REPLICATE.  The former is used to temporarily disable
	replication.  The latter is used to indicate that this database should
	NEVER be replicated.  The former may be set and cleared by the Notes
	user interface.  The latter is intended to be set programmatically
	and SHOULD NEVER be able to be cleared by the user interface.

	The latter was invented to avoid having to set the replica ID to
	the known value of REPLICA_ID_NEVERREPLICATE.  This latter method has
	the failing that DBs that use it cannot have DocLinks to them.  */

/*								0x0001	spare was COPY_ACL */
/*								0x0002	spare */
#define REPLFLG_DISABLE			0x0004	/* Disable replication */
#define REPLFLG_UNREADIFFNEW	0x0008	/* Mark unread only if newer note */
#define REPLFLG_IGNORE_DELETES	0x0010	/* Don't propagate deleted notes when
											replicating from this database */
#define REPLFLG_HIDDEN_DESIGN	0x0020	/* UI does not allow perusal of Design */
#define REPLFLG_DO_NOT_CATALOG	0x0040	/* Do not list in catalog */
#define	REPLFLG_CUTOFF_DELETE	0x0080	/* Auto-Delete documents prior to cutoff date */
#define REPLFLG_NEVER_REPLICATE	0x0100	/* DB is not to be replicated at all */
#define REPLFLG_ABSTRACT		0x0200	/* Abstract during replication */
#define REPLFLG_DO_NOT_BROWSE	0x0400	/* Do not list in database add */
#define REPLFLG_NO_CHRONOS		0x0800	/* Do not run chronos on database */
#define REPLFLG_IGNORE_DEST_DELETES	0x1000	/* Don't replicate deleted notes
											 into destination database */
#define REPLFLG_MULTIDB_INDEX	0x2000	/* Include in Multi Database indexing */
#define REPLFLG_PRIORITY_LOW	0xC000	/* Low priority */
#define REPLFLG_PRIORITY_MED	0x0000	/* Medium priority */
#define REPLFLG_PRIORITY_HI		0x4000	/* High priority */
#define REPLFLG_PRIORITY_SHIFT	14		/* Shift count for priority field */
#define REPLFLG_PRIORITY_MASK	0x0003	/* Mask for priority field after shifting*/
#define REPLFLG_PRIORITY_INVMASK 0x3fff	/* Mask for clearing the field */
#define REPLFLG_USED_MASK		(0x4|0x8|0x10|0x40|0x80|0x100|0x200|0xC000|0x1000|0x2000|0x4000)


/*  Replication priority values are stored in the high bits of the
	replication flags.  The stored value is biased by -1 so that
	an encoding of 0 represents medium priority (-1 is low and +1 is high).
	The following macros make getting and setting the priority easy.
	They return and accept normalized values of 0 - 2. */

#define REPL_GET_PRIORITY(Flags) \
	(((Flags >> REPLFLG_PRIORITY_SHIFT)+1) & REPLFLG_PRIORITY_MASK)
#define REPL_SET_PRIORITY(Pri) \
	(((Pri - 1) & REPLFLG_PRIORITY_MASK) << REPLFLG_PRIORITY_SHIFT)

/*  Reserved ReplicaID.Date.  Used in ID.Date field in ReplicaID to escape
	to reserved REPLICA_ID_xxx
*/
#define REPLICA_DATE_RESERVED		0		/* If used, see REPLICA_ID_xxx */

/*  Known Replica IDs.  Used in ID.Time field in ReplicaID.  Date
	subfield must be REPLICA_DATE_RESERVED).  NOTE:  If you add to this list,
	you should check the code in \catalog\search.c to see if the new one(s)
	need to be added to that code (probably not - but worth checking).

	The format is as follows.  Least sig. byte is version number.  2nd
	byte represents package code but is hard-coded to protect against
	changes in the package code.  Most sig. 2 bytes are reserved for future
	use.
*/
#define REPLICA_ID_UNINITIALIZED	0x00000000 /*  Uninitialized ID */
#define REPLICA_ID_CATALOG			0x00003301 /* Database Catalog (Version 2) */
#define REPLICA_ID_EVENT			0x00003302 /* Stats & Events Config DB */


/*  The following known replica ID is now obsolete.  Although the replicator
	still supports it, the problem is that DBs that use it cannot have
	DocLinks to them.  Instead use the replica flag REPLFLG_NEVER_REPLICATE. */
#define REPLICA_ID_NEVERREPLICATE	0x00001601 /* Do not allow replicas */

/*	Number of times within cutoff interval that we purge deleted stubs.
	For example, if the cutoff interval is 90 days, we purge every 30
	days. */

#define	CUTOFF_CHANGES_DURING_INTERVAL 3

/*	This is the structure that identifies a replica database. */

typedef struct {
	TIMEDATE ID;				/* ID that is same for all replica files */
	WORD Flags; 				/* Replication flags */
	WORD CutoffInterval;		/* Automatic Replication Cutoff Interval (Days) */
	TIMEDATE Cutoff;			/* Replication cutoff date */
} DBREPLICAINFO;


typedef struct {
	DWORD WarningThreshold; /* Database size warning threshold in kbyte units */
	DWORD SizeLimit;		/* Database size limit in kbyte units */
	DWORD CurrentDbSize;	/* Current size of database (in kbyte units) */
	DWORD MaxDbSize;		/* Max database file size possible (in kbyte units) */
} DBQUOTAINFO;

typedef struct {
	DWORD WarningThreshold; /* Database size warning threshold in kbyte units */
	DWORD SizeLimit;		/* Database size limit in kbyte units */
	DWORD CurrentDbSize;	/* Current size of database (in kbyte units) */
	DWORD MaxDbSize;		/* Max database file size possible (in kbyte units) */
	WORD QuotaMethod;		/* Enforcement method - filesize or usage */
	DWORD CurrentUsage;		/* Current amount of space used in the database (in kbyte units) */
	DWORD CurrentSizeUsed;	/* Either CurrentDbSize, or CurrentUsage, depending on method in use */
	DWORD Unused1;			/* Reserved.  Unused */
	DWORD Unused2;			/* Reserved.  Unused */
} DBQUOTAINFOEXT;


/*	This is the structure that globally identifies an INSTANCE of a note,
	that is, if we are doing a SEARCH_ALL_VERSIONS, the one with the
	latest modification date is the one that is the "most recent" instance. */

typedef struct {
	DBID File;					/* database Creation time/date */
	TIMEDATE Note;				/* note Modification time/date */
	NOTEID NoteID;				/* note ID within database */
} GLOBALINSTANCEID;

/*	This is the structure that universally (across all servers) describes
	a note (ALL INSTANCES of the same note), but without the information
	necessary to directly access the note in a given database.  It is used
	for referencing a specific note from another note (response notes and
	hot buttons are examples of its use) by storing this structure in the
	referencing note itself.  It is intended to work properly on any server,
	and even if the note being referenced is updated.  Matching of notes
	to other notes is done via the NIF machinery. */

typedef struct UNIVERSALNOTEID_tag {
	DBID File;					/* Unique (random) number */
								/* (Even though this field is called "File", */
								/*  it doesn't have anything to do with the file!) */
	TIMEDATE Note;				/* Can be Original Note Creation time/date */
								/*	(see OID.Note comment above) */
} UNIVERSALNOTEID;

#define UNID UNIVERSALNOTEID

/*	This is the structure that universally (across all servers) describes
	a note LINK. */

typedef struct {
	TIMEDATE File;					/* File's replica ID */
	UNID View;						/* View's Note Creation TIMEDATE */
	UNID Note;						/* Note's Creation TIMEDATE */
} NOTELINK;