# Nintendo DSi Photo Database Library (TCL)

## Introduction

The TCL library performs tasks such as loading JPEG images saved on NAND by the Nintendo DSi cameras and writing JPEG images to paths that can be loaded by Nintendo DSi Camera.

Loading and writing JPEG images is based on information in management files, which are saved in memory separately from the image files.

TCL manipulates files on NAND, so it can be used only with NAND applications.

## Errors Corresponding to FS Function Processes

With TCL, no special processes are performed for internally generated FS function errors. All error processes are left to the application. For any functions that use FS internally, error codes are returned by an argument, so use them to perform the necessary processes.

## Loading Management Files and Errors

You must load a management file to use TCL functions.

The following processes demonstrate error handling when a management file fails to be loaded.

- Show a message prompting the user to start the Nintendo DSi Camera and use it to reference system memory and then stop further processing.
- Recreate the management file.

There is little possibility that loading the management file in system memory will fail and recovery can be performed with the Nintendo DSi Camera, so there is basically no problem with the former error process. In such cases, when application specifications are limited to loading (not writing) photos, it is possible to ignore several errors. For more information, see the `TCL_LoadTable` function.

The following are the sequences for attempting to recover a management file for reasons associated with the game's characteristics. However, even if the following processes are performed, management files might not be recovered.

## Sequences to Attempt Recovering Management Files That Failed to Load

If a management file fails to load and you are recovering it, two error-handling sequences are available, depending on your application specifications. The first sequence is based on next save locations defined for images in the management file. If the save location is invalid, images are loaded but will not be written. If the management file fails to load for a different reason, both the loading and writing of images fails.

The error-handling sequences are explained in the following sections.

### When Images Can Only Be Loaded

This sequence loads a management file that includes an error process when only loading images for application specifications. (See the manual for more information on the content of each function.)

    // Load the management file
    TCLResult result = TCL_LoadTable( &accessor ,
                                      tableBuffer ,
                                      tableBufferSize ,
                                      workBuffer ,
                                      workBufferSize ,
                                      &fsResult );

    // The result of the load process
    switch ( result )
    {
        case TCL_RESULT_SUCCESS: // Loading succeeded
        case TCL_RESULT_ERROR_EXIST_OTHER_FILE: // A file already exists in the next save location
        case TCL_RESULT_ERROR_ALREADY_MANAGED: // The  next save location is already being managed
            // The image loading process is performed, so nothing needs to be done
                         :
            break;
        default:
            // The image loading process is not being performed, so recreate the management file
            result = TCL_CreateTable( &accessor ,
                                      tableBuffer ,
                                      tableBufferSize ,
                                      workBuffer ,
                                      workBufferSize ,
                                      &fsResult );

            if ( result == TCL_RESULT_SUCCESS )
            {
                // Images can be both loaded and written out
                             :
            }
            else
            {
                // Images can neither be loaded nor written out
                             :
            }
        }
    }

### When Images Can Be Loaded and Written

When images can be loaded and written as per application specifications, this management file loading sequence includes an error-handling process.

    // Load the management file
    TCLResult result = TCL_LoadTable( &accessor ,
                                      tableBuffer ,
                                      tableBufferSize ,
                                      workBuffer ,
                                      workBufferSize ,
                                      &fsResult );

    // The result of the load process
    switch ( result )
    {
        case TCL_RESULT_SUCCESS: // Loading succeeded
            // The image loading and writing processes are both performed, so nothing needs to be done
                          :
            break;

        case TCL_RESULT_ERROR_EXIST_OTHER_FILE: // A file already exists in the next save location
        case TCL_RESULT_ERROR_ALREADY_MANAGED: // The  next save location is already being managed
            // The writing process is not performed, so recalculate the next save location
            result = TCL_RepairTable( &accessor , &fsResult );

            if ( result == TCL_RESULT_SUCCESS )
            {
                // Images can be both loaded and written
                              :
            }
            else
            {
                // The image-writing process cannot be performed, so recreate the management file
                result = TCL_CreateTable( &accessor ,
                                          tableBuffer ,
                                          tableBufferSize ,
                                          workBuffer ,
                                          workBufferSize ,
                                          &fsResult );

                if ( result == TCL_RESULT_SUCCESS )
                {
                    // Images can be both loaded and written out
                                  :
                }
                else
                {
                    // Images can neither be loaded nor written out
                                  :
                }
            }
            break;
        default:
            // The image loading process is not being performed, so recreate the management file
            result = TCL_CreateTable( &accessor ,
                                      tableBuffer ,
                                      tableBufferSize ,
                                      workBuffer ,
                                      workBufferSize ,
                                      &fsResult );

            if ( result == TCL_RESULT_SUCCESS )
            {
                // Images can be both loaded and written out
                             :
            }
            else
            {
                // Images can neither be loaded nor written out
                             :
            }
        }
    }

## Example Message for Failure to Load a Management File

When the loading of a management file has failed, it might be necessary to display some form of message to indicate that photos cannot be worked with and that the management file should be recreated. Such cases are shown as an example based on Nintendo DSi Camera messages.

However, these are only for your reference. Perform processes appropriate for the application.

### When Loading a Management File Failed and Photos Cannot Be Worked With

No special message has been prepared for such cases with the Nintendo DSi Camera. (Handled as a fatal error.) For that reason, an example cannot be provided. It might be effective to provide a message that prompts the user to start the Nintendo DSi Camera and recover the file.

### When Creating a Management File That Does Not Exist

When `TCL_RESULT_ERROR_NO_TABLE_FILE` is returned from the `TCL_LoadTable` function, it indicates that the management file does not exist. The following message is displayed when a management file is created in this state.

    Creating a photo management file...

### When Recreating Because the Management File Could Not Be Loaded

The following message is displayed when the management file is recreated for some other reason.

    The photo management file is corrupted.

    Recreating the photo management file.

## Writing Image Files

Image files cannot be written in the following situations.

  There is insufficient NAND
  The maximum manageable number of photos is already being managed
  An addressable path does not exist for the save location

The `TCL_CalcNumEnableToTakePictures` function calculates how many photos can be taken, based on the NAND capacity and the number of photos currently being managed. However, it does not determine whether it is possible to write to the specified path. Include logic similar to that shown in the following example when an image file is written.

    // Flags that maintain whether addressable path exists.
    // If TCL_RESULT_ERROR_NO_NEXT_INDEX is returned from TCL_RepairTable or TCL_CreateTable, no path can be specified so the default value is set to FALSE.
    //
    BOOL isEnableValidPath;

    // Where image is actually stored
    // Only take photo if 1 or more photos can be taken and there is a valid path
    if ( TCL_CalcNumEnableToTakePictures(,,) > 0 && isEnableValidPath != FALSE )
    {
        result = TCL_EncodeAndWritePicture(,,);

        // If, as a result of this save, there is no longer a valid path, hold this
        if ( result == TCL_RESULT_ERROR_NO_NEXT_INDEX )
        {
            isEnableValidPath = FALSE;
        }
    }

For more information, see the `tcl-2` demo.

## JPEG Decoding

The `TCL_DecodePicture` function to decode JPEG files is provided. This is a wrapper function for the `SSP_StartJpegDecoder` function, but because it performs the necessary internal error checks, decode using this function without calling the `SSP_StartJpegDecoder` function directly.

## Differentiating Image Types

There are two types of images used with the Nintendo DSi cameras: photos and frames. Frames are used by the frame camera. Metadata information stored in the JPEG image defines its image type. TCL write operations must adhere to the specified image type.

The management file stores image information independent of the metadata. Overwriting the management file, therefore, can lead to a mismatch between TCL data and image data.

If this happens, unexpected results may occur. For example, a search based only on data in the management file may return frames instead of photos.

Compare the image type in the management file with the image type retrieved from the JPEG metadata before operating on files. The following sample compares the two sources of information.

    // Get image type from the management file
    TCLPictureInfo* pPicInfo = NULL;
    TCL_SearchNextPictureInfo( ,, &pPicInfo ,, );

    // The manufacturer's note structure gotten from the manufacturer's note after decoding
    // See the JPEG library to learn how to get this
    // Cast the Nintendo DSi camera manufacturer note to the following structure.
    TCLMakerNote* pMakerNote = ...;

    // Perform this process only if the image types match
    if ( TCL_IsSameImageType( pPicInfo , pMakerNote ) != FALSE )
    {
        :
    }

That this evaluation procedure is not necessary if you want to handle photos and frames together without differentiating between the two.

## Revision History

2009/04/13 Initial version.

CONFIDENTIAL