| GEOS C Reference| | LocalLexicalValue()... | MailboxGetBodyFormat() ...

---

MailboxAcknowledgeMessageReceipt()

 void 	MailboxAcknowledgeMessageReceipt(
	MailboxMessage 		msg);

This routine tells the Mailbox library that the application has taken control of the message msg. msg will be visually removed from the system inbox only when this function is called.

Warning: When the mailbox receives a message targeted for an application, it sends that application the message MSG_META_MAILBOX_NOTIFY_MESSAGE_AVAILABLE. Should the application not acknowledge the message with MailboxAcknowledgeMessageReceipt() and the application exits and restarts, the application will again be notified of the message's availability.

Include: mailbox.h

MailboxBodyReformatted()

 MailboxError 	MailboxBodyReformatted(
	MailboxMessage 	msg,
	MailboxDataFormat 	newFormat,
	MailboxMessageFlags 	newBodyFlags);

This routine changes the format indication of the message msg to newFormat and sets the MailboxMessageFlags newBodyFlags to either MMF_BODY_DATA_VOLATILE or MMF_DELETE_BODY_AFTER_TRANSMISSION. This routine does not alter the contents of msg msg.If msg is invalid then a MailboxError will be generated.

The MailboxDataFormat structure is formatted as:

    typedef struct {		        word		MDF_id;     /*GeoworksMailboxDataFormatID*/        ManufacturerID	MDF_manuf;    } MailboxDataFormat;

Warning: MailboxBodyReformatted() is used to change the format of msg in-place. To create a copy of a message in a new format, use MailboxChangeBodyFormat() .

Include: mailbox.h

MailboxChangeBodyFormat()

 MailboxError	MailboxChangeBodyFormat(
	MailboxMessage 	msg,
	const MailboxChangeBodyFormatArgs 	*mcbfArgs);

This routine replaces the format and the body of the message msg with mcbfArgs. If msg is invalid or the body is in use, then a MailboxError will be generated.

Warning: MailboxChangeBodyFormat() should be used when creating a copy of a message in a new format. To reformat the message in-place, use MailboxBodyReformatted() .

Include: mailbox.h

MailboxChangeToMailboxDir()

void	MailboxChangeToMailboxDir(void);

This routine changes the application's current working directoryto the directory where the Mailbox library holds its message bodies and administrative files.

Warning: This is primarily intended for use by data and transport drivers.

Include: mailbox.h

MailboxCheckMediumAvailable()

Boolean  MailboxCheckMediumAvailable(
	MediumType 	mediumType, 
	word 	unitNum, 
	MediumUnitType 	unitType);

If the transmission medium mediumType exists, then this routine returns TRUE (non-zero); otherwise, it returns FALSE (zero). Since the Mailbox library cannot control the comings and goings of the different media, there is no guarantee that a medium which exists now will exist later.

For example, if a modem PCMCIA card is inserted, then the DATA_MODEM medium will be available (and the unit number will be the SERIAL_COMx constant by which the modem can be reached). When the PCMCIA card is removed, then that medium will no longer be available and MailboxCheckMediumAvailable() will return FALSE.

Warning: If unitType is a MUT_MEM_BLOCK (a handle to other data), it means that the Mailbox library will take responsibility for freeing the memory block. In this case, the application should no longer reference the handle it passed in as the unit number.

Include: mailbox.h

MailboxCheckMediumConnected()

Boolean 	MailboxCheckMediumConnected(
	MediumType 	mediumType, 
	word 	unitNum, 
	MediumUnitType 	unitType);

Sees if the Mailbox library has been told whether a connection over the specified transmission medium exists. The medium is not guaranteed to remain connected once this call returns, as the Mailbox library has no control over connections, usually. This routine returns non-zero if, while the call was in-progress, the medium using MediumType mediumType, unit number unitNum (ignored if unitType is set to MUT_NONE), and MediumUnitType unitType were connected; otherwise, the routine returns zero.

Warning: If unitType is a MUT_MEM_BLOCK (a handle to other data), it means that the Mailbox library will take responsibility for freeing the memory block. In this case, the application should no longer reference the handle it passed in as the unit number.

Include: mailbox.h

MailboxDeleteMessage()

 void 	MailboxDeleteMessage(MailboxMessage msg);

This routine lets the Mailbox library know that it is free to delete the message msg. This routine should only be called after the application has called MailboxAcknowledgeMessageReceipt() to acknowledge that it has finished handling the message.

Include: mailbox.h

MailboxDoneWithBody()

 void 	MailboxDoneWithBody(
	MailboxMessage	msg,
	const void 	*appRef, 	
	word 	appRefSize);		

This routine indicates that the body reference appRef returned by an earlier call to MailboxGetBodyRef() will no longer be used, so the data driver is free to close the file, etc. appRef points to the body of the message msg, and appRefSize refers to the size of this body, in bytes.

Warning: After calling this routine, no further use of the body via appRef may be made.

Include: mailbox.h

MailboxDoneWithVMFile()

 void 	MailboxDoneWithVMFile(	VMFileHandle file);

Lets the Mailbox know that the application is done using the file file, a parameter which was returned from MailboxGetVMFile() . The Mailbox library is free to close file after this routine is called.

Include: mailbox.h

MailboxFreeDriver()

void	MailboxFreeDriver(
	GeodeHandle 	driverHandle);

This routine unloads the driver driverHandle previously loaded by the Mailbox library. Note that a call to MailboxLoad...Driver() should be balanced with a call to MailboxFreeDriver() .

See Also: MailboxLoadDataDriver()
MailboxLoadDataDriverWithError()
MailboxLoadTransportDriver()

Include: mailbox.h

MailboxGetAdminFile()

VMFileHandle	MailboxGetAdminFile(void);

Returns the handle of the main administrative VM file that is maintained by the Mailbox library.

Warning: The returned file should NOT be used for general storage of data. This routine is intended to allow applications that wish to register a message without the aid of a MailboxSendControl to create the transData argument required by the transport driver they've chosen, should the driver expect something to be allocated within the admin file.

Include: mailbox.h