objecthandling.c

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

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

	//if it's the first attachment-descriptor item that's being requested...
	if (ISNULLBLOCKID( (*pbid_itm)))	{
		//if no first attachment-descriptor item can be obtained...
		if (us_err = NSFItemInfo( h_NOTE, pc_ITMNM, us_LEN_ITEMNM, &bid_itm, 
														NULL, &bid_ctnt, NULL))
			//if it's because no 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;
	//else if no next attachment-descriptor item can be obtained...
	}else if (us_err = NSFItemInfoNext( h_NOTE, *pbid_itm, 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 all output variables null, signifying this 
			//	condition
			if (pbid_itm)
				*pbid_itm = ebid_NULLBLOCKID;
			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;
	}

	//fill outputs as requested
	if (pc_objNm)	{
		memcpy( pc_objNm, (char *) (pflo + 1), pflo->FileNameLength);
		pc_objNm[ pflo->FileNameLength] = NULL;
	}
	if (pul_objId)
		*pul_objId = pflo->Header.RRV;
	if (pul_size)
		*pul_size = pflo->FileSize;
	if (pf_compressed)
		*pf_compressed = !!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_getAttachInfoNext(


/** eus_getAttchOriginalNm( ***
Given the internal object name of an attachment, determine its associated 
original filename.

--- parameters & return ----
pc_OBJNM: address of the internal object name of the target attachment
H: handle to the note "containing" the attachment
pc_ITMNM: address of the name of the rich-text field containing the 
	attachment hotspot associated with the target attachment
f_COPY: flag telling whether the caller should be given a duplicate copy of 
	the original filename found (TRUE) or is content with the address of the 
	filename within internal Notes memory which should not be manipulated
ppc: address of pointer variable in which to output the address of the 
	original filename associated with the attachment
RETURN:
	eus_SUCCESS if no errors occurred
	eus_ERR_INVLD_ARG if any input parameter is obviously invalid
	the Notes API error code otherwise

--- revision history ------
?/?/0? PR: created			*/
/*PROTO!!
STATUS eus_getAttchOriginalNm( const char  pc_OBJNM[], 
								NOTEHANDLE  H, 
								char  pc_ITMNM[], 
								const BOOL  f_COPY, 
								char *const * ppc)	{
} //eus_getAttchOriginalNm(
*/

/** eus_AttachBufferAsObject( ***
Construct an object in the target database and note that contains the specified 
content.

--- parameters & return ----
PUC: pointer to the buffer containing the object's content
ul_LEN: length of the object's content
h_DB: Optional. Handle of the database to hold the consturcted object. If NULL, 
	will be manufactured from the h_NOTE input.
h_NOTE: handle of the note to hold a reference item to the object
pc_ITMNM: address of the name of the reference item to be added to the 
	specified note
pc_OBJNM: Address of the name to be associated with the object. If the name is 
	an extended filename, the path portion will be ignored.
us_HOST_TYPE: the Notes "host type" to associate with the object and the 
	reference item
RETURN:
	eus_SUCCESS if no errors occurred
	eus_ERR_INVLD_ARG if any input parameter is obviously invalid
	the Notes API error code otherwise

--- revision history -------
9/6/02 PR: listing format adjustment, minor exception-handling adjustment

8/9/00 PR
+ standard documentation
+ exception-handling adjustment, token renaming

1/30/99 PR: created			*/
STATUS eus_AttachBufferAsObject( const BYTE *const  PUC, 
									const DWORD  ul_LEN, 
									DBHANDLE  h_DB, 
									NOTEHANDLE  h_NOTE, 
									char  pc_ITMNM[], 
									const char  pc_OBJNM[], 
									const WORD  us_HOST_TYPE)	{
	DBHANDLE  h_Db;
	DWORD  ul_objId;
	HANDLE  h;
	STATUS  us_err;

	if (!( PUC && ul_LEN && h_NOTE && pc_ITMNM && pc_OBJNM))
		return eus_ERR_INVLD_ARG;

	//allocate space for the object within the target database
	if (!( h_Db = h_DB))
		NSFNoteGetInfo( h_NOTE, _NOTE_DB, &h_Db);
	if (us_err = NSFDbAllocObject( h_Db, ul_LEN, NOTE_CLASS_DOCUMENT, NULL, 
																	&ul_objId))
		return us_err;

	//allocate generic Notes space for and copy in the object content
	if (us_err = OSMemAlloc( NULL, ul_LEN, &h))
		goto errJump;
	memcpy( OSLockObject( h), PUC, ul_LEN);
	OSUnlockObject( h);

	//add an "object" item to the note that references the object we're creating
	if (us_err = us_AttachObjectItem( h_NOTE, ul_objId, pc_ITMNM, pc_OBJNM, 
														ul_LEN, us_HOST_TYPE))
		goto errJump;

	//copy the object content in the Notes-memory buffer into the space 
	//	allocated for the object in the target database
	us_err = NSFDbWriteObject( h_Db, ul_objId, h, 0L, ul_LEN);

errJump:
	OSMemFree( h);
	if (us_err && ul_objId)
		NSFDbFreeObject( h_Db, ul_objId);

	return us_err;
} //eus_AttachBufferAsObject(


/** eus_AttachFileAsObject( ***
Construct an object in the target database and note from the specified file.

--- parameters & return ----
pc_EXTFILENM: address of the extended filename of the source file to be copied
h_DB: Optional. Handle of the database to hold the consturcted object. If null, 
	will be manufactured from the h_NOTE input.
h_NOTE: handle of the note to hold a reference item to the object
pc_ITMNM: address of the name of the reference item to be added to the 
	specified note
pc_OBJNM: Optional. Address of the name to be associated with the object. If 
	the name is an extended filename, the path portion will be ignored. If 
	null, the filename portion of the source extended filename will be used.
us_HOST_TYPE: the Notes "host type" to associate with the object and the 
	reference item
RETURN:
	eus_SUCCESS if no errors occurred
	eus_ERR_INVLD_ARG if any input parameter is obviously invalid
	the Notes API error code otherwise

--- revision history -------
9/6/02 PR: listing format adjustment, minor exception-handling adjustment, 
	minor documentation adjustment
8/9/00 PR: created			*/
STATUS eus_AttachFileAsObject( const char  pc_EXTFILENM[], 
								DBHANDLE  h_DB, 
								NOTEHANDLE  h_NOTE, 
								char  pc_ITMNM[], 
								const char  pc_OBJNM[], 
								const WORD  us_HOST_TYPE)	{
	DBHANDLE  h_db;
	DWORD  ul_objId;
	FILE * pfl;
	int  i;
	HANDLE  h = NULL;
	STATUS  us_err;

	if (!( pc_EXTFILENM && h_NOTE && pc_ITMNM))
		return eus_ERR_INVLD_ARG;

	//allocate space for the object within the target database
	if (!(pfl = fopen( pc_EXTFILENM, "rb")))
		return !eus_SUCCESS;
	if (us_err = ((i = filelength( fileno( pfl))) == ei_FAIL))
		goto errJump;
	if (!( h_db = h_DB))
		NSFNoteGetInfo( h_NOTE, _NOTE_DB, &h_db);
	if (us_err = NSFDbAllocObject( h_db, i, NOTE_CLASS_DOCUMENT, NULL, 
																	&ul_objId))
		goto errJump;

	//allocate generic Notes space for and copy in the object content
	if (us_err = OSMemAlloc( NULL, i, &h))
		goto errJump;
	if (fread( OSLockObject( h), 1, i, pfl) != (UINT) i)
		goto errJump;
	OSUnlockObject( h);

	//add an "object" item to the note that references the object we're creating
	if (us_err = us_AttachObjectItem( h_NOTE, ul_objId, pc_ITMNM, pc_OBJNM ? 
													pc_OBJNM : pc_EXTFILENM, 
													i, us_HOST_TYPE))
		goto errJump;

	//copy the object content in the Notes-memory buffer into the space 
	//	allocated for the object in the target database
	us_err = NSFDbWriteObject( h_db, ul_objId, h, 0L, i);

errJump:
	if (fclose( pfl) == EOF && us_err)
		us_err = !eus_SUCCESS;
	if (h)
		OSMemFree( h);
	if (us_err && ul_objId)
		NSFDbFreeObject( h_db, ul_objId);

	return us_err;
} //eus_AttachFileAsObject(


/** eus_getObjectContentsInBuffer( ***
Purpose is to copy the contents of a database object (usually a file) into 
a handled buffer. If the object is not compressed, it is more efficient to 
provide the object ID as opposed to the item BlockID associated with the 
note item referring to the object.

--- parameters & return ----
ul_OBJID: Provisionally Optional. The ID (RRV) of the object in the database. 
	Ignored if bid_ITEM is provided; required otherwise.
bid_ITEM: Optional. The item BlockID associated with the note item referring 
	to the object.
ul_LEN_CONTENT: Optional. The length of the content to be read into the 
	handled buffer. If omitted or equal to the API's MAXDWORD constant, the 
	entire content of the object will be read into the buffer.
h_NOTE: Provisionally Optional. If bid_ITEM is provided, the handle to the 
	note containing the item referring to the object. Else if bid_ITEM not 
	provided, the handle to any note in the database containing the object, 
	although not necessary if h_DB is provided.
h_DB: Optional. Handle to the database containing the object. Ignored if 
	bid_ITEM is provided. Otherwise if not provided, the handle will be 
	determined using by means of the h_NOTE parameter.
ph_contents: Pointer to the variable in which to store the handle to the 
	buffer filled with the object's content.
RETURN: eus_SUCCESS if no error occured. The Notes API error code if an API 
	error occurred. !eus_SUCCESS if the object contained less content than 
	that specified by ul_LEN_CONTENT.

--- revision history -------
9/12/99 PR
+ overhauled to make more generic
+ full documentation added

12/12/98 PR: created		*/
STATUS eus_getObjectContentsInBuffer( const DWORD  ul_OBJID, 
										const BLOCKID  bid_ITEM, 
										const DWORD  ul_LEN_CONTENT, 
										NOTEHANDLE  h_NOTE, 
										DBHANDLE  h_DB, 
										HANDLE *const  ph_contents)	{
	static const char  pc_FILENM_TEMP[] = "~gocib.tmp";

	static char  pc_extFileNmTemp[ mus_MAXBUF_EXTFILENM - 
													sizeof( pc_FILENM_TEMP)];

	DBHANDLE  h_Db;
	HANDLE  h = NULL;
	STATUS  us_error = NULL;
	BOOL  f_failure = FALSE;

	if (!( (ul_OBJID || bid_ITEM.pool) && (bid_ITEM.pool ? (BOOL) h_NOTE : 
													(!h_DB ? (BOOL) h_NOTE : 
													TRUE)) && ph_contents))
		return !eus_SUCCESS;

	*ph_contents = NULL;

	//if we're dealing with files here...
	if (bid_ITEM.pool)	{
		unsigned long  ul;
		int  i_err;

		//if this is the first time through with a file, initialize the 
		//	variable to hold the path to the user's temporary directory
		if (!*pc_extFileNmTemp)	{
			if (!epc_getTempDirNm( pc_extFileNmTemp, mus_MAXBUF_EXTFILENM - 
																		2))
				return !eus_SUCCESS;
			strcat( pc_extFileNmTemp, pc_FILENM_TEMP);
		}

		//extract the file as a temporary file on the file system
		if (us_error = NSFNoteExtractFile( h_NOTE, bid_ITEM, 
													pc_extFileNmTemp, NULL))
			return us_error;

		//if necessary, determine the length of the content to be read into 
		//	the buffer
		if (!ul_LEN_CONTENT || ul_LEN_CONTENT == MAXDWORD)	{
			struct stat  st;

			if (f_failure = !stat( pc_extFileNmTemp, &st))
				goto errJump;

			if (f_failure = (ul = st.st_size) <= 0)
				goto errJump;
		}else
			ul = ul_LEN_CONTENT;

		//allocate a handled buffer to accommodate the content we're going to 
		//	read
		if (us_error = OSMemAlloc( NULL, ul, &h))
			goto errJump;

		//read the specified amount of content from the file into the buffer
		f_failure = !ef_LoadBinaryFile( pc_extFileNmTemp, OSLockObject( h), 
																		ul);
		OSUnlockObject( h);
		if (f_failure)
			goto errJump;

		//delete the temporary file, ignoring failure
		i_err = remove( pc_extFileNmTemp);
		_ASSERTE( i_err == eus_SUCCESS);
	}else {
		if (!( h_Db = h_DB))
			NSFNoteGetInfo( h_NOTE, _NOTE_DB, &h_Db);
		if (us_error = NSFDbReadObject( h_Db, ul_OBJID, 0, ul_LEN_CONTENT ? 
											ul_LEN_CONTENT : MAXDWORD, &h))	{
			_ASSERTE( !h);
			return us_error;
		}
	} //if (bid_ITEM.pool)

	*ph_contents = h;

	return eus_SUCCESS;

errJump:
	if (f_failure)
		remove( pc_extFileNmTemp);

	return us_error + f_failure;
} //eus_getObjectContentsInBuffer(