nn::cec::CTR::MessageBox::WriteMessage Member Function

Syntax

nn::Result WriteMessage(
     const Message & cecMessage,
     const CecBoxType boxType,
     MessageId & messageIdOut,
     bool withWriteBoxInfo
);

Parameters

Name Description
in cecMessage An object of the Message class.
in boxType Inbox and outbox specification.
out messageIdOut Returns the MessageId that is assigned during the write operation.
in withWriteBoxInfo Updates to the internal message list are skipped when false is specified. The list is updated when the CommitMessageBox or CloseMessageBox function is called.

Return Values

nn::Result

Value Description
Result::IsSuccess Succeeded.
ResultNotAuthorized The box has not been opened.
ResultMessTooLarge The message is too large.
ResultBoxSizeFull The box's capacity has been exceeded.
ResultBoxMessNumFull The maximum number of boxes has been exceeded.
ResultNoData No message body or icon has been set for the message.
ResultInvalidCombination The send count and propagation count have both been set equal to a value of 2 or greater.
ResultNotAgreeEula The EULA has not been agreed to, or no icon file (.icn) is configured in the ROM.
ResultParentalControlCec Not allowed by Parental Controls.
ResultStateBusy Unable to access because the daemon is busy (BUSY state). It may succeed if you wait some time before accessing again.
ResultBufferFull Could not allocate the memory required for the process.
Any other value Process failed.

Description

Writes a message to the system save region.

The message cannot be written if it is larger than 100 KB (including data such as the header and icon), or if it would exceed the box's maximum save capacity or maximum number of messages. You can use the Message::GetMessageSize function to get the message size. Because NAND memory (the save region) uses a block size of 4 KB, for some message sizes it may be impossible to write up to the maximum storage capacity. If the message size is 5 KB, a NAND memory region of 8 KB is used for storing the message. After usage exceeds 1,024 KB, messages cannot be written to memory. The number of 5 KB messages that can be stored (in the inbox and outbox combined) is 1024/8 = 128 messages.
Written data is committed when the CloseMessageBox or CommitMessageBox function is called after a write has been made.

If you set withWriteBoxInfo equal to false, updates to the internal message list are skipped. This enables you to shorten the amount of time to write multiple consecutive messages. Note that the GetMessageBoxXXX functions are unable to get accurate information if the list has not been updated.
The EULA version to which the user has agreed is checked when a message is written. If an icon file (.icn) is not set in the ROM, ResultNotAgreeEula is returned. You must initialize the FS library before calling this function because the check uses FS library features.

Error Handling

The following simplified C++ code provides guidelines for error handling. 
    nn::Result result = WriteMessage();
    if(result.IsFailure())
    {
        if(result == nn::cec::ResultNotAgreeEula())
        {
            // The user has not agreed to the EULA.
        }
        else if(result == nn::cec::ResultParentalControlCec())
        {
            // Not permitted by Parental Controls.
        }
        else if(result == nn::cec::ResultNotAuthorized())
        {
            // Box is not open
            //  --> OpenMessageBox
        }
        else if(result == nn::cec::ResultBoxSizeFull() || result == nn::cec::ResultBoxMessNumFull())
        {
            // Outbox capacity exceeded
            // You must delete some outbox messages → DeleteMessage/DeleteAllMessages
        }
        else if(result == nn::cec::ResultMessTooLarge() || result == nn::cec::ResultNoData() 
             || result == nn::cec::ResultInvalidCombination() )
        {
            // Invalid message
        }
        else if(result == nn::cec::ResultStateBusy() )
        {
            // Daemon is BUSY. This state never occurs normally. It might be possible to succeed by retrying.
        }
        else
        {
            // Error
        }
        return result;	// Failure
    }
    return result;  // Success

Revision History

2011/01/19
Added a description of error handling.
2010/08/16
Initial version.

CONFIDENTIAL