MailboxGetBodyFormat()

 MailboxError	MailboxGetBodyFormat(
	MailboxMessage 	msg,
	MailboxDataFormat 	*dataFormat);

This routine gets the MailboxDataFormat token of the message msg and copies it into dataFormat. It returns a MailboxError if the routine is invalid.

Include: mailbox.h

MailboxGetBodyMboxRefBlock()

 MailboxError	MailboxGetBodyMboxRefBlock(
	MailboxMessage 	msg,
	MemHandle 	*mboxRefHandle);

Fetches the opaque mailbox reference to the message body of message msg and stores it in the block mboxRefHandle. This returned block contains a mailbox reference structure specific to the Data Driver. Examples are:

	/* for mailbox data drivers that use VMChains */
	typedef {  
		dword VMTMR_vmChain;
		TCHAR VMTMR_filename[];
	} VMTreeMboxRef;

	/* for mailbox data drivers that use raw data files */
	typedef {
		Boolean FMR_deleteAfterTransmit;
		word FMR_diskDataOffset;
		word FMR_diskDataLen;
		word FMR_filenameLen;
		byte FMR_filenameAndDiskData[];
			/* start of null-terminated filename, 
			 * followed by diskData (at 
			 * FMR_diskDataOffset). */
	} FileDDMboxRef;

The routine returns ME_INVALID_MESSAGE if the message is invalid, or ME_NOT_ENOUGH_MEMORY if the block of data could not be created.

Note: This routine is normally used by the mailbox drivers, not by applications.

Include: mailbox.h

MailboxGetBodyRef()

 MailboxError	MailboxGetBodyRef(
	MailboxMessage 	msg,
	void 	*appRefBuf, 		
	word 	*appRefBufSize);

This routine retrieves the address of the message body of the message msg in the format understood and used by applications registering a message with the Mailbox library, the app-reference. The definitions of app-reference structures are defined in the documentation for each of the various communication methods, e.g. the SMS chapter. This reference to the body is copied into the buffer appRefBuf. appRefBufSize initially points to the size of this buffer in bytes, and then it is set to the number of bytes that were copied into the buffer. In the case of an error (msg is invalid, the library is unable to load the driver, there is insufficient memory, the app-ref buffer too small, there is no message body available) a MailboxError will be generated.

Warning: Each call to this routine must be matched by a call to MailboxDoneWithBody() .

Include: mailbox.h

MailboxGetDestApp()

 MailboxError	MailboxGetDestApp(
	MailboxMessage 	msg,
	GeodeToken 	*tokenBuf);

Gets the GeodeToken for the destination application from the message msg and copies it into tokenBuf. This routine returns ME_INVALID_MESSAGE if the passed MailboxMessage is invalid.

Include: mailbox.h

MailboxGetEndBound()

 MailboxError	MailboxGetEndBound(
	MailboxMessage 	msg,
	FileDateAndTime 	*dateTime);

Fetches the end bound of the message msg and copies it into dateTime. If the message is invalid, this routine returns ME_INVALID_MESSAGE.

See Also: MailboxGetStartBound()

Include: mailbox.h

MailboxGetFirstMediumUnit()

 word	 MailboxGetFirstMediumUnit(
	MediumType 	mediumType, 
	MediumUnitType 	*unitType);

Puts the first available unit of the indicated MediumType mediumType into unitType. This should be used when a transport driver just wants to use a particular medium but doesn't care which one. This routine returns the unit number.

Warning: Do not call this for a medium that doesn't use unit numbers. You will generate a fatal-error in the error-checking version, and won't get any additional information in the non-error-checking version (since the return will be MUT_NONE whether there's an available unit or not). Use MailboxCheckMediumAvailable() instead. Also remember, if unitType is a handle to other memory because it is a MUT_MEM_BLOCK, it will be your responsibility to free the associated memory block.

Include: mailbox.h

MailboxGetMessageFlags()

 MailboxError	MailboxGetMessageFlags(
	MailboxMessage 	msg,
	MailboxMessageFlags 	*flags);

Retrieves the MailboxMessageFlags for the message msg and copies them into flags. If the message is invalid, ME_INVALID_MESSAGE is returned.

Include: mailbox.h

MailboxGetNumTransAddrs()

 MailboxError	MailboxGetNumTransAddrs(
	MailboxMessage 		msg, 
	word 	*numAddresses);

Retrieves the number of transport addresses bound to the message msg and stores that number in numAddresses. If msg is in the inbox, then numAddressess is set to zero. If the number of addresses can't be obtained, then the routine returns ME_INVALID_MESSAGE.

See Also: MailboxGetTransAddr()

Include: mailbox.h

MailboxGetStartBound()

 MailboxError	MailboxGetStartBound(
	MailboxMessage 	msg,
	FileDateAndTime	*dateTime);

Fetches the start bound of the message msg and copies it into dateTime. If the message is invalid, this routine returns ME_INVALID_MESSAGE.

See Also: MailboxGetEndBound()

Include: mailbox.h

MailboxGetStorageType()

 MailboxError 	MailboxGetStorageType(
	MailboxMessage 	msg,
	MailboxStorage 	*storage);

This routine gets the MailboxStorage token for the message msg and copies it into storage. If the message is invalid, ME_INVALID_MESSAGE is returned.

Include: mailbox.h

MailboxGetSubjectBlock()

 MailboxError	MailboxGetSubjectBlock(
	MailboxMessage 	msg, 
	MemHandle 	*subjHandle);

Retrieves the null-terminated subject/summary of the message msg and copies it into a global memory block, then puts the associated MemHandle into subjHandle. Returns ME_INVALID_MESSAGE if msg is invalid or ME_NOT_ENOUGH_MEMORY if there isn't sufficient memory to create the block.

Include: mailbox.h

MailboxGetSubjectLMem()

 MailboxError	MailboxGetSubjectLMem(
	MailboxMessage 	msg, 
	MemHandle 	lmemBlock, 
	ChunkHandle 	*subjectChunk);

Retrieves the subject/summary of the message msg and copies it into a local memory block lmemBlock, and puts the ChunkHandle for this null-terminated subject into subjectChunk. Returns ME_INVALID_MESSAGE if msg is invalid or ME_NOT_ENOUGH_MEMORY if there isn't sufficient memory to create the block.

Include: mailbox.h

MailboxGetTransAddr()

 Boolean	MailboxGetTransAddr(
	MailboxMessage 	msg, 
	word 	addrNumber,
	void 	*addressBuffer,
	word 	*bufSizePtr);

This routine retrieves the addrNumber-th transport address from the message msg and copies the address into addressBuffer. bufSizePtr should initially point to the size of the buffer in bytes and, if the routine works successfully, it will be set to the number of bytes that were actually copied into addressBuffer. If the addrNumber is invalid because it is either too large or the message doesn't exist, then bufSizePtr will be set to zero. If the buffer isn't large enough to store the address, then bufSizePtr is set to the number of bytes required. The routine returns zero (FALSE) if an error occurred, otherwise it returns non-zero.

See Also: MailboxGetNumTransAddrs() MailboxGetUserTransAddrLMem() MailboxSetTransAddr()

Include: mailbox.h

MailboxGetTransData()

 MailboxError 	MailboxGetTransData(
	MailboxMessage 	msg, 
	dword 	*transData);

Puts the 32-bit transport data registered with the message msg into transData. If msg is an invalid message then the routine returns ME_INVALID_MESSAGE.

See Also: MailboxSetTransData()

Include: mailbox.h

MailboxGetUserTransAddrLMem()

 MailboxError 	MailboxGetUserTransAddrLMem(
	MailboxMessage 	msg, 
	word 	addrNumber,
	MemHandle 	lmemBlock,
	ChunkHandle 	*addrChunk);

Retrieves a user-readable transport address from a message. The input parameters are the message msg, the address number addrNumber, and the handle of the lmem block lmemBlock in which to place the string. The routine copies the null-terminated string into this block, and sets addrChunk to point to the string's chuck. There are three errors that could occur: if addrNumber is not valid, ME_ADDRESS_INVALID is returned; if msg is not valid, ME_INVALID_MESSAGE is returned; and if there is insufficient memory to create the chunk, ME_NOT_ENOUGH_MEMORY is returned;

See Also:MailboxGetTransAddr()

Include: mailbox.h

This document is in Beta. Ride at your own risk. Mail us your comments and suggestions