objecthandling.c

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

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


	$Id: ObjectHandling.c,v 1.9 2002/09/09 00:31:43 sdas Exp $
______________________________________________________________________________*/

/*::: MODULE OVERVIEW :::::::::::::
Library/abstract data type that facilitates object handling within a Notes 
database.

--- suggested enhancement ---
9/16/00 PR: complete the stubbed-out eus_getAttchOriginalNm()

--- revision history --------
9/6/02 Version 1.2 Paul Ryan
+ listing format adjustment

9/16/00 Version 1.1.3 Paul Ryan
+ stubbed out a eus_getAttchOriginalNm() function
+ minor improvements to eus_getAttachmentInfo(), including documentation 
  addition

8/9/00 Version 1.1.2 Paul Ryan
+ added eus_AttachFileAsObject()
+ documentation addition

3/20/00 Version 1.1.1 Paul Ryan
+ minor documentation adjustment

9/12/99 Version 1.1 Paul Ryan
+ genericization, documentation of eus_getObjectContentsInBuffer()

12/10/98 Version 1.0 Paul Ryan
::::::::::::::::::::::::::::::::::::*/

#include "ObjectHandling.h"


//global-scope declaration
char  epc_ITEMNM_STANDARD_ATTACH[] = ITEM_NAME_ATTACHMENT;

//module-scope declaration
#define mus_MAXBUF_EXTFILENM  255


/** us_AttachObjectItem( ***


--- parameters & return ----

RETURN: eus_SUCCESS if no error occured; the Notes API error code otherwise

--- revision history -------
1/30/99 PR: created			*/
//DOC!!
static STATUS us_AttachObjectItem( NOTEHANDLE  h_NOTE, 
									const DWORD  ul_OBJ_ID, 
									char  pc_ITMNM[], 
									const char  pc_OBJNM[], 
									const DWORD  ul_OBJ_SIZE, 
									const WORD  us_HOST_TYPE)	{
	const char * pc_objNm;
	BLOCKID  bid;
	WORD * pus, us_lenItem;
	TIMEDATE  td;
	FILEOBJECT * pt_itmInfo;
	WORD  us;
	STATUS  us_error;

	if (!( h_NOTE && ul_OBJ_ID && pc_ITMNM && pc_OBJNM && ul_OBJ_SIZE))
		return !eus_SUCCESS;

	//if we're dealing with a simple filename (no path)...
	if (!( pc_objNm = strrchr( pc_OBJNM, ec_PATH_SPECIFIER)))
		//use that filename as the object name
		pc_objNm = pc_OBJNM;
	//else step to the character immediately following the last backslash 
	//	and have that tail-end simple filenmae be the object name
	else
		pc_objNm++;

	if (us_error = OSMemAlloc( NULL, us_lenItem = sizeof( WORD) + sizeof( 
											FILEOBJECT) + (us = (WORD) 
											strlen( pc_objNm)), &bid.pool))
		return us_error;
	bid.block = NULLBLOCK;

	pus = OSLockBlock( WORD, bid);
	*pus = TYPE_OBJECT;

	//Fill in the item structure used to describe the object to the note 
	//	"hosting" the object. A host type of "MSDOS" in needed in order to 
	//	ensure that the object travels with the rich-text field when the 
	//	message is forwarded or replied to "with history" ("unknown" works 
	//	as well). I'm not sure what the "in-doc" flag does, but Notes seems 
	//	to put it on every attachment, so we will too.
	pt_itmInfo = (FILEOBJECT *) (pus + 1);
	pt_itmInfo->Header.ObjectType = OBJECT_FILE;
	pt_itmInfo->Header.RRV = ul_OBJ_ID;
	pt_itmInfo->FileNameLength = us;
	pt_itmInfo->HostType = us_HOST_TYPE;
	pt_itmInfo->FileAttributes = NULL;	//i.e. Read/Write & Public
	pt_itmInfo->Flags = FILEFLAG_INDOC;
	pt_itmInfo->FileSize = ul_OBJ_SIZE;
	pt_itmInfo->CompressionType = NULL;
	OSCurrentTIMEDATE( &td);
	pt_itmInfo->FileCreated = pt_itmInfo->FileModified = td;

	memcpy( (BYTE *) pt_itmInfo + sizeof( FILEOBJECT), pc_objNm, us);
	OSUnlockBlock( bid);

	us_error = NSFItemAppendObject( h_NOTE, NULL, pc_ITMNM, (WORD) strlen( 
											pc_ITMNM), bid, us_lenItem, TRUE);

	if (us_error)
		OSMemFree( bid.pool);

	return us_error;
} //us_AttachObjectItem(


/** eus_getAttachmentInfo( ***
Obtain descriptive information on the attachment specified by name.

--- parameters & return ----
h_NOTE: handle to the note containing the item descriptor associated with the 
	specified attachment
pc_ITM_NM: Optional. Address of the name of the item descriptor associated with 
	the attachement. If null, the default item name will be used.
pc_OBJNM: Optional. Address of the unique internal name (object name) of the 
	attachment for which information is sought. If null, information will be 
	returned on the first item found.
pul_objId: Optional Output. Address of variable in which to store the RRV ID 
	associated with the specified object (see Notes API documentation re what 
	this is). If null, the output will be skipped.
pul_size: Optional Output. Address of variable in which to store the original 
	(i.e. uncompressed) size of the attachment. If null, the output will be 
	skipped.
pf_cmprssd: Optional Output. Address of variable in which to store whether the 
	attachment is stored compressed (TRUE) or not (FALSE). If null, the output 
	will be skipped.
pus_host: Optional Output. Address of variable in which to store the host type 
	associated with the object. If null, the output will be skipped.
pbid_itm: Optional Output. Address of BlockID structure in which to store 
	the _item_ BlockID associated with the item descriptor for the attachment. 
	If null, the output will be skipped.
pbid_ctnt: Optional Output. Address of the BlockID structure in which to store 
	the _content_ BlockID that contains attachment information. If null, the 
	output will be skipped.
RETURN:
	eus_ERR_INVLD_ARG if any input parameter is obviously invalid
	ERR_ITEM_DATATYPE if the item found is not an attachment descriptor
	the Notes API error code if any error other than ERR_ITEM_NOT_FOUND occurred
	eus_SUCCESS otherwise

--- revision history -------
9/6/02 PR
+ extended to allow output of object type, prompting a signature change
+ extended to allow the object-name input to be optional
+ fixed logic error that was probably causing a memory leak
+ fixed bug by which false-positive matches could be returned
+ listing format adjustment, minor documentation adjustment, minor token 
  renaming

9/16/00 PR
+ made the string matching case insensitive
+ logic shortening
+ minor token renaming, error-handling improvement
+ completed standard documentation

9/12/99 PR: added compressed-flag return
1/31/99 PR: created			*/
STATUS eus_getAttachmentInfo( NOTEHANDLE  h_NOTE, 
								char  pc_ITM_NM[], 
								const char  pc_OBJNM[], 
								DWORD *const  pul_objId, 
								DWORD *const  pul_size, 
								BOOL *const  pf_cmprssd, 
								WORD *const  pus_host, 
								BLOCKID *const  pbid_itm, 
								BLOCKID *const  pbid_ctnt)	{
	char *const  pc_ITMNM = pc_ITM_NM ? pc_ITM_NM : ITEM_NAME_ATTACHMENT;
	const WORD  us_LEN_ITEMNM = strlen( pc_ITMNM), 
				us_LEN_OBJNM = pc_OBJNM ? strlen( pc_OBJNM) : NULL;

	BLOCKID  bid_itm, bid_ctnt, bid_prvItm;
	BYTE * puc;
	const FILEOBJECT * pflo;
	STATUS  us_err;

	if (!h_NOTE)
		return eus_ERR_INVLD_ARG;

	if (pul_objId)
		*pul_objId = NULL;
	if (pul_size)
		*pul_size = NULL;
	if (pf_cmprssd)
		*pf_cmprssd = NULL;
	if (pus_host)
		*pus_host = NULL;
	if (pbid_itm)
		*pbid_itm = ebid_NULLBLOCKID;
	if (pbid_ctnt)
		*pbid_ctnt = ebid_NULLBLOCKID;

	//Get information about the first attachment item. If no such item exists, 
	//	return success with the output variables null, signifying this 
	//	condition.
	if (us_err = NSFItemInfo( h_NOTE, pc_ITMNM, us_LEN_ITEMNM, &bid_itm, NULL, 
															&bid_ctnt, NULL))
		if (ERR( us_err) == ERR_ITEM_NOT_FOUND)
			return eus_SUCCESS;
		else
			return us_err;

	//if the type of the item doesn't support attachments, short-curcuit with 
	//	failure
	if (!*(WORD *) (puc = OSLockBlock( BYTE, bid_ctnt)) == TYPE_OBJECT || 
								(pflo = (FILEOBJECT *) (puc + sizeof( 
								WORD)))->Header.ObjectType != OBJECT_FILE)	{
		us_err = ERR_ITEM_DATATYPE;
		goto errJump;
	}

	//if this isn't the item we're looking for, see if an ensuing one might 
	//	be...
	if (us_LEN_OBJNM)
		while (!( us_LEN_OBJNM == pflo->FileNameLength && strnicmp( pc_OBJNM, 
												(char *) (pflo + 1), 
												us_LEN_OBJNM) == ei_SAME))	{
			//if no next attachment-descriptor item can be obtained...
			OSUnlockBlock( bid_ctnt);
			bid_prvItm = bid_itm;
			if (us_err = NSFItemInfoNext( h_NOTE, bid_prvItm, pc_ITMNM, 
													us_LEN_ITEMNM, &bid_itm, 
													NULL, &bid_ctnt, NULL))
				//if it's because no further item by that name exists...
				if (ERR( us_err) == ERR_ITEM_NOT_FOUND)
					//return success with the output variables null, signifying 
					//	this condition
					return eus_SUCCESS;
				//else short-circuit with failure
				else
					return us_err;

			//if the type of the item can't describe an attachment, 
			//	short-curcuit with failure
			if (!*(WORD *) (puc = OSLockBlock( BYTE, bid_ctnt)) == 
								TYPE_OBJECT || (pflo = (FILEOBJECT *) 
								(puc + sizeof( WORD)))->Header.ObjectType != 
								OBJECT_FILE)	{
				us_err = ERR_ITEM_DATATYPE;
				goto errJump;
			}
		} //while (!( us_LEN_OBJNM == pflo->FileNameLength && strnicmp(

	//fill outputs as requested
	if (pul_objId)
		*pul_objId = pflo->Header.RRV;
	if (pul_size)
		*pul_size = pflo->FileSize;
	if (pf_cmprssd)
		*pf_cmprssd = !!pflo->CompressionType;
	if (pus_host)
		*pus_host = pflo->HostType;
	if (pbid_itm)
		*pbid_itm = bid_itm;
	if (pbid_ctnt)
		*pbid_ctnt = bid_ctnt;

errJump:
	OSUnlockBlock( bid_ctnt);

	return us_err;
} //eus_getAttachmentInfo(


/** eus_DeleteAttachment( ***
Deletes the identified attachment from its note and database.

--- parameters & return ----
h_NOTE: handle to the note holding the identified attachment
pc_OBJNM: Optional. The object-name of the attachment (as opposed to the 
	filename that might be otherwise stored in a rich-text attachment hotspot). 
	If null, the first file-attachment item found using the pc_ITMNM input will 
	be processed.
pc_ITMNM: Optional. The name of the item associated with the attachment to be 
	deleted (as well as the item). If null, the default item name will be used.
RETURN:
	eus_SUCCESS if no error occured
	eus_ERR_INVLD_ARG if any input parameter is obviously invalid
	ERR_ITEM_DATATYPE if the item found is not an attachment descriptor
	ERR_ITEM_NOT_FOUND if the identified attachment could not be located
	the Notes API error code otherwise

--- revision history ------
9/6/02 PR: created			*/
STATUS eus_DeleteAttachment( NOTEHANDLE  h_NOTE, 
								const char  pc_OBJNM[], 
								char  pc_ITMNM[])	{
	BLOCKID  bid_itm;
	STATUS  us_err;

	if (!h_NOTE)
		return eus_ERR_INVLD_ARG;

	//get the info we need on the requested attachment
	if (us_err = eus_getAttachmentInfo( h_NOTE, pc_ITMNM, pc_OBJNM, NULL, NULL, 
													NULL, NULL, &bid_itm, NULL))
		return us_err;
	if (!bid_itm.pool)
		return ERR_ITEM_NOT_FOUND;

	//delete the attachment by regular means
	return NSFNoteDetachFile( h_NOTE, bid_itm);
} //eus_DeleteAttachment(


/** eus_getAttachInfoNext( ***
Obtain descriptive information on the next attachment found associated with a 
given item name.

--- parameters & return ----
h_NOTE: handle to the note containing the item descriptor associated with the 
	sought-for attachment
pc_ITM_NM: Optional. Address of the name of the item descriptor associated with 
	the attachement. If null, the default item name will be used.
pbid_itm: Input & Output. Address of the item-BLOCKID structure associated with 
	the item descriptor of the attachment preceding the attachment about which 
	information is being sought. If null, information about the first 
	attachment found will be output. For output, parameter will be reset to the 
	address of the item-BLOCKID structure associated with the item descriptor 
	of the next attachment found. If a next one is not found, address will be 
	nullified.
pc_objNm: Optional Output. Address of buffer into which the name of the object 
	is copied. If null, the output will be skipped.
pul_objId: Optional Output. Address of variable in which to store the RRV ID 
	associated with the specified object (see Notes API documentation re what 
	this is). If null, the output will be skipped.
pul_size: Optional Output. Address of variable in which to store the original 
	(i.e. uncompressed) size of the attachment. If null, the output will be 
	skipped.
pf_compressed: Optional Output. Address of variable in which to store whether 
	the attachment is stored compressed (TRUE) or not (FALSE). If null, the 
	output will be skipped.
pus_host: Optional Output. Address of variable in which to store the host type 
	associated with the object. If null, the output will be skipped.
pbid_ctnt: Optional Output. Address of the BlockID structure in which to store 
	the _content_ BlockID that contains attachment information. If null, the 
	output will be skipped.
RETURN:
	eus_ERR_INVLD_ARG if any input parameter is obviously invalid
	ERR_ITEM_DATATYPE if an item is found (by name) that cannot be an 
		attachment descriptor
	the Notes API error code if any error other than ERR_ITEM_NOT_FOUND occurred
	eus_SUCCESS otherwise

--- revision history -------
9/6/02 PR: created			*/
STATUS eus_getAttachInfoNext( NOTEHANDLE  h_NOTE, 
								char  pc_ITM_NM[], 
								BLOCKID *const  pbid_itm, 
								char  pc_objNm[], 
								DWORD *const  pul_objId, 
								DWORD *const  pul_size, 
								BOOL *const  pf_compressed, 
								WORD *const  pus_host, 
								BLOCKID *const  pbid_ctnt)	{
	char *const  pc_ITMNM = pc_ITM_NM ? pc_ITM_NM : ITEM_NAME_ATTACHMENT;
	const WORD  us_LEN_ITEMNM = strlen( pc_ITMNM);

	BLOCKID  bid_itm, bid_ctnt;
	BYTE * puc;
	const FILEOBJECT * pflo;
	STATUS  us_err;

	if (!( h_NOTE && pbid_itm))
		return eus_ERR_INVLD_ARG;

	if (pc_objNm)
		*pc_objNm = NULL;