MailboxGetVMFile()

 VMFileHandle 	MailboxGetVMFile(
	word 	expectedNumBlocks, 
	word 	*vmStatusp);

This routine obtains the handle of a writable VM file in which data can be stored. The file is managed by the Mailbox library, so the data stored in it can be passed off to the library without being marked as MMF_BODY_DATA_VOLATILE.

Parameters:

expectedNumBlocks: This parameter is your estimate of your file's size, in blocks. The library uses this estimate to rationally apportion data among various VM files without getting block sizes within one file so large that the system is in danger of running out of conventional memory. Poor estimates will usually not cause fatal problems since the library is rather cautious when deciding whether to start a new file. Still, you should do your best to come up with accurate information on your needs. You should request 1 block for every 4Kb of data to store. For example, SMS message would only require 1 block. If expectedNumBlocks is set to zero, then a system-assumed value will be used.
vmStatusp: This is a pointer to a word that, in the case of an error, will be set to the error type.

Returns: If successful, this routine returns a VMFileHandle to a writable VM File. If it fails, it returns NullHandle and sets vmStatusp.

Include: mailbox.h

MailboxGetVMFileName()

void 	MailboxGetVMFileName(
	VMFileHandle 	file, 
	FileLongName 	*namep);

Gets the name of a VM file file which was previously opened by the Mailbox library. This file resides in the Mailbox library's spool directory. namep is a buffer in which to place the file's FileLongName, a null-terminated file name.

Warning: MailboxGetVMFileName() is used primarily by data storage drivers to obtain a persistent reference to the body of a message since file handles aren't preserved across shutdowns or file closes.

Include: mailbox.h

MailboxLoadDataDriver()

 GeodeHandle	MailboxLoadDataDriver(
	MailboxStorage 	storage,
	GeodeLoadError 	*error);

MailboxLoadDataDriver() loads the specified data storage driver.

Parameters:

storage is a MailboxStorage token of the requested data storage driver.

error is a buffer to store a GeodeLoadError should the driver not load properly.

Return: If this routine is successful, it returns the handle of the loaded driver. Otherwise, the error is put into error.

This driver should be unloaded using MailboxFreeDriver() .

Include: mailbox.h

MailboxLoadDataDriverWithError()

 GeodeHandle	MailboxLoadDataDriverWithError(
	MailboxStorage 	storage,
	GeodeLoadError 	*error);

MailboxLoadDataDriverWithError() loads the specified data storage driver. If the driver can't be loaded then the error message error will be used to prompt the user to make the driver available, with the option to retry the load.

Parameters:

storage is a MailboxStorage token of the requested data storage driver.

error should point to a notification string that the user will see if the driver cannot load properly. If error points to NULL, then this routine behaves just like


MailboxLoadDataDriver()

Return: If this routine is successful, it returns the handle of the loaded driver. Otherwise, the error is put into error.

This driver should be unloaded using MailboxFreeDriver().

Include: mailbox.h

MailboxLoadTransportDriver()

 GeodeHandle	MailboxLoadTransportDriver(
	MailboxTransport 	transport,
	GeodeLoadError 	*error);

MailboxLoadTransportDriver() loads the transport driver with the MailboxTransport token transport and returns the handle of the driver. If the driver can't be loaded, then the GeodeLoadError is put into error.

The driver should be unloaded using MailboxFreeDriver() .

Include: mailbox.h

MailboxOpenVMFile()

 VMFileHandle 	MailboxOpenVMFile(
	FileLongName 	*namep, 
	word 	*vmStatusp);

Reopens a VM file that was previously returned by MailboxGetVMFileName() , and whose name namep was obtained through MailboxGetVMFileName. If successful, the routine returns a VMFileHandle to the VMFile. If there is an error, this routine returns NullHandle with vmStatusp filled in with the appropriate VMStatus value.

Warning: Any call to this routine must be matched with a call to MailboxDoneWithVMFile() .

Include: mailbox.h

MailboxPushToMailboxDir()

void 	MailboxPushToMailboxDir();

This routine performs a FilePushDir() followed by a MailboxChangeToMailboxDir() .

Include: mailbox.h

MailboxRegisterMessage()

MailboxError MailboxRegisterMessage(
	MailboxRegisterMessageArgs 	*mrmArgs,
	MailboxMessage 		*msg);

The routine registers a message with the system. A message consists of the information the system needs to properly process that message, the MailboxRegisterMessageArgs mrmArgs, and the body data of the message itself, msg. The body data are copied, if necessary, or simply taken-possession-of by the system.

You can find examples of filling in MailboxRegisterMessageArgs in the chapters that discuss the various communication methods, such as the SMS chapter.

Include: mailbox.h

MailboxSetTransAddr()

 MailboxError	MailboxSetTransAddr(
	MailboxMessage msg, 
	word addrNumber,
	const void *newAddress,
	word addrSize);

Sets the opaque transport address of the addrNumber-th address for the message msg to newAddress, replacing the existing one. addrSzie is the size of the new address buffer, in bytes. This routine returns ME_INVALID_MESSAGE if msg is invalid or ME_NOT_ENOUGH_MEMORY if there is not enough memory.

Warning: The new address may not differ from the old address in its significant address bytes. This is not intended to allow arbitrary redirection of a message, but simply for transport drivers to record their progress for a particular address in the insignificant portion of the address.

See Also: MailboxGetTransAddr()

Include: mailbox.h

MailboxSetTransData()

 MailboxError 	MailboxGetTransData(
	MailboxMessage 	msg, 
	dword 	transData);

This routine replaces the 32-bit transport data registered with the message msg with transData. If the message is invalid then the routine returns ME_INVALID_MESSAGE; if successful, it returns ME_SUCCESS.

Warning: The caller is responsible for freeing any resources referred to by the previous dword transport data since the Mailbox library places absolutely no interpretation on the transData, and thus cannot know what needs to be freed when one transData dword replaces another.

See Also: MailboxGetTransAddr()

Include: mailbox.h

MailboxStealBody()

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

This routine lets an application take possession of the body of the message msg. It puts the app-reference to the body in appRefBuf. The app-reference structure defined for each communication mode is defined in the documentation for that communication mode, e.g. the SMS chapter. The application is responsible for destroying the data associated with this app-reference. If the message body is within a VM file, the application is responsible for calling MailboxDoneWithVMFile() after freeing the data that make up the body. The parameters for this routine are the message msg, a pointer appRefBuf to an app-reference, and a word appRefBufSize that points to the size of appRefBuf, in bytes. appRefBufSize is then filled with the number of bytes that are put into appRefBuf.

The possible errors are ME_INVALID_MESSAGE, ME_NOT_ENOUGH_MEMORY, ME_CANNOT_LOAD_DATA_DRIVER, ME_CANNOT_LOAD_TRANSPORT_DRIVER, ME_APP_REF_BUF_TOO_SMALL, ME_CANNOT_OPEN_MESSAGE_FILE, and ME_CANNOT_READ_MESSAGE_FILE.

Include: mailbox.h