nif.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.                                                         */
/*                                                                   */
/*********************************************************************/



/*	NIF manipulation routines & basic datatypes */

#ifndef NIF_DEFS
#define NIF_DEFS

#ifndef NSF_DATA_DEFS
#include "nsfdata.h"					/* We need NOTEID */
#endif

#ifndef NSF_NOTE_DEFS
#include "nsfnote.h"					/* We need NOTE_CLASS_VIEW */
#endif

#ifndef POOL_DEFS
#include "pool.h"
#endif

#ifndef STD_NAME_DEFS
#include "stdnames.h"
#endif

#ifdef __cplusplus
extern "C" {
#endif

#define DB2NIF_VERSION 11

/*	Collection handle */

typedef WORD HCOLLECTION;				/* Handle to NIF collection */
#define	NULLHCOLLECTION ( (HCOLLECTION) 0 )


/*	NIFOpenCollection "open" flags */

#define OPEN_REBUILD_INDEX		0x0001	/* Throw away existing index and */
										/* rebuild it from scratch */
#define OPEN_NOUPDATE			0x0002	/* Do not update index or unread */
										/* list as part of open (usually */
										/* set by server when it does it */
										/* incrementally instead). */
#define OPEN_DO_NOT_CREATE		0x0004	/* If collection object has not yet */
										/* been created, do NOT create it */
										/* automatically, but instead return */
										/* a special internal error called */
										/* ERR_COLLECTION_NOT_CREATED */
#define OPEN_SHARED_VIEW_NOTE	0x0010	/* Tells NIF to "own" the view note */
										/* (which gets read while opening the */
										/* collection) in memory, rather than */
										/* the caller "owning" the view note */
										/* by default.  If this flag is specified */
										/* on subsequent opens, and NIF currently */
										/* owns a copy of the view note, it */
										/* will just pass back the view note */
										/* handle  rather than re-reading it */
										/* from disk/network.  If specified, */
										/* the the caller does NOT have to */
										/* close the handle.  If not specified, */
										/* the caller gets a separate copy, */
										/* and has to NSFNoteClose the */
										/* handle when its done with it. */
#define OPEN_REOPEN_COLLECTION	0x0020	/* Force re-open of collection and */
										/* thus, re-read of view note. */
										/* Also implicitly prevents sharing */
										/* of collection handle, and thus */
										/* prevents any sharing of associated */
										/* structures such as unread lists, etc */


/*	Collection navigation directives */

#define NAVIGATE_CURRENT			0	/* Remain at current position */
										/* (reset position & return data) */
#define NAVIGATE_PARENT				3	/* Up 1 level */
#define NAVIGATE_CHILD				4	/* Down 1 level to first child */
#define NAVIGATE_NEXT_PEER			5	/* Next node at our level */
#define NAVIGATE_PREV_PEER			6	/* Prev node at our level */
#define NAVIGATE_FIRST_PEER			7	/* First node at our level */
#define NAVIGATE_LAST_PEER			8	/* Last node at our level */
#define NAVIGATE_CURRENT_MAIN		11	/* Highest level non-category entry */
#define NAVIGATE_NEXT_MAIN			12	/* CURRENT_MAIN, then NEXT_PEER */
#define NAVIGATE_PREV_MAIN			13	/* CURRENT_MAIN, then PREV_PEER only if already there */
#define NAVIGATE_NEXT_PARENT		19	/* PARENT, then NEXT_PEER */
#define NAVIGATE_PREV_PARENT		20	/* PARENT, then PREV_PEER */

#define NAVIGATE_NEXT				1	/* Next entry over entire tree */
										/* (parent first, then children,...) */
#define NAVIGATE_PREV				9	/* Previous entry over entire tree */
										/* (opposite order of PREORDER) */
#define NAVIGATE_ALL_DESCENDANTS	17	/* NEXT, but only descendants */
										/* below NIFReadEntries StartPos */
#define NAVIGATE_NEXT_UNREAD		10	/* NEXT, but only "unread" entries */
#define NAVIGATE_NEXT_UNREAD_MAIN	18	/* NEXT_UNREAD, but stop at main note also */
#define NAVIGATE_PREV_UNREAD_MAIN	34	/* Previous unread main. */
#define NAVIGATE_PREV_UNREAD		21	/* PREV, but only "unread" entries */
#define NAVIGATE_NEXT_SELECTED		14	/* NEXT, but only "selected" entries */
#define NAVIGATE_PREV_SELECTED		22	/* PREV, but only "selected" entries */
#define NAVIGATE_NEXT_SELECTED_MAIN	32	/* Next selected main. (Next unread */
										/* main can be found above.) */
#define NAVIGATE_PREV_SELECTED_MAIN	33	/* Previous selected main. */
#define NAVIGATE_NEXT_EXPANDED		15	/* NEXT, but only "expanded" entries */
#define NAVIGATE_PREV_EXPANDED		16	/* PREV, but only "expanded" entries */
#define NAVIGATE_NEXT_EXPANDED_UNREAD 23 /* NEXT, but only "expanded" AND "unread" entries */
#define NAVIGATE_PREV_EXPANDED_UNREAD 24 /* PREV, but only "expanded" AND "unread" entries */
#define NAVIGATE_NEXT_EXPANDED_SELECTED 25 /* NEXT, but only "expanded" AND "selected" entries */
#define NAVIGATE_PREV_EXPANDED_SELECTED 26 /* PREV, but only "expanded" AND "selected" entries */
#define NAVIGATE_NEXT_EXPANDED_CATEGORY	27 /* NEXT, but only "expanded" AND "category" entries */
#define NAVIGATE_PREV_EXPANDED_CATEGORY	28 /* PREV, but only "expanded" AND "category" entries */
#define NAVIGATE_NEXT_EXP_NONCATEGORY	39	/* NEXT, but only "expanded" "non-category" entries */
#define NAVIGATE_PREV_EXP_NONCATEGORY	40	/* PREV, but only "expanded" "non-category" entries */
#define NAVIGATE_NEXT_HIT			29	/* NEXT, but only FTSearch "hit" entries */
										/* (in the SAME ORDER as the hit's relevance ranking) */
#define NAVIGATE_PREV_HIT			30	/* PREV, but only FTSearch "hit" entries */
										/* (in the SAME ORDER as the hit's relevance ranking) */
#define NAVIGATE_CURRENT_HIT		31	/* Remain at current position in hit's relevance rank array */
										/* (in the order of the hit's relevance ranking) */
#define NAVIGATE_NEXT_SELECTED_HIT	35	/* NEXT, but only "selected" and FTSearch "hit" entries */
										/* (in the SAME ORDER as the hit's relevance ranking) */
#define NAVIGATE_PREV_SELECTED_HIT	36	/* PREV, but only "selected" and FTSearch "hit" entries */
										/* (in the SAME ORDER as the hit's relevance ranking) */
#define NAVIGATE_NEXT_UNREAD_HIT	37	/* NEXT, but only "unread" and FTSearch "hit" entries */
										/* (in the SAME ORDER as the hit's relevance ranking) */
#define NAVIGATE_PREV_UNREAD_HIT	38	/* PREV, but only "unread" and FTSearch "hit" entries */
										/* (in the SAME ORDER as the hit's relevance ranking) */
#define NAVIGATE_NEXT_CATEGORY		41	/* NEXT, but only "category" entries */
#define NAVIGATE_PREV_CATEGORY		42	/* PREV, but only "category" entries */
#define NAVIGATE_NEXT_NONCATEGORY	43	/* NEXT, but only "non-category" entries */
#define NAVIGATE_PREV_NONCATEGORY	44	/* PREV, but only "non-category" entries */

#define NAVIGATE_MASK			0x007F	/* Navigator code (see above) */


/*	Flag which can be used with ALL navigators which causes the navigation
	to be limited to entries at a specific level (specified by the
	field "MinLevel" in the collection position) or any higher levels
	but never a level lower than the "MinLevel" level.  Note that level 0
	means the top level of the index, so the term "minimum level" really
	means the "highest level" the navigation can move to.
	This can be used to find all entries below a specific position
	in the index, limiting yourself only to that subindex, and yet be
	able to use any of the navigators to move around within that subindex.
	This feature was added in Version 4 of Notes, so it cannot be used
	with earlier Notes Servers. */

#define NAVIGATE_MINLEVEL		0x0100	/* Honor "Minlevel" field in position */
#define NAVIGATE_MAXLEVEL		0x0200	/* Honor "Maxlevel" field in position */

/*  This flag can be combined with any navigation directive to
	prevent having a navigation (Skip) failure abort the (ReadEntries) operation.
	For example, this is used by the Notes user interface when
	getting the entries to display in the view, so that if an attempt is made to
	skip past either end of the index (e.g. using PageUp/PageDown),
	the skip will be left at the end of the index, and the return will return
	whatever can be returned using the separate return navigator.

	This flag is also used to get the "last" N entries of a view by setting the
	Skip Navigator to NAVIGATE_NEXT | NAVIGATE_CONTINUE, setting the SkipCount to MAXDWORD,
	setting the ReturnNavigator to NAVIGATE_PREV_EXPANDED, and setting the ReturnCount
	to N (N must be greater than 0). */

#define NAVIGATE_CONTINUE		0x8000	/* "Return" even if "Skip" error */

/*	Structure which describes statistics about the overall collection,
	and can be requested using the READ_MASK_COLLECTIONSTATS flag.  If
	requested, this structure is returned at the beginning of the returned
	ReadEntries buffer. */

typedef struct
	{
	WORD	TopLevelEntries;			/* # top level entries (level 0) */
	WORD	spare[3];					/* 0 */
	} COLLECTIONSTATS16;

typedef struct
	{
	DWORD	TopLevelEntries;			/* # top level entries (level 0) */
	DWORD	spare;						/* 0 */
	} COLLECTIONSTATS;

/*	Structure which specifies collection index position. */

#define MAXTUMBLERLEVELS_V2 8			/* Max. levels in hierarchy tree in V2 */
#define MAXTUMBLERLEVELS 32				/* Max. levels in hierarchy tree */

typedef struct
	{
	WORD	Level;						/* # levels -1 in tumbler */
										/* (top level = 0) */
	WORD	Tumbler[MAXTUMBLERLEVELS_V2]; /* Current tumbler (1.2.3, etc) */
										/* (an array of ordinal ranks) */
										/* (0th entry = top level) */
	} COLLECTIONPOSITION16;

typedef struct
	{
	WORD	Level;						/* # levels -1 in tumbler */
										/* (top level = 0) */
	BYTE	MinLevel;					/* MINIMUM level that this position */
										/* is allowed to be nagivated to. */
										/* This is useful to navigate a */
										/* subtree using all navigator codes. */
										/* This field is IGNORED unless */
										/* the NAVIGATE_MINLEVEL flag is */
										/* enabled (for backward compat) */
	BYTE	MaxLevel;					/* MAXIMUM level that this position */
										/* is allowed to be nagivated to. */
										/* This is useful to navigate a */
										/* subtree using all navigator codes. */
										/* This field is IGNORED unless */
										/* the NAVIGATE_MAXLEVEL flag is */
										/* enabled (for backward compat) */
	DWORD	Tumbler[MAXTUMBLERLEVELS];	/* Current tumbler (1.2.3, etc) */
										/* (an array of ordinal ranks) */
										/* (0th entry = top level) */
										/* Actual number of array entries */
										/* is Level+1 */
	} COLLECTIONPOSITION;


/*	Macro which computes size of portion of COLLECTIONPOSITION structure
	which is actually used.  This is the size which is returned by
	NIFReadEntries when READ_MASK_INDEXPOSITION is specified. */

#define COLLECTIONPOSITIONSIZE16(p) (sizeof(WORD) * ((p)->Level+2))
#define COLLECTIONPOSITIONSIZE(p) (sizeof(DWORD) * ((p)->Level+2))
/*	NIFReadEntries return mask flags

	These flags specified what information is returned in the return
	buffer.  With the exception of READ_MASK_COLLECTIONSTATS, the
	information which corresponds to each of the flags in this mask
	are returned in the buffer, repeated for each index entry, in the
	order in which the bits are listed here.

	The return buffer consists of:

	1) COLLECTIONSTATS structure, if requested (READ_MASK_COLLECTIONSTATS).
		This structure is returned only once at the beginning of the
		buffer, and is not repeated for each index entry.

	2) Information about each index entry.  Each flag requested a different
		bit of information about the index entry.  If more than one flag