pgpclientlibwin32.h

PGP8.0源码 请认真阅读您的文件包然后写出其具体功能

/*____________________________________________________________________________
	Copyright (C) 2002 PGP Corporation
	All rights reserved.

	$Id: pgpClientLibWin32.h,v 1.135 2002/11/22 03:10:38 pbj Exp $
____________________________________________________________________________*/
#ifndef Included_pgpClientLibWin32_h	/* [ */
#define Included_pgpClientLibWin32_h

#include <windows.h>
#include "pgpPubTypes.h"

#include "pflPrefTypes.h"
#include "pgpGroups.h"
#include "pgpKeyServerPrefs.h"
#include "pgpReconstruct.h"

#ifdef __cplusplus
extern "C" {
#endif

//	_______________________________________________________
//
//	Library Initialization/Cleanup
//
//	Open library and initialize

//	Entry parameters :
//		pcontext		- receives new PGPContextRef
//		uFlags			- flags for special options

enum
{
	kPGPclUseLocalSDKMode			= (1UL << 0),
	kPGPclNoPrefsFileInit			= (1UL << 1),
	kPGPclEnableNewUserWizard		= (1UL << 2),
	kPGPclForceNewUserWizard		= (1UL << 3),
};

PGPError PGPclExport
PGPclInitLibrary (
		PGPContextRef*	pcontext,
		PGPUInt32		uFlags);

//	Tell clientlib to use another prefs file.  This is needed only by
//	GINA/NPI when clientlib is initialized *before* user logon.
//	Passing in pszPath == NULL will revert to default file.

PGPError PGPclExport
PGPclChangeDefaultPrefsFile (
		char*			pszPath);

//	Close down DLL and purge passphrase buffers.

PGPError PGPclExport
PGPclCloseLibrary (void);


//	_______________________________________________________
//
//	Word wrap convenience functions
//
//	Wrap text using platform independent word wrap code.
//	Output buffer must be freed with PGPclFreeWrapBuffer
//
//	Entry parameters :
//		szInText		- input buffer
//		wrapColumn		- column at which to wrap
//		pszOutText		- buffer to receive pointer to
//						  output buffer containing wrapped text

PGPError PGPclExport
PGPclWrapBuffer (
		char*			szInText,
		PGPUInt16		wrapColumn,
		char**			pszOutText);

//	Free previously-wrapped text buffer.
//
//	Entry parameters :
//		textBuffer		- buffer to free

PGPError PGPclExport
PGPclFreeWrapBuffer (
		char* 			textBuffer);


//	_______________________________________________________
//
//	Unicode convenience functions

//  wrapper for PGPGetPrimaryUserIDName.  This wrapper gets
//	the userid name string then converts from UTF8 to local
//	code page.
//
//	Entry parameters :
//		key				- key to query
//		pszName			- buffer to receive output
//		uMaxLen			- size of output buffer
//		puLen			- receives length of string

PGPError PGPclExport
PGPclGetPrimaryUserIDName (
		PGPKeyDBObjRef	key,
		LPSTR			pszName,
		PGPUInt32		uMaxLen,
		PGPUInt32*		puLen);

//  similar to PGPclGetPrimaryUserIDName, but for getting userid
//	name string directly from the specified userid.  This function
//	get the userid name string then converts from UTF8 to local
//	code page.
//
//	Entry parameters :
//		userid			- userid to query
//		pszName			- buffer to receive output
//		uMaxLen			- size of output buffer
//		puLen			- receives length of string

PGPError PGPclExport
PGPclGetUserIDName (
		PGPKeyDBObjRef	userid,
		LPSTR			pszName,
		PGPUInt32		uMaxLen,
		PGPUInt32*		puLen);

//  wrapper for PGPGetPrimaryUserIDName.  This wrapper gets
//	the userid name string and then ensures that string is
//	in UTF-8 format
//
//	Entry parameters :
//		key				- key to query
//		pszName			- buffer to receive output
//		uMaxLen			- size of output buffer
//		puLen			- receives length of string

PGPError PGPclExport
PGPclGetPrimaryUserIDNameUTF8 (
		PGPKeyDBObjRef	key,
		LPSTR			pszName,
		PGPUInt32		uMaxLen,
		PGPUInt32*		puLen);

//  wrapper for PGPGetPrimaryUserIDName.  This wrapper gets
//	the userid name string and then ensures that string is
//	in UCS2 format
//
//	Entry parameters :
//		key				- key to query
//		pwszName		- buffer to receive output
//		uMaxLen			- size of output buffer
//		puLen			- receives length of string

PGPError PGPclExport
PGPclGetPrimaryUserIDNameUCS2(
		PGPKeyDBObjRef	key,
		LPWSTR			pwszName,
		PGPUInt32		uMaxLen,
		PGPUInt32*		puLen);


//  similar to PGPclGetPrimaryUserIDName, but for getting userid
//	name string directly from the specified userid.  This function
//	get the userid name string then ensures that string is in UTF-8
//	format.
//
//	Entry parameters :
//		userid			- userid to query
//		pszName			- buffer to receive output
//		uMaxLen			- size of output buffer
//		puLen			- receives length of string


PGPError PGPclExport
PGPclGetUserIDNameUTF8 (
		PGPKeyDBObjRef	userid,
		LPSTR			pszName,
		PGPUInt32		uMaxLen,
		PGPUInt32*		puLen);


//	_______________________________________________________
//
//	Miscellaneous common dialogs and UI elements

//	Post PGP preferences property sheets.
//
//	This function posts the "PGP Preferences" property
//	sheet dialog boxes.  Appropriate calls are made set
//	the preferences.
//
//	Entry parameters :
//		context			- PGP library context
//		hwndParent		- handle of parent window
//		prefref			- optional prefref for PGP prefs
//						  NULL => load default PGP prefs
//		prefrefNet		- optional prefref for PGPnet prefs
//						  NULL => load default PGPnet prefs
//		uFlags			- flags for setting admin options
//		uSheetsToShow	- logical OR of following constants
//						  to indicate which sheets to display
//		iStartsheet		- zero-based index of property sheet
//						  page to display initially.
//						  use the below-defined constants
//		keydbMain		- main keydb, if available.  If not
//						  available, NULL is OK.
//
//	This function returns kPGPError_UserAbort (if the user
//	presses the cancel button)

//	flags for "uFlags"
enum
{
	kPGPclEnableBroadcasts			= (1UL << 0),
	kPGPclRespectDisableFlags		= (1UL << 1),

	kPGPclDefaultAdminPrefFlags 	= 0
};

//	preferences pages (used for "panelsToShow" and "panelStart")
enum
{
	kPGPclGeneralPrefs				= (1UL << 0),
	kPGPclKeyringPrefs				= (1UL << 1),
	kPGPclEmailPrefs				= (1UL << 2),
	kPGPclHotkeyPrefs				= (1UL << 3),
	kPGPclKeyserverPrefs			= (1UL << 4),
	kPGPclCAPrefs					= (1UL << 5),
	kPGPclAdvancedPrefs				= (1UL << 6),
	kPGPclPGPdiskPrefs				= (1UL << 7),
	kPGPclPGPnetIDRPrefs			= (1UL << 8),
	kPGPclPGPnetVPNPrefs			= (1UL << 9),
	kPGPclPGPnetAuthPrefs			= (1UL << 10),
	kPGPclPGPnetAdvancedPrefs		= (1UL << 11),

	kPGPclDefaultPrefsPanel			= kPGPclGeneralPrefs,
	kPGPclNumPrefsPanels			= 12
};

PGPError PGPclExport
PGPclAdminPreferences (
		PGPContextRef	context,
		HWND			hwndParent,
		PGPPrefRef		prefref,
		PGPPrefRef		prefrefNet,
		PGPUInt32		uFlags,
		PGPUInt32		uPanelsToShow,
		PGPUInt32		uStartPanel,
		PGPKeyDBRef		keydbMain);

PGPError PGPclExport
PGPclPreferences (
		PGPContextRef	context,
		HWND			hwndParent,
		PGPUInt32		uStartPanel,
		PGPKeyDBRef		keydbMain);

//
//	Get descriptive string for error code for encode/decode modules
//
//	Entry parameters :
//		iCode		- error code returned by pgp or simple library routine
//		szString	- buffer to be filled with descriptive error message
//		uLen		- length of buffer in bytes
//
//	This function evaluates iCode.  If iCode warrants an error
//	message, the buffer is filled with the message and the function
//	returns kPGPError_UnknownError.  If no message is warranted,
//	the function returns kPGPError_NoErr.

PGPError PGPclExport
PGPclEncDecErrorToString (
		PGPInt32		iCode,
		char*			szString,
		PGPUInt32		uLen);

//
//	Putup error messagebox (if necessary) for encode/decode modules
//
//	Entry parameters :
//		hwnd		- handle of parent (NULL is OK)
//		iCode		- error code returned by pgp or simple library routine
//
//	This function calls PGPclErrorToString to evaluate iCode.
//	If PGPclErrorToString returns kPGPError_UnknownError, a message
//  box is posted containing the descriptive text.  Otherwise no
//	messagebox is displayed.

PGPError PGPclExport
PGPclEncDecErrorBox (
		HWND			hwnd,
		PGPError		errIn);

//
//	Get descriptive string for error code
//
//	Entry parameters :
//		iCode		- error code returned by pgp or simple library routine
//		szString	- buffer to be filled with descriptive error message
//		uLen		- length of buffer in bytes
//		puCaptionID	- string ID of caption string
//
//	This function evaluates iCode.  If iCode warrants an error
//	message, the buffer is filled with the message and the function
//	returns kPGPError_UnknownError.  If no message is warranted,
//	the function returns kPGPError_NoErr.

enum
{
	kPGPclErrorType_Error			= 1,
	kPGPclErrorType_Warning			= 2,
	kPGPclErrorType_Alert			= 3,
	kPGPclErrorType_Information		= 4
};

PGPError PGPclExport
PGPclErrorToString (
		PGPInt32		iCode,
		char*			szString,
		PGPUInt32		uLen,
		PGPUInt32*		puCaptionType);

//
//	Putup error messagebox (if necessary)
//
//	Entry parameters :
//		hwnd		- handle of parent (NULL is OK)
//		iCode		- error code returned by pgp or simple library routine
//
//	This function calls PGPclErrorToString to evaluate iCode.
//	If PGPclErrorToString returns kPGPError_UnknownError, a message
//  box is posted containing the descriptive text.  Otherwise no
//	messagebox is displayed.  This function always returns the error
//	code which the caller passes in.

PGPError PGPclExport
PGPclErrorBox (
		HWND			hwnd,
		PGPError		errIn);
		
//
//	Convert UTF8 strings to UCS2 and put up MessageBoxW
//
//	Entry parameters :
//		hwnd			- handle of parent window
//		pszTextUTF8		- main text of messagebox
//		pszCaptionUTF8	- caption string for title bar
//		uType			- flags as used by MessageBox
//
//	This function returns kPGPError_UserAbort (if the user
//  presses the cancel button).

PGPUInt32 PGPclExport
PGPclMessageBoxUTF8 (
		HWND			hwnd,
		char*			pszTextUTF8,
		char*			pszCaptionUTF8,
		UINT			uType);

//
//	Put up dialog to collect entropy from keyboard/mouse.
//
//	Entry parameters :
//		context		- PGP library context
//		hwndParent	- handle of parent window
//		uNeeded		- bits of entropy needed
//
//	This function returns kPGPError_UserAbort (if the user
//  presses the cancel button).

PGPError PGPclExport
PGPclRandom (
		PGPContextRef	context,
		HWND			hwndParent,
		PGPUInt32		uNeeded);

//
//	Post Help|About dialog with button for browser launch to specified URL.
//
//	Entry parameters :
//		context		- current PGP context
//		hwndParent	- handle of parent window
//		szVersion	- string containing version information
//					  to be displayed
//					  NULL => use default version string
//		szLinkText	- text to be displayed on link button
//					  (should be <= ~20 chars),
//					  NULL => use default ("www.pgp.com")
//		szLink		- URL to which to jump
//					  NULL => use default ("http://www.pgp.com/")

PGPError PGPclExport
PGPclHelpAbout (
		PGPContextRef	context,
		HWND			hwndParent,
		char*			szVersion,
		char*			szLinkText,
		char*			szLink);

//
//	Post License Number Dialog
//
//	Entry parameters :
//		context		- current PGP context
//		hwndParent	- handle of parent window

PGPError PGPclExport 
PGPclEnterLicense(
		PGPContextRef	context,
		HWND			hwndParent);

//
//	Post certificate retrieval congratulations dialog
//
//	Entry parameters :
//		hwndParent		- handle of parent window
//		uCongratsType	- type of message text to display
//		pszUserID		- cert userID

enum
{
	kPGPclManualRetrieval				= 0,
	kPGPclAutoRetrievalUsingCert		= 1,
	kPGPclAutoRetrievalQueryUse			= 2
};

PGPError PGPclExport
PGPclCertCongrats (
		HWND			hwndParent,
		PGPUInt32		uCongratsType,
		char*			pszUserID);

//
//	display and handle selective key import dialog - new version
//
//	Entry parameters :
//		hwndParent		- handle of parent window
//		keysetToAdd		- keyset containing keys to add
//		keydbMain		- keydb to which keys will be added
//		uFlags			- logical OR of flags (below)
//
//	Returns kPGPError_NoErr if no error
//

enum
{
	kPGPclNoImportDialog				= (1UL << 0),
	kPGPclNoDialogForValidSingletons	= (1UL << 1),
	kPGPclNoTrustWarningMessage			= (1UL << 2),

	kPGPclDefaultImportFlags 			= 0
};

PGPError PGPclExport
PGPclImportKeys (
		PGPContextRef		context,
		PGPtlsContextRef	tlscontext,
		HWND				hwndParent,
		PGPKeySetRef		keysetToAdd,
		PGPKeyDBRef			keydbMain,
		PGPUInt32			uFlags);

//
//	display keyset and allow user to select keys
//	- original calling parameters
//
//	Entry parameters :
//		hwndParent		- handle of parent window
//		pszPrompt		- prompt string
//		keysetToDisplay	- keyset containing keys to show
//		pkeydbSelected	- buffer to receive keydb ref of selected keys
//
//
//	Returns kPGPError_NoErr if no error

// option flag bits
enum
{
	kPGPclSingleSelection			= (1UL << 0),

	kPGPclDefaultSelectionFlags 	= 0
};

PGPError PGPclExport
PGPclSelectKeys (
		PGPContextRef		context,
		PGPtlsContextRef	tlsContext,
		HWND				hwndParent,
		char*				pszPrompt,
		PGPKeySetRef		keysetToDisplay,
		PGPUInt32			uFlags,
		PGPKeySetRef*		pkeysetSelected);

//