/*---------------------------------------------------------------------------*
  Project:  NitroSDK - wireless_shared - demos - wfs
  File:     wfs.h

  Copyright 2003-2006 Nintendo.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

  $Log: wfs.h,v $
  Revision 1.4  01/18/2006 02:12:39  kitase_hirotake
  do-indent

  Revision 1.3  05/09/2005 04:30:58  yosizaki
  add comment of WFS_End().

  Revision 1.2  02/28/2005 05:26:34  yosizaki
  do-indent.

  Revision 1.1  11/16/2004 01:13:04  yosizaki
  moved from /demos/wbt/wbt-fs.


 -[old log at /demos/wbt/wbt-fs/wfs]-

  Revision 1.9  10/25/2004 04:20:14  yosizaki
  add WFS_InitParent and WFS_InitChild.
  add some getter functions.

  Revision 1.8  09/29/2004 07:28:03  yosizaki
  change WFS_Init.

  Revision 1.7  09/29/2004 07:10:11  yosizaki
  merge from branch.

  Revision 1.6  09/15/2004 01:11:12  yosizaki
  add WFS_SetPacketSize().

  Revision 1.5  09/11/2004 04:13:35  yosizaki
  add comments.
  unify MP-size definition.

  Revision 1.4  09/04/2004 13:25:40  yosizaki
  add WFS_GetCurrentDownloadProgress.

  Revision 1.3  09/04/2004 01:45:14  yosizaki
  delete obsolete codes and waste parameters.

  Revision 1.2  09/03/2004 10:10:04  yosizaki
  enable WFS_OBSOLETE.

  Revision 1.1  09/03/2004 01:12:10  yosizaki
  (none)

  $NoKeywords: $
 *---------------------------------------------------------------------------*/

#ifndef	NITRO_BUILD_DEMOS_WIRELESSSHARED_WFS_INCLUDE_WFS_H_
#define	NITRO_BUILD_DEMOS_WIRELESSSHARED_WFS_INCLUDE_WFS_H_


#include <nitro/fs.h>
#include <nitro/wm.h>


#if	defined(__cplusplus)
extern  "C"
{
#endif


/*****************************************************************************/
/* constant*/


/*
 * Enumerator type showing internal state of WFS.
 */
    typedef enum
    {
        WFS_STATE_STOP,
        WFS_STATE_IDLE,
        WFS_STATE_READY,
        WFS_STATE_ERROR
    }
    WFSState;


/*****************************************************************************/
/* prototype*/

/*
 * The callback called every time the internal state of the WFS changes.
 * The FS automatically becomes available when WFS_STATE_READY is returned.
 */
    typedef void (*WFSStateCallback) (void *);


/*
 * The dynamic memory allocation callback internal to WFS.
 * arg is  user defined argument.
 * If ptr is NULL, return memory of size byte.
 * If ptr is not NULL, release ptr.
 */
    typedef void *(*WFSAllocator) (void *arg, u32 size, void *ptr);


/*****************************************************************************/
/* function*/

/*---------------------------------------------------------------------------*
  Name:         WFS_InitParent

  Description:  Initializes wireless file system (WFS) as parent.
                sets the port callback to the WM library and runs automatically, so    
                you must call it before READY state of WM.    

  Arguments:    port             Port number used for internal MP communication.
                callback         Callback that receives various state notifications.
                allocator        Callback used for internal memory allocation.
                                 The amount of memory the WFS uses is decided each time
                                 application runs.
                allocator_arg    User-defined argument given to allocator.
                parent_packet    Default parent send size.    
                                 his value must be greater than WBT_PACKET_SIZE_MIN    
                                 less than parent maximum send size.
                                 This is simply ignored for child.    
                p_rom            File program pointing to programs including    
                                 FAT/FNT/OVT provided form children.    
                                 This normally specifies the child program itself sent    
                                 with wireless download.    
                                 Seek position maintains position before the call.
                                 When this argument is NULL, provides parent's own
                                 file system.
                use_parent_fs    When TRUE, provides parent's own FAT/FNT, not
                                 program specified with p-rom.
                                 With this setting, it is possible to share simple file systems    
                                 with separate parent child programs.    
                                 If p_rom is NULL, this setting is ignored, and sharing always
                                 occurs.

  Returns:      None.
 *---------------------------------------------------------------------------*/
    void    WFS_InitParent(int port, WFSStateCallback callback,
                           WFSAllocator allocator, void *allocator_arg, int parent_packet,
                           FSFile *p_rom, BOOL use_parent_fs);

/*---------------------------------------------------------------------------*
  Name:         WFS_InitChild

  Description:  Initializes wireless file system (WFS) as child.
                sets the port callback to the WM library and runs automatically, so    
                you must call it before READY state of WM.    

  Arguments:    port             Port number used for internal MP communication.
                callback         Callback that receives various state notifications.
                allocator        Callback used for internal memory allocation.
                                 The amount of memory the WFS uses is decided each time
                                 application runs.
                allocator_arg    User-defined argument given to allocator.

  Returns:      None.
 *---------------------------------------------------------------------------*/
    void    WFS_InitChild(int port, WFSStateCallback callback,
                          WFSAllocator allocator, void *allocator_arg);

/*---------------------------------------------------------------------------*
  Name:         WFS_Init

  Description:  Initializes wireless file system (WFS).
                After initializing internal state as parent or child,    
                sets the port callback to the WM library and runs automatically, so    
                you must call it before READY state of WM.    

  Arguments:    is_parent        If wireless parent, TRUE. If child, FALSE.
                                 In actual multiboot, gives !MB_IsMultiBootChild()    
                                 for this argument.    
                port             Port number used for internal MP communication.
                parent_packet    Default parent send size.    
                                 his value must be greater than WBT_PACKET_SIZE_MIN    
                                 less than parent maximum send size.
                                 This is simply ignored for child.    
                callback         Callback that receives various state notifications.
                allocator        Callback used for internal memory allocation.
                                 The amount of memory the WFS uses is decided each time
                                 application runs.
                allocator_arg    User-defined argument given to allocator.

  Returns:      None.
 *---------------------------------------------------------------------------*/
    void    WFS_Init(BOOL is_parent, int port, int parent_packet,
                     WFSStateCallback callback, WFSAllocator allocator, void *allocator_arg);

/*---------------------------------------------------------------------------*
  Name:         WFS_Start

  Description:  For WFS, sends notification that wireless has entered MP state.
                After this notification, WFS uses WM_SetMPDataToPort() and runs
               automatically with "Priority: low (WM_PRIORITY_LOW)".
                For this reason, it must be called in MP_PARENT or MP_CHILD
                state.
                Normally called after WM_STATECODE_MP_START is passed    
                to state trigger type with WM_StartMP() callback.    

  Arguments:    None.

  Returns:      None.
 *---------------------------------------------------------------------------*/
    void    WFS_Start(void);

/*---------------------------------------------------------------------------*
  Name:         WFS_End

  Description:  Called when WFS is not needed.
                Releases all internally allocated memory and returns to state before initialization.
                Normally, this is called when all wireless communication has been disconnected.
                This function cannot be called from the interrupt handler.

  Arguments:    None.

  Returns:      None.
 *---------------------------------------------------------------------------*/
    void    WFS_End(void);

/*---------------------------------------------------------------------------*
  Name:         WFS_GetStatus

  Description:  Gets current internal state of WFS in WFSState type.

  Arguments:    None.

  Returns:      Some WFSState-type enumerator value.    
 *---------------------------------------------------------------------------*/
    WFSState WFS_GetStatus(void);

/*---------------------------------------------------------------------------*
  Name:         WFS_GetCurrentBitmap

  Description:  Acquire a bitmap of the current child group that WBT recognizes.    
                This function can only be called by parent.

  Arguments:    None.

  Returns:      Currently recognized child group.    
 *---------------------------------------------------------------------------*/
    int     WFS_GetCurrentBitmap(void);

/*---------------------------------------------------------------------------*
  Name:         WFS_GetSyncBitmap

  Description:  Gets bitmap of child group with accessed sync specified.
                This function can only be called by parent.

  Arguments:    None.

  Returns:      Child group designated for getting access sync.    
 *---------------------------------------------------------------------------*/
    int     WFS_GetSyncBitmap(void);

/*---------------------------------------------------------------------------*
  Name:         WFS_GetBusyBitmap

  Description:  Gets bitmap of children currently accessing parent.    
                This function can only be called by parent.

  Arguments:    None.

  Returns:      Children currently accessing parent.    
 *---------------------------------------------------------------------------*/
    int     WFS_GetBusyBitmap(void);

/*---------------------------------------------------------------------------*
  Name:         WFS_IsBusy

  Description:  Checks whether child of specified aid is currently being accessed.    
                This function can only be called by parent.

  Arguments:    aid              aid of child to check.

  Returns:      TRUE if specified child is being accessed. Otherwise FALSE.    
 *---------------------------------------------------------------------------*/
    BOOL    WFS_IsBusy(int aid);

/*---------------------------------------------------------------------------*
  Name:         WFS_GetCurrentDownloadProgress

  Description:  Gets progress of file that child is currently ReadFile-ing.    
                The unit will be the WBT internal sequence number.
                This function can only be called by children.

  Arguments:    current_count    Variable address storing currently received    
                                 to receive.    
                total_count      Variable address storing sequence total    
                                 to receive.    

  Returns:      Returns TRUE when currently in ReadFile state and progress can be gotten correctly.    
                Otherwise, returns FALSE.
 *---------------------------------------------------------------------------*/
    BOOL    WFS_GetCurrentDownloadProgress(int *current_count, int *total_count);

/*---------------------------------------------------------------------------*
  Name:         WFS_GetPacketSize

  Description:  Gets MP communication packet size of parent set by WFS.

  Arguments:    None.

  Returns:      MP communication packet size of parent set by WFS.
 *---------------------------------------------------------------------------*/
    int     WFS_GetPacketSize(void);

/*---------------------------------------------------------------------------*
  Name:         WFS_SetPacketSize

  Description:  Sets parent MP communication packet size.
                Making this value large improves transfer efficiency. When you make it small,    
                you can avoid one way congestion from port priority packaged with separate port    
                communication such as data sharing with one-time MP communication.    
                This function can only be called by parent.

  Arguments:    size             Parent send size to set.
                                 his value must be greater than WBT_PACKET_SIZE_MIN    
                                 less than parent maximum send size.

  Returns:      None.
 *---------------------------------------------------------------------------*/
    void    WFS_SetPacketSize(int size);

/*---------------------------------------------------------------------------*
  Name:         WFS_EnableSync

  Description:  Sets the set of children that that obtains access synchronicity for parent.    
                This function accesses the same file group in the same order.    
                But, by synchronizing responses for children clearly guaranteed children, realizes efficient transfer taking    
                advantage of the special characteristics of the WBT library.    
                However, note that when the timing of the sync start is logically insecure,    
                the response to the children slips and deadlocks.    
                This function can only be called by parent.

  Arguments:    sync_bitmap      aid bitmap of children that get access synchronicity.    
                                 The lowest bit 1 indicating parent is ignored.    
                                 By assigning 0 for this value, synchronicity does not occur.
                                 This state by default.

  Returns:      None.
 *---------------------------------------------------------------------------*/
    void    WFS_EnableSync(int sync_bitmap);

/*---------------------------------------------------------------------------*
  Name:         WFS_DisableSync

  Description:  Cancels children access synchronicity by parent.   
                This function is equivalent to specifying WFS_EnableSync() 0.

  Arguments:    None.

  Returns:      None.
 *---------------------------------------------------------------------------*/
    static inline void WFS_DisableSync(void)
    {
        WFS_EnableSync(0);
    }

/*---------------------------------------------------------------------------*
  Name:         WFS_SetDebugMode

  Description:  Enables/Disables WFS internal debug output.
                The default setting is FALSE.

  Arguments:    enable_debug     TRUE if debug output is enabled. FALSE if disabled.

  Returns:      None.
 *---------------------------------------------------------------------------*/
    void    WFS_SetDebugMode(BOOL enable_debug);


/*****************************************************************************/


#if	defined(__cplusplus)
}                                      /* extern "C"*/
#endif


#endif /* NITRO_BUILD_DEMOS_WIRELESSSHARED_WFS_INCLUDE_WFS_H_ */
