dus.h

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

STATUS	LNCALLBACK	DUSRegistrationNotify(	HANDLE hContext,
										char *UserName,
										NOTEHANDLE hUserNote,
										BOOL bAfterEvent);




/*************************************************************************
FUNCTION: 	DUSConvertMailFile

Purpose:
	Converts DUS mail into Notes mail file.

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

	MailFilePath -- lmbcs string identifying the fully qualified mail
					file path (including mail server) of the empty 
					Notes mail file to be converted.

	hUserNote -- contains user and DUS specific information.

	hNewPersonNote -- the Note handle of the person document just created
				by user registration in the Address book.  If the DUS
				modifies this note it must update the note (NSFNoteUpdate),
				but the DUS framework will close the note.

	SignalStatus -- address of a function to display status in the
				Status bar of the admin panel (below the user reg
				dialog).  The DUS can use this proc to apprise the
				administrator of mail conversion progress if desired.

Comments:
 	DUSConvertMailFile is called after the user has been
 	successfully registered and a Notes mail file (empty)
 	has been created.

Outputs:
	Converted mail file (implicit).
*************************************************************************/
STATUS	LNCALLBACK	DUSConvertMailFile( HANDLE hContext,
									char *UserName,
									char *MailFilePath,
									NOTEHANDLE hUserNote,
									NOTEHANDLE	hNewPersonNote,
									REGSIGNALPROC SignalStatus);



/***********************************************************************
FUNCTION:	DUSStop

Purpose:
	Notifies the DUS that the end of this session (started
	by DUSStart and represented by hContext) is over.  Memory
	associated with the context handle (alloced in DUSStart) should
	now be freed.

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

Comments:
	DUSStop is called from one of two places:
		1)	If the DUS was started from the foreign Directory dialog,
			DUSStop will be called when that dialog is closed.

		2)	If the DUS was started during user registration because
			a user from this DUS was being registered, DUSStop will
			be called when registration of ALL users in that session
			is complete.
************************************************************************/
STATUS	LNCALLBACK	DUSStop( HANDLE hContext);




/*************************************************************************
	FUNCTION: 	DUSTerm

    Comments:
     	This call notifies the DUS DLL that it is being terminated/unloaded.
		Any alloced memory not already freed should be freed here.
*************************************************************************/
STATUS	LNCALLBACK	DUSTerm( void);





/*************************************************************************
    FUNCTION: 	DUSRetrieveUsersEx (Added in R6)

    Purpose:
    	This function allocates and passes back an array of DUS_ENTRY structs
    	containing information about the users in a group, or in a filter search result.

	Inputs:
		hContext -- provided by the DUS with DUSStart and passed back
					with every call by the framework.
		Filter	 -- filter string in application-defined format that user has 
					selected.
		GroupName -- Name of the group, non-NULL if members of the group are requested.
		hGroupNote -- Group Note handle. 
		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 DUSRetrieveUsersEx 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 DUSRetrieveUsersEx
			is called.
			
		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:	- DUSRetrieveUsersEx 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.
				- If group members are retrieved, calls will stop if 65K entries are retrieved.
				65K is the limit imposed by Notes on number of group members.
				- if Filter is NULL, and GroupName is valid, return members of a group.
				if both are NULL, return all entries.
*************************************************************************/
STATUS	LNCALLBACK	DUSRetrieveUsersEx(	HANDLE hContext,
									char * Filter,
									char * GroupName,
									NOTEHANDLE hGroupNote,
									DWORD StartIndex,
									DWORD *pResumeIndex,
									DWORD NumUsersRequested,
									DWORD *pNumUsersReturned,
									HANDLE *pRethExternalUsers,
									DWORD *pRetUserEntrySize);



/*************************************************************************
    FUNCTION: 	DUSRetrieveGroupsEx (added in R6)

    Purpose:
    	This function allocates and passes back an array of DUS_ENTRY structs
    	containing information about the groups in a group, or in a filter search result.

	Inputs:
		hContext -- provided by the DUS with DUSStart and passed back
					with every call by the framework.
		Filter	 -- filter string in application-defined format that user has 
					selected.
		GroupName -- Name of the group, non-NULL if members of the group are requested.
		hGroupNote -- Group Note handle. 
		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 DUSRetrieveGroupsEx 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 DUSRetrieveGroupsEx
			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:	-DUSRetrieveGroupsEx 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.
				- If group members are retrieved, calls will stop if 65K entries are retrieved.
				65K is the limit imposed by Notes on number of group members.
				- if Filter is NULL, and GroupName is valid, return members of a group.
				if both are NULL, return all entries.

*************************************************************************/
STATUS	LNCALLBACK	DUSRetrieveGroupsEx(	HANDLE hContext,
									char * pFilter,
									char * GroupName,
									NOTEHANDLE hGroupNote,
									DWORD StartIndex,
									DWORD *pResumeIndex,
									DWORD NumGroupsRequested,
									DWORD *pNumGroupsReturned,
									HANDLE *pRethExternalGroups,
									DWORD *pRetGroupEntrySize);


/***********************************************************************
FUNCTION:	DUSRetrieveFilters (new in R6)

Purpose:
	Returns default filter strings 

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:
	phDefaultFilters -- allocated by the DUS, this is a list containing default
	filter strings that will be shown in the combobox.

	bAllowType -- flag indicating whether user should be allowed to type 
	other custom filters, or only select from the default ones.

	The LIST handle 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:
	DUSRetrieveFilters is called after DUSStart, in case when the DUS 
	is selected from the combobox. If fDUSUseFilters flag is passed to DUSStart,
	user will be allowed to type other filters, otherwise, (s)he will only be 
	able to choose among default filters, and options such as "All Users and Groups",
	"All Users" and "All Groups". 
************************************************************************/
STATUS	LNCALLBACK	DUSRetrieveFilters(	HANDLE hContext,
										HANDLE *phDefaultFilters);

#endif /* if defined (NT) */

#ifdef __cplusplus
}
#endif

#endif


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