dus.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. 1999, 2001  All Rights Reserved           */
/*                                                                   */
/* US Government Users Restricted Rights - Use, duplication or       */
/* disclosure restricted by GSA ADP Schedule Contract with           */
/* IBM Corp.                                                         */
/*                                                                   */
/*********************************************************************/


#ifndef DUS_DEFS
#define DUS_DEFS

#ifdef __cplusplus
extern "C" {
#endif

/*	Function prototypes and definitions for the Domino Upgrade Services (DUS) SPI.
	Unlike typical Notes API functions, these Service Provider Interface functions
	do NOT exist in the notes library, but are implemented by the
	Domino Upgrade Serice builder to be called by the DUS framework.
	A sample of a Domino Upgrade Service (which implements these functions)
	will be available with the Notes SDK. */

#if defined(ADMIN_PLATFORM) /* This SPI interface only available with Admin Client */

#ifndef	USERREG_DEFS
#include "reg.h"
#endif

/*************************  DEFINITIONS  ***************************/

/* Max size of Name element in DUS_ENTRY struct */
#define DUSMAXFLATNAME 128


/* DUS Init Flags -- set in the StartFlags param of DUSStart. */

#define fDUSDoMailConversion		0x00000001	/* mail exists to convert and should be converted */
#define fDUSGenerateRandPWs			0x00000002	/* generate random passwords if no user password supplied */
#define fDUSAdvancedDlg				0x00000004	/* advanced dialog is available DUSAdvancedDlg is implemented */
#define fDUSUseFullNameProvided		0x00000008	/* use the full name provided as a secondary Notes user name */
#define fDUSAllowEmptyGroups		0x00000010	/* allow addition of empty groups to Notes Address Book */
#define fDUSMailConversionOnly		0x00000020	/* Only convert mail for this migrating user.  The person document
												   and ID file must already exist in the address book in this case */
#define fDUSAddAdminToACL			0x00000080	/* Add the administrator to the mail file access control list during
												   registration mail creation.  This allows mail conversion access to
												   mail file in two pass migration scenarios (directory migrated first,
												   mail converted at a later date). */
#define fDUSOverwritePasswords		0x00000100	/* Generate random password for every user, always overwriting any existing password */

#define fDUSUseFilters				0x00000200	/* (NEW IN R6) See comment to DUSRetrieveFilters below */

/* DUS Entry Flags -- used in 'EntryFlags' for DUS_ENTRY struct */
#define fDUSExternalEntry			0x00010000	/* (NEW IN R6) If flag is set for a group member, it will not be registered in Notes, only added to the group */
#define fDUSIgnoreEntry				0x00020000	/* (NEW IN R6) If flag is set for a group member, it will neither be registered in Notes, nor added to the group */
/* NOTE: fDUSExternalEntry and fDUSIgnoreEntry flags are ignored when filter is executed, or all users/groups are retrieved */


/* Used to write to the ADMINP_GROUP_TYPE field in the group note. */
#define DUS_GROUP_TYPE_MULTI_PURPOSE	"0"
#define DUS_GROUP_TYPE_MAIL_ONLY		"1"
#define DUS_GROUP_TYPE_ACL_ONLY			"2"
#define DUS_GROUP_TYPE_DENY_LIST_ONLY	"3"


/*	The below four flags for extended error processing.
	Used in pErrorLevel param with DUSExtendedErrorText */

/* The below three flags should not be or'd in together, only exclusively.
	For example, if DUS_ERROR_LEVEL_INFO is or'd in, do not or in
	DUS_ERROR_LEVEL_WARNING or DUS_ERROR_LEVEL_ERROR. DUS_ERROR_LEVEL_ERROR
	signals the DUS framework (Notes) to go no farther and to shutdown the DUS */
#define DUS_ERROR_LEVEL_INFO			0x0001
#define DUS_ERROR_LEVEL_WARNING			0x0002
#define DUS_ERROR_LEVEL_ERROR			0x0004
/* Use this flag if the error should not be displayed. */
#define DUS_ERROR_NO_DISPLAY			0x0008

/************************** TYPEDEFS ****************************/

/*	DUS_ENTRY -- Represents one user or group.  An array of these
	structures is allocated by Notes and passed in to the DUS with
	DUSRetrieveUsers and DUSRetrieveGroups.  The DUS fills in the
	data and the array is passed back to Notes,	where the data
	is displayed in the Notes Upgrade UI. */

typedef struct
{
char	Name[DUSMAXFLATNAME+1];	/*	required -- user or group name */
DWORD	ID;						/*	required -- unique value identifying this user or group */
DWORD	EntryFlags;				/*	not to be used by the DUS */
HANDLE	hParentGroupList;		/* 	Optional and rarely used.  Alloced by the DUS or Notes and freed by Notes.
									Contains a Notes LIST of group names to which the entry belongs.
									This can be adjusted by Notes after DUSInitialize, depending
									on administrator choices at the UI, but can be initially set
									by the DUS.  This LIST handle must be created with the
									prefix data type set to FALSE (see ListAllocate) and must
									be passed UNLOCKED back to Notes. */
} DUS_ENTRY, *PDUS_ENTRY;


/* typedef for progress bar callback passed to DUS with DUSInitialize */

typedef void   (LNCALLBACKPTR DUSPROGRESSBARPROC)(DWORD Range, DWORD Position, char *MessageText);
typedef STATUS (LNVARARGS * DUSLOGEVENTPROC)(STATUS StringID, HMODULE hModule, STATUS AdditionalErrorCode,...);


/* Prototypes for DUS SPI functions */

/*************************************************************************
    FUNCTION: 	DUSGetName

    PURPOSE:  	Provide UI strings immediately after dll is loaded.

	INPUTS:		hInstance -- instance handle of this DUS.
				DUSNameBufLen -- size of the DUSNameBuf.
				DUSDescriptionBufLen -- size of the DUSDescriptionBuf.

	OUTPUTS:	DUSNameBuf -- buffer into which the DUS will copy the name
				of the DUS as it will appear in the Foreign Directory Source
				listbox (in the upgrade dialog).
				DUSDescriptionBuf -- buffer into which the DUS will copy a brief
				description of the DUS as it will appear in the upgrade dialog.

    COMMENTS: 	This call notifies the upgrade DLL that the upgrade dialog
    			is being displayed.  It also passes in the instance handle of
    			the DUS, which the DUS may want to store for later DUS operations.
*************************************************************************/
STATUS	LNCALLBACK	DUSGetName(	HMODULE hInstance,
							char *DUSNameBuf,
							WORD DUSNameBufLen,
							char *DUSDescriptionBuf,
							WORD DUSDescriptionBufLen );




/*************************************************************************
    FUNCTION: 	DUSStart

    PURPOSE:  	Notifies the DUS of one of two situations:
    				1)	It has been selected from the foreign directory
		    			source list in the foreign directory dialog or;
					2)	The first of possibly several users retrieved
						from this DUS is about to be registered in Notes.
				It also supplies the DUS framework with a context handle,
				which will be passed back to the DUS with every subsequent
				DUSxxx function.
				finally, it supplies the DUS with flags representing
				UI defaults for the Foreign Directory dialog.

	INPUTS:		hInstance -- Instance handle to this DUS dll.

				hUserNote -- this note handle will only be valid (non-NULL)
				if DUSStart is called just prior to user registration
				(from the user registration dialog, as opposed to from the
				foreign directory dialog).  The hUserNote contains context
				information (represented by the context handle passed back
				to the caller).  The DUS can stores this context information
				in the hUserNote passed in with DUSGetUserInformation.
				When DUSStart is called from the Foreign Directory dialog,
				hUserNote will be NULLHANDLE and the DUS allocates and inits
				a context buffer for the first time.

				DUSProgressBar -- pointer to a callback used by the DUS
				to display progress on potentially length operations, such
				as user retrieval.  This should be retained by the DUS for
				subsequent calls.
			
				DUSLogEvent -- pointer to a callback used by the DUS
				to log progress to the Notes log on any operation, such
				as user retrieval.  This should be retained by the DUS for
				subsequent calls.  The log cannot be written to after DUSStop
				is called.

	OUTPUTS:	pRethContext -- pointer to a context handle the DUS can optionally
				allocate/return to the DUS framework.  On every subsequent call
				to the DUS in the current session, this context handle will be passed
				to the DUS by the DUS framework.  The DUS is responsible for freeing
				this handle in DUSStop and should store the context handle in the
				hUserNote if the DUS needs to convert mail or take pre- or post-
				user registration actions available with DUSRegistrationNotify.


    COMMENTS: 	This function is also where the DUS should put up any secondary UI
				necessary to handle directory specific operations, such as
				retrieving users.  For example, if the administrator will have
				to supply a password to access the foreign directory source,
				the DUS should prompt for it here.

				DUSStart is called once per Foreign Directory dialog session
				(for each DUS) and once per registration session (for each DUS,
				if users from that DUS source are being registered).
*************************************************************************/
STATUS	LNCALLBACK	DUSStart(	HMODULE hInstance,
							HANDLE *pRethContext,
							NOTEHANDLE hUserNote,
							DWORD *pRetInitFlags,
							DUSPROGRESSBARPROC DUSProgressBar,
							DUSLOGEVENTPROC DUSLogEvent);



/****************************************************************************
    FUNCTION:	DUSExtendedErrorText

    Purpose:
    	This call retrieves the text to be displayed in the
		event that a call to the DUS extension DLL fails and the dll
		wishes to return it's own error string.  Any call implemented
		in this dll wanting this callback should return ERR_DUS_EXTENDED_ERROR.

	Inputs:
		hContext -- pointer to DUS specific context.  Alloced/provided by the DUS
					in DUSStart and passed back to the DUS with every DUS function.

		BufferLen -- length of ErrorBuffer

	Outputs:
		ErrorBuffer -- lmbcs string passed to DUS framework for display.

		pErrorLevel -- pointer to one of three error level flags supplied by the DUS
						(see DUS_ERROR_LEVEL_xxx in dus.h).  This value determines
						how the error message box will be displayed.  The three flags
						relating to error level should only be or'd in exclusively (not
						with each other).  A fourth flag, DUS_ERROR_NO_DISPLAY, prevents
						display of the error if or'd in.
*******************************************************************************/
void	LNCALLBACK	DUSExtendedErrorText(	HANDLE hContext,
										char * ErrorBuffer,
										WORD BufferLen,
										WORD *pErrorLevel);




/*************************************************************************
    FUNCTION: 	DUSRetrieveUsers

    Purpose:
    	This function allocates and passes back an array of DUS_ENTRY structs
    	containing information about the users available for upgrade/migration.

	Inputs:
		hContext -- provided by the DUS with DUSStart and passed back
					with every call by the framework.
		StartIndex -- 0L the first time the DUS is called.  If all users
					are not retrieved the first time and subsequent calls
					are necessary, this value is equal to the resume index
					passed back by the DUS on the previous call (*pResumeIndex).
		NumUsersRequested -- number of users that should be provided
							to the caller, if available.

	Outputs:
		pResumeIndex -- Set this value if additional users need to be
			returned to the DUS framework (number of available users exceeds
			the number requested by the framework).  This value will be returned
			to the DUS on the subsequent DUSRetrieveUsers call as the StartIndex.
			When user retrieval is complete the pResumeIndex should be set to 0L.
			The pResumeIndex will always be 0L the first time DUSRetrieveUsers
			is called.