#ifndef IFELICADEV_H
#define IFELICADEV_H
/*=============================================================================================

FILE            : IFeliCaDev.h

SERVICES        : BREW FeliCa 拡張API

DESCRIPTION     : FeliCa Dev API

PUBLIC CLASSES  : なし

INITIALIZATION AND SEQUENCING REQUIREMENTS : なし

     Copyright 2004-2005 Felica Networks, Inc.
              All Rights Reserved.
        Felica Networks, Inc. Proprietary

=============================================================================================*/

/*=============================================================================================
 INCLUDES AND VARIABLE DEFINITIONS
=============================================================================================*/

/*=====================================================================
 Include Files
=====================================================================*/
#include "AEE.h"
#include "AEEError.h"
#include "IFeliCaDev.bid"

/*=====================================================================
 Macros
=====================================================================*/

//---------------------------------------------------------------------
// IFeliCaDev_IOCtl() Paramater
//---------------------------------------------------------------------
#define IFELICADEV_IOCTL_SETPOWERON  (1)  // Set PowerOn Status


//---------------------------------------------------------------------
// FeliCa Dev 復帰値/処理結果
//---------------------------------------------------------------------
//#define SUCCESS             (0)         // AEEError.hにて定義されている
#define EFELICADEV_FAILED     (-1)        // 失敗
#define EFELICADEV_ALREADY    (-2)        // ポートが他オブジェクトによりオープン済み
#define EFELICADEV_WOULDBLOCK (-3)        // 処理中
#define EFELICADEV_NOTOPENED  (-4)        // 自オブジェクトがポートをオープンしていない場合
#define EFELICADEV_BADPARAM   (-5)        // パラメータ異常
#define EFELICADEV_BADSTATE   (-6)        // 既にコールバック登録済み


/*=====================================================================
 Type Declarations
=====================================================================*/

/*=====================================================================
 Interface Definitions
=====================================================================*/
typedef struct IFeliCaDev IFeliCaDev;

/*=====================================================================
 IFELICA Interface
=====================================================================*/
AEEINTERFACE(IFeliCaDev)
{
   INHERIT_IQueryInterface(IFeliCaDev);
   int          (* Open)               (IFeliCaDev * po);
   int          (* Close)              (IFeliCaDev * po);
   int          (* Write)              (IFeliCaDev * po, const byte * pbyData, uint16 nSize);
   int          (* Writable)           (IFeliCaDev * po, AEECallback * pcb);
   int          (* Read)               (IFeliCaDev * po, byte * pbyData, uint16 nSize);
   int          (* Readable)           (IFeliCaDev * po, AEECallback * pcb);
   int          (* IOCtl)              (IFeliCaDev * po, int nOption, uint32 dwVal);
   int          (* GetLockStatus)      (IFeliCaDev * po, boolean * pbStatus);
};

/*=====================================================================
 Function Declarations
=====================================================================*/
#define IFELICADEV_AddRef(p)                       AEEGETPVTBL((p),IFeliCaDev)->AddRef((p))
#define IFELICADEV_Release(p)                      AEEGETPVTBL((p),IFeliCaDev)->Release((p))
#define IFELICADEV_QueryInterface(p, id, ppo)      AEEGETPVTBL((p),IFeliCaDev)->QueryInterface((p),(id),(ppo))
#define IFELICADEV_Open(p)                         AEEGETPVTBL((p),IFeliCaDev)->Open((p))
#define IFELICADEV_Close(p)                        AEEGETPVTBL((p),IFeliCaDev)->Close((p))
#define IFELICADEV_Write(p,pbyData,nSize)          AEEGETPVTBL((p),IFeliCaDev)->Write((p),(pbyData),(nSize))
#define IFELICADEV_Writable(p,pcb)                 AEEGETPVTBL((p),IFeliCaDev)->Writable((p),(pcb))
#define IFELICADEV_Read(p,pbyData,nSize)           AEEGETPVTBL((p),IFeliCaDev)->Read((p),(pbyData),(nSize))
#define IFELICADEV_Readable(p,pcb)                 AEEGETPVTBL((p),IFeliCaDev)->Readable((p),(pcb))
#define IFELICADEV_IOCtl(p,nOption,dwVal)          AEEGETPVTBL((p),IFeliCaDev)->IOCtl((p),(nOption),(dwVal))
#define IFELICADEV_GetLockStatus(p,pbStatus)       AEEGETPVTBL((p),IFeliCaDev)->GetLockStatus((p),(pbStatus))

/*=============================================================================================
    インタフェース説明
===============================================================================================

IFELICADEV_AddRef()

Description     :
  IFeliCaオブジェクトの参照カウンタをインクリメントする。

Prototype       :
  uint32    IFELICADEV_AddRef(IFeliCaDev * po);

Parameters      :
  po            : IFeliCaDevオブジェクトへのポインタ

Return Value    :
  0以上         : 正常終了
                  インクリメント後の参照カウンタの値

Comment         :
  なし

See Also        :
  IFELICADEV_Release()

===============================================================================================

IFELICADEV_Release()

Description     :
  IFeliCaオブジェクトの参照カウンタをデクリメントする。

Prototype       :
  uint32    IFELICADEV_Release(IFeliCaDev  * po) ;

Parameters      :
  po            : IFeliCaDevオブジェクトへのポインタ

Return Value    :
  0以上         : 正常終了
                  デクリメントした後の参照カウンタの値

Comment         :
  ・参照カウンタが0になった場合、PortExclusion オブジェクトの解放処理を行う。
    -IFELICADEV_Writable()及びIFELICADEV_Readable()によって登録されているコールバック関数を破棄する。
    -自オブジェクトが、ポートをオープンしている場合、ポートのクローズ処理を行う。

See Also        :
  IFELICADEV_AddRef()

===============================================================================================

IFELICADEV_QueryInterface()

Description     :
  このメソッドは、そのオブジェクトからの別のオブジェクトを問い合わせる。
  IFeliCaDevでは、問い合わせに対して公開できるオブジェクトをもたないため、
  FeliCaDevクラスの要求のみ受け付けることとする。

Prototype       :
  int    IFELICADEV_QueryInterface(IFeliCaDev  * po,
                                   AEECLSID      idReq,
                                   void       ** ppo    );

Parameters      :
  po            : IFeliCaDevオブジェクトへのポインタ
  idReq         : 要求するClassID。オブジェクトによって公開される
  ppo           : 要求されたオブジェクトへのポインタを格納するポインタ

Return Value    :
  SUCCESS          : 正常終了
  ENOMEMORY        : メモリ獲得に失敗した場合
  ECLASSNOTSUPPORT : 要求したインタフェースをサポートしていない場合

Comment         :
  ・要求されたクラスがIFeliCaDevのクラスであった場合、*ppoに格納するポインタには、
    自オブジェクトインタフェースを指すように設定し、参照カウントを１つインクリメントする。
    FeliCaDev以外のクラスであった場合、NULLを設定する。

  ・本メソッドは、IQIの派生でインスタンスを１つだけ実装するQueryInterface()メソッドとなり、
    マクロIQI_SELF()をその実体として使用することができる。

See Also        :
  IFELICADEV_AddRef()

===============================================================================================

IFELICADEV_Open()

Description     :
  モバイルFeliCaチップと接続されているUARTのポートをオープンする。

Prototype       :
  int       IFELICADEV_Open(IFeliCaDev * po);

Parameters      :
  po            : IFeliCaDevオブジェクトへのポインタ

Return Value    :
  SUCCESS               : オープン成功、または既に自オブジェクトでオープンしている場合。
  EFELICADEV_FAILED     : オープン失敗
  EFELICADEV_ALREADY    : 他オブジェクトがオープンしている場合
  EFELICADEV_WOULDBLOCK : オープン処理中

Comment         :
  ・デバイスの制約により、すぐにオープンを完了できない場合は復帰値として
    EFELICADEV_WOULDBLOCKを返却する。

  ・オープン完了時に、IFELICADEV_Writable()にてコールバック関数が登録されている場合、
    登録されているコールバックを実行する。

  ・本関数の復帰値がSUCCESSまたはEFELICADEV_WOULDBLOCKであった場合をオープン中状態であるとし、
    以降、ポートクローズが正常終了するまでの間に、他のオブジェクトから本関数が実行された場合は
    EFELICADEV_ALREADYを返却する。

See Also        :
  IFELICADEV_Close()
  IFELICADEV_Writable()

===============================================================================================

IFELICADEV_Close()

Description     :
  モバイルFeliCaチップと接続されているUARTのポートをクローズする。

Prototype       :
  int       IFELICADEV_Close(IFeliCaDev * po);

Parameters      :
  po            : IFeliCaDevオブジェクトへのポインタ

Return Value    :
  SUCCESS              : クローズ成功
  EFELICADEV_NOTOPENED : 自オブジェクトがポートをオープンしていない場合(他オブジェクトがポートを
                         オープンしている、またはポートがクローズ状態)
  EFELICADEV_FAILED    : その他エラーが発生した場合

Comment         :
  ・本関数が実行された時点で、自オブジェクトがポートをオープンしている場合は、
    クローズ処理の結果に関係なくIFELICADEV_Writable()およびIFELICADEV_Readable()によって登録され
    ているコールバック関数を破棄する。

  ・自オブジェクトがポートをオープンしていない場合(他オブジェクトがポートをオープンしている、
    またはポートがクローズ状態)は、復帰値としてEFELICADEV_NOTOPENEDを返却する。

See Also        :
  IFELICADEV_Open
  IFELICADEV_Writable
  IFELICADEV_Readable

===============================================================================================

IFELICADEV_Write()

Description     :
  モバイルFeliCaチップにデータを送信する。

Prototype       :
  int       IFELICADEV_Write(IFeliCaDev  * po,
                            const byte  * pbyData,
                            uint16        nSize);

Parameters      :
  po            : IFeliCaDevオブジェクトへのポインタ
  pbyData       : 送信データが格納されている領域へのポインタ
  nSize         : 送信データのサイズ(pbyDataのサイズ)

Return Value    :
  1以上                 : 正常終了送信データのバイト数を返却する
  EFELICADEV_BADPARAM   : パラメータ異常
  EFELICADEV_NOTOPENED  : 自オブジェクトがポートをオープンしていない場合
                          (他オブジェクトがポートをオープンしている、またはポートがクローズ状態)
  EFELICADEV_WOULDBLOCK : UARTポートへデータを送信できない場合(送信待ち状態)
  EFELICADEV_FAILED     : その他エラーが発生した場合

Comment         :
  ・正常終了した場合は送信バイト数を返却する。返却されたバイト数が要求したバイト数よりも少ない場合は
    再度、本関数を実行する必要がある。

  ・UARTポートへデータを1バイトも送信できなかった場合は、復帰値としてEFELICADEV_WOULDBLOCKを返却する。
    IFELICADEV_Writable()にてコールバック関数が登録されている場合、送信可能状態となった時点で登録されて
    いるコールバックを実行する。

  ・以下の場合、EFELICADEV_BADPARAMが返却される。
    -pbyDataがNULLの場合
    -nSizeが0の場合

See Also        :
  IFELICADEV_Writable

===============================================================================================

IFELICADEV_Writable()

Description     :
  IFELICADEV_Open または IFELICADEV_Writeの復帰値がEFELICADEV_WOULDBLOCKだった場合、
  送信可能となった時点で、その旨を通知するコールバック関数を登録する関数。
  コールバック関数を実行するタイミングは以下の通り。
   -IFELICADEV_Openで、EFELICADEV_WOULDBLOCKを返却した場合・・・ポートオープンが完了した時点
   -IFELICADEV_Writeで、EFELICADEV_WOULDBLOCKを返却した場合・・・送信可能となった時点

Prototype       :
  int       IFELICADEV_Writable(IFeliCaDev  * po,
                                AEECallback * pcb);

Parameters      :
  po            : IFeliCaDevオブジェクトへのポインタ
  pcb           : 送信可能になった時点で実行するコールバック関数を含むAEECallback領域へのポインタ

Return Value    :
  SUCCESS              : 正常終了
  EFELICADEV_BADPARAM  : パラメータ異常
  EFELICADEV_NOTOPENED : 自オブジェクトがポートをオープンしていない場合(他オブジェクトがポートをオープンしている、
                         またはポートがクローズ状態)
  EFELICADEV_BADSTATE  : 既にコールバックが登録済みである場合
  EFELICADEV_FAILED    : その他エラーが発生した場合

Comment         :
  ・既にコールバックを登録済みである場合に本関数が実行された場合、EFELICADEV_BADSTATEを返却する。
    この場合、コールバックの登録は行わず、オープン完了後または、送信可能となった時点で、
    登録されているコールバック関数が実行される。

  ・本関数がコールされた時点で、pcbのpfnCancel(※1)にコールバックの実行をキャンセルするための関数が登録される。
    コールバックの実行をキャンセルするための関数とは、コールバックの情報を破棄する関数のことである。
    このpfnCancelを使用し、コールバックを破棄することができる。
    (※1) AEECallbackのメンバ。【AEECallbackについてはBREWAPIReference】を参照)

  ・以下の場合、EFELICADEV_BADPARAMが返却される。
     -pcbがNULLの場合

See Also        :
  IFELICADEV_Open
  IFELICADEV_Write

===============================================================================================

IFELICADEV_Read()

Description     :
  モバイルFeliCaチップからのデータを受信する。
Prototype       :
  int       IFELICADEV_Read(IFeliCaDev  * po,
                               byte        * pbyData,
                               uint16        nSize);

Parameters      :
  po            : IFeliCaDevオブジェクトへのポインタ
  pbyData       : 受信データを格納する領域へのポインタ
  nSize         : 受信データのサイズ(pbyDataのサイズ)

Return Value    :
  1以上                 : 正常終了受信データのバイト数を返却する
  EFELICADEV_BADPARAM   : パラメータ異常
  EFELICADEV_NOTOPENED  : 自オブジェクトがポートをオープンしていない場合
                          (他オブジェクトがポートをオープンしている。または、ポートがクローズ状態。)
  EFELICADEV_WOULDBLOCK : UARTポートに受信可能なデータがない場合(受信待ち状態)
  EFELICADEV_FAILED     : その他エラーが発生した場合

Comment         :
  ・正常終了した場合、受信バイト数が返却される。データをすべて受信しても、nSizeにて指定されたサイズに
    満たない場合は、受信できたサイズが返却される。

  ・UARTポートからデータを1バイトも受信できなかった場合、EFELICADEV_WOULDBLOCKが返却される。

  ・IFELICADEV_Readable()にてコールバック関数が登録されている場合、受信可能状態となった時点で
    登録されているコールバックが実行される。

See Also        :
  IFELICADEV_Readable

===============================================================================================

IFELICADEV_Readable()

Description     :
  IFELICADEV_Readの復帰値がEFELICADEV_WOULDBLOCKだった場合、受信可能となった時点で、
  その旨を通知するコールバック関数を登録する関数。
  受信可能になった時点で保持したコールバック関数を実行する。
  IFELICADEV_Readを実行されずに本関数が実行された場合も、
  受信可能になった時点で保持したコールバック関数を実行する。

Prototype       :
  int       IFELICADEV_Readable(IFeliCaDev  * po,
                                  AEECallback * pcb);

Parameters      :
  po            : IFeliCaDevオブジェクトへのポインタ
  pcb           : 受信可能になった時点で実行するコールバック関数を含むAEECallback領域へのポインタ

Return Value    :
  SUCCESS              : 正常終了
  EFELICADEV_BADPARAM  : パラメータ異常
  EFELICADEV_NOTOPENED : 自オブジェクトがポートをオープンしていない場合
                         (他オブジェクトがポートをオープンしている。または、ポートがクローズ状態。)
  EFELICADEV_BADSTATE  : 既にコールバックが登録済みである場合
  EFELICADEV_FAILED    : その他エラーが発生した場合

Comment         :
  ・既にコールバックを登録済みである場合に本関数が実行された場合、EFELICADEV_BADSTATEを返却する。
    この場合、コールバックの登録は行わず、受信可能になった時点で、登録されているコールバックを実行する。

  ・本関数がコールされた時点で、pcbのpfnCancel(※1)にコールバックの実行をキャンセルするための関数が登録される。
    コールバックの実行をキャンセルするための関数とは、コールバックの情報を破棄する関数のことである。
    このpfnCancelを使用し、コールバックを破棄することができる。
    (※1) AEECallbackのメンバ。【AEECallbackについてはBREWAPIReference】を参照)

  ・EFELICADEV_BADPARAMは以下の条件を満たした場合に返却する。
     -pcbがNULLの場合

See Also        :
  IFELICADEV_Read

===============================================================================================

IFELICADEV_IOCtl()

Description     :
  POWER ON端子の状態を設定する。

Prototype       :
  int       IFELICADEV_IOCtl(IFeliCaDev * po,
                             int          nOption,
                             uint32       dwVal   );

Parameters      :
  po            : IFeliCaDevオブジェクトへのポインタ
  nOption       : オプションID   IFELICADEV_IOCTL_SETPOWERON - POWER ON端子の状態設定
  dwVal         : POWER ON端子の状態設定時
                     High   :  != 0
                     Low    :  =  0

Return Value    :
  SUCCESS              : 正常終了
  EUNSUPPORTED         : オプションIDが認識されなかった場合
  EFELICADEV_NOTOPENED : 自オブジェクトがポートをオープンしていない場合
                         (他オブジェクトがポートをオープンしている、またはポートがクローズ状態)
  EFELICADEV_FAILED    : その他エラーが発生した場合

Comment         :
  特になし。

See Also        :
  特になし。

===============================================================================================

IFELICADEV_GetLockStatus()

Description     :
  移動機の不揮発性メモリに格納されているFeliCa Lock On/Off の状態を取得する。

Prototype       :
  int       IFELICADEV_GetLockStatus(IFeliCaDev * po,
                                     boolean    * pbStatus);

Parameters      :
  po            : IFeliCaDevオブジェクトへのポインタ
  pbStatus      : 取得した状態を格納する領域へのポインタ
                     On  : TRUE
                     Off : FALSE

Return Value    :
  SUCCESS              : 正常終了
  EFELICADEV_BADPARAM  : パラメータ異常
  EFELICADEV_FAILED    : その他エラーが発生した場合

Comment         :
  EFELICADEV_BADPARAM は、pbStatus がNULL の場合に返却します。
  本関数は、ポートのオープン・クローズに関わらず、呼び出すことが可能です。

See Also        :
  特になし。

===============================================================================================
*/

#endif // __IFELICADEV_H__

