nn::cec::CTR::MessageBox Class

class MessageBox

This class is used to access CEC MessageBox objects.

This allows you to create and delete boxes, write and load messages, get box information, and so forth. By creating a box with the CreateMessageBox function and then opening it with the OpenMessageBox function, you can access the messages in that box. You can use the WriteMessage function to write messages to a box. Messages written to the outbox are sent. Received messages are stored in the inbox and can be read with the ReadMessage function.

Call the CloseMessageBox function when you have finished accessing the box. Changes are committed when you call the CloseMessageBox/CommitMessageBox pair. If the program is ended before changes are committed, all changes up to that point are reverted. Changes may also be reverted due to system operations, even when communication control returns to the system, such as when transitioning to Sleep Mode/Home Menu.
Treat the interval from Open/Create to Close as a single unit of processing and block entry to Sleep Mode/Home Menu during that time.

When a message is created and written, a MessageId is given to the message. The MessageId is a randomly generated unique value, and each message is accessed using this value as the key.

Use the GetMessageXXX functions to get various information, such as the attributes of individual messages. Because the GetMessageXXX functions retrieve information from the message list stored in the system, they can get information faster than the message itself can be accessed with ReadMessage. This information is read from the system when the OpenMessageBox function is called. It is possible that the message list stored in the system and the information in the messages themselves may become unsynchronized due to an unexpected power outage or other interruption. (For example, you may be able to get the message ID but ReadMessage may fail.) The message list is regenerated when a message is written with WriteMessage, but if processing enters an irrecoverable state, delete it using DeleteAllMessages and then DeleteMessageBox.

Do not adopt implementations that periodically call the OpenMessageBox and CloseMessageBox functions to check the arrival of messages in real time. Because communication stops whenever the OpenMessageBox function is called, send and receive processes cannot be executed in the background. Use the GetCecEvent and GetCecInfoBuffer functions to find out if there has been communication.

The EULA version to which the user has agreed is checked when a message is written by the WriteMessage function.
You must initialize the FS library before calling this function because the check uses FS library features.

2011/03/18

Renamed functions as follows: GetBoxMessNumMax to GetBoxMessageNumMax; GetBoxMessNum to GetBoxMessageNum; GetMessageMessSize to GetMessageSize; GetMessageMessTypeFlag to GetMessageTypeFlag; GetMessageMessIdPairto GetMessageIdPair; GetMessageMessId to GetMessageId; GetMessIndex to GetMessageIndex

2011/01/24

Added description of errors in OpenMessageBox, ReadMessage, and WriteMessage.

2010/08/16

Initial version.