dus.h

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

			
		pNumUsersReturned -- points to the number of users returned by the DUS to
							the caller (users returned via the array of DUS_ENTRY
							structs represented	by pRethExternalUsers).  This value
							should be used to allocate an array of DUS_ENTRY structs
							with the size:
								NumUsersRequested * sizeof(DUS_ENTRY)
		pRethExternalUsers -- pointer to the memory handle of an array of DUS_ENTRY
							structs returned to the caller.  The DUS allocs and assigns
							this handle, sets the user information into the array, and
							returns the handle UNLOCKED to the caller. The array should
							contain *pNumUsersReturned structs.  The caller will
							free the memory associated with the handle.
		pRetUserEntrySize -- pointer to the size of the DUS_ENTRY struct (an array of
							which are alloced by the DUS and passed back to the caller)

	Comments:	DUSRetrieveUsers will be continue to be called by the DUS framework
				until the DUS returns a resume index of 0 or the *pNumUsersReturned is
				less than *pNumUsersRequested.

*************************************************************************/
STATUS	LNCALLBACK	DUSRetrieveUsers(	HANDLE hContext,
									DWORD StartIndex,
									DWORD *pResumeIndex,
									DWORD NumUsersRequested,
									DWORD *pNumUsersReturned,
									HANDLE *pRethExternalUsers,
									DWORD *pRetUserEntrySize);



/*************************************************************************
    FUNCTION: 	DUSRetrieveGroups

    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 groups
					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).
		NumGroupsRequested -- number of groups that should be provided
							to the caller, if available.

	Outputs:
		pResumeIndex -- Set this value if additional groups need to be
			returned to the DUS framework (number of available groups exceeds
			the number requested by the framework).  This value will be returned
			to the DUS on the subsequent DUSRetrieveGroups call as the StartIndex.
			When group retrieval is complete the pResumeIndex should be set to 0L.
			The pResumeIndex will always be 0L the first time DUSRetrieveGroups
			is called.
			
		pNumGroupsReturned -- points to the number of groups returned by the DUS to
							the caller (groups returned via the array of DUS_ENTRY
							structs represented	by pRethExternalGroups).  This value
							should be used to allocate an array of DUS_ENTRY structs
							with the size:
								NumGroupsRequested * sizeof(DUS_ENTRY)
		pRethExternalGroups -- pointer to the memory handle of an array of DUS_ENTRY
							structs returned to the caller.  The DUS allocs and assigns
							this handle, sets the user information into the array, and
							returns the handle UNLOCKED to the caller. The array should
							contain *pNumUsersReturned structs.  The caller will
							free the memory associated with the handle.
		pRetGroupEntrySize -- pointer to the size of the DUS_ENTRY struct (an array of
							which are alloced by the DUS and passed back to the caller)

	Comments:	DUSRetrieveGroups will be continue to be called by the DUS framework
				until the DUS returns a resume index of 0 or the *pNumGroupsReturned is
				less than *pNumGroupsRequested.

*************************************************************************/
STATUS	LNCALLBACK	DUSRetrieveGroups(	HANDLE hContext,
									DWORD StartIndex,
									DWORD *pResumeIndex,
									DWORD NumGroupsRequested,
									DWORD *pNumGroupsReturned,
									HANDLE *pRethExternalGroups,
									DWORD *pRetGroupEntrySize);








/*************************************************************************
    FUNCTION: 	DUSGetUserInformation

    Comments:
    	This call supplies the upgrade DLL with one of the users selected
		for upgrade and returns full information for this user.

	Inputs:
		hContext -- handle to this DUS's context information,
					initially set in DUSStart.  Passed with every DUS call.
		UserName -- The text originally supplied to the DUS framework with DUSRetrieveUsers.
		hUserNote -- contains the UserName and ID used by the DUS to identify
					the user for which full information is being requested.
					The DUS stores and passes back information to be set
					in the NAB person document via the hUserNote.
		TotalLeftToRead -- This identifies the number of selected users for
					which full information still needs to be returned by the DUS.
					When this value is 1, it should be the last time DUSGetUserInformation
					is called.  This is passed as a courtesy to the DUS, which
					might be able to make retrieval more efficient if it knows:
					1) the number of users selected
					2) when retrieval is complete
	Outputs:
		hUserNote -- contains the UserName and ID used by the DUS to identify
					the user for which full information is being requested.
					The DUS stores and passes back information to be set
					in the NAB person document via the hUserNote.  When the DUS
					is called before/after user registration (DUSRegistrationNotify
					and optionally, DUSConvertMailFile) this hUserNote will be
					passed back to the DUS.  Any information the DUS needs at that
					time should be stored here, such as information represented by
					the hContext handle passed in to the DUS with every DUS function.
					If the DUS writes it's own non-standard "context" information
					to the hUserNote, it should store this info in one or more
					fields prefixed with "Context", such as "ContextPostOfficeInfo".
					This prevents an unintentional name collision with other field
					names in the hUser Note.

					The hUserNote should NOT be updated or closed by the DUS.  The
					DUS framework (caller) writes additional fields to this note and
					will update/close the hUserNote appropriately. 

	Comments:
*************************************************************************/
STATUS	LNCALLBACK	DUSGetUserInformation(	HANDLE hContext,
										char * UserName,
										NOTEHANDLE hUserNote,
										DWORD TotalLeftToRead);





/***********************************************************************
FUNCTION:	DUSGetGroupInformation

Purpose:
	Returns full information about the group for display immediately
	after the administrator has selected the group from the available list. 

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

	GroupName -- name of the group selected (originally supplied by the DUS
	with DUSRetrieveGroups).

Output:
	Additional group information in the form of fields written to the hNote.
	The following fields can be supplied:
		GroupType -- type of Notes group, if known (Multi-purpose, mail only, etc.)
					Field name is ADMINP_GROUP_TYPE.

		Description -- description of the group if known (MAIL_LISTDESCRIPTION_ITEM)

		ParentGroupNamesList -- list of the groups parent groups, if applicable.
								Field name is USERREG_DUSPARENTGROUPS_ITEM.

		See stdnames.h for the field names of a group document.

************************************************************************/
STATUS	LNCALLBACK	DUSGetGroupInformation(	HANDLE hContext,
										char * GroupName,
										NOTEHANDLE hGroupNote);




/***********************************************************************
FUNCTION:	DUSGetGroupMembers

Purpose:
	Returns membership information about the group.  Members will also be
	added to the selected list for upgrade, depending on options chosen
	by the administrator in the group dialog.  Called after DUSGetGroupInformation
	(the administrator has selected the group from the available list). 

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

	GroupName -- name of the group selected (originally supplied by the DUS
	with DUSRetrieveGroups).

Output:
	Additional group information in the form of fields written to the hNote.

	hUserMembersList -- allocated by the DUS, this is a list containing all
	of the user members of the Group identified by GroupName.

	hGroupMembersList -- allocated by the DUS, this is a list containing all
	of the immediate group members of the Group identified by GroupName.

	These LIST handles must be created with the prefix data type set
	to FALSE (see ListAllocate) and must be passed UNLOCKED back to Notes.
	Notes will take care of deallocation.

Comments:
************************************************************************/
STATUS	LNCALLBACK	DUSGetGroupMembers(	HANDLE hContext,
									char * GroupName,
									NOTEHANDLE hGroupNote,
									HANDLE *phGroupMembersList,
									HANDLE *phUserMembersList);



/***********************************************************************
FUNCTION:	DUSAdvancedDlg

Purpose:
	Allows this dll to put up it's own dialog from the Foreign
	Directory dialog when the "Advanced" button is pushed.

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

Output:
	Advanced dialog put up the by DUS.

Comments:
	DUSStart can return a flag which ORs in fDUSAdvancedDlg.
	If it does so, when the "Advanced" button is pressed
	from the foreign Directory dialog, DUSAdvancedDlg will be called.

	Information collected from the dialog can be stored in the buffer
	represented by hContext, but the handle itself should not change.
************************************************************************/
STATUS	LNCALLBACK	DUSAdvancedDlg(	HANDLE hContext);



/***********************************************************************
FUNCTION:	DUSRegistrationNotify

Purpose:
	Notifies the DUS that Notes user registration for the user represented by
	UserName (and originally retrieved from this DUS) is about to start
	or just finished.  This allows the DUS to take pre or post registration
	action to supplement registration-related activity.

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

Inputs:
	UserName -- lmbcs string identifying the user being registered,
				originally passed in by the DUS with DUSRetrieveUsers.

	hUserNote -- contains user and DUS specific information.

	bAfterEvent -- FALSE if the notification is just prior to user registration,
					TRUE if the notification is just after.

Comments:
	DUSRegistrationNotify is an optional function, which must be implemented
	but can do nothing if not needed by the DUS.
************************************************************************/