Windows版 iTRONサービスコールの作成 (メールボックス)
（その５）

メールボックスからメッセージを受信する

メールボックスからメッセージを受信するサービスコールは以下のとおりです。


サービスコール名説明
rcv_msg

タイムアウトなしでメールボックスからメッセージを受信します。

prcv_msg

ポーリング方式でメールボックスからメッセージを受信します。

trcv_msg

タイムアウト付きでメールボックスからメッセージを受信します。

※ Ver3.0と4.0では関数名は同じですが、引数の順番が逆になりますので注意してください。

メールボックスからメッセージを受信する (タイムアウトなし)

タイムアウトなしでメールボックスからメッセージを受信するには以下のサービスコールを使用します。


・Ver3.0の場合 


    ER rcv_msg( T_MSG **ppk_msg, ID mbxid )

・Ver4.0の場合 


    ER rcv_msg( ID mbxid, T_MSG **ppk_msg )

引数説明
ppk_msg

受信したメッセージ･パケットのポインタを格納する領域のポインタ。

mbxid

メールボックスID番号。

戻り値説明
E_OK

正常終了。

E_ID

範囲外のメールボックスID番号。

E_NOEXS

指定したメールボックスID番号は登録されていない。

E_PAR

パラメータエラー。

E_CTX

非コンテキスト･タスクからの呼び出し。


・Ver3.0のサービスコールのソースコードは以下のようになります。


/****************************************************************************/
/*!
 *  @brief  メールボックスからの受信 (タイムアウトなし).
 *
 *  @param  [out]   ppk_msg メッセージ･パケットのアドレスを格納する領域のポインタ.
 *  @param  [in]    mbxid   メールボックスID番号.
 *
 *  @retval エラーコード.
 */
ER      rcv_msg( T_MSG **ppk_msg, ID mbxid )
{
    //! タイムアウトなしでメールボックスからメッセージを受信する.
    return trcv_msg( ppk_msg, mbxid, TMO_FEVR );
}

・Ver4.0のサービスコールのソースコードは以下のようになります。


/****************************************************************************/
/*!
 *  @brief  メールボックスからの受信 (タイムアウトなし).
 *
 *  @param  [in]    mbxid   メールボックスID番号.
 *  @param  [out]   ppk_msg メッセージ･パケットのアドレスを格納する領域のポインタ.
 *
 *  @retval エラーコード.
 */
ER      rcv_msg( ID mbxid, T_MSG **ppk_msg )
{
    //! タイムアウトなしでメールボックスからメッセージを受信する.
    return trcv_msg( mbxid, ppk_msg, TMO_FEVR );
}

trcv_msg()のタイムアウト設定に TMO_FEVR を指定して呼び出します。

メールボックスにメッセージが無い場合は、メールボックスにメッセージが格納されるまでタスクをスリープさせます。

メールボックスからメッセージを受信する (ポーリング)

ポーリングでメールボックスからメッセージを受信するには以下のサービスコールを使用します。


・Ver3.0の場合 


    ER prcv_msg( T_MSG **ppk_msg, ID mbxid )

・Ver4.0の場合 


    ER prcv_msg( ID mbxid, T_MSG **ppk_msg )

引数説明
ppk_msg

受信したメッセージ･パケットのポインタを格納する領域のポインタ。

mbxid

メールボックスID番号。

戻り値説明
E_OK

正常終了。

E_ID

範囲外のメールボックスID番号。

E_NOEXS

指定したメールボックスID番号は登録されていない。

E_PAR

パラメータエラー。

E_TMOUT

メールボックスにメッセージがない。


・Ver3.0のサービスコールのソースコードは以下のようになります。


/****************************************************************************/
/*!
 *  @brief  メールボックスからの受信 (ポーリング).
 *
 *  @param  [out]   ppk_msg メッセージ･パケットのアドレスを格納する領域のポインタ.
 *  @param  [in]    mbxid   メールボックスID番号.
 *
 *  @retval エラーコード.
 */
ER      prcv_msg( T_MSG **ppk_msg, ID mbxid )
{
    //! 受信待ちなしでメールボックスからメッセージを受信する.
    return trcv_msg( ppk_msg, mbxid, TMO_POL );
}

・Ver4.0のサービスコールのソースコードは以下のようになります。


/****************************************************************************/
/*!
 *  @brief  メールボックスからの受信 (ポーリング).
 *
 *  @param  [in]    mbxid   メールボックスID番号.
 *  @param  [out]   ppk_msg メッセージ･パケットのアドレスを格納する領域のポインタ.
 *
 *  @retval エラーコード.
 */
ER      prcv_msg( ID mbxid, T_MSG **ppk_msg )
{
    //! 受信待ちなしでメールボックスからメッセージを受信する.
    return trcv_msg( mbxid, ppk_msg, TMO_POL );
}

trcv_msg()のタイムアウト設定に TMO_POL を指定して呼び出します。

メールボックスにメッセージが無い場合は、タスクをスリープさせずに戻り値をE_TMOUTとしてすぐにサービスコールから戻ります。

メールボックスからメッセージを受信する (タイムアウト付き)

タイムアウト付きでメールボックスからメッセージを受信するには以下のサービスコールを使用します。


・Ver3.0の場合 


    ER trcv_msg( T_MSG **ppk_msg, ID mbxid, TMO tmout )

・Ver4.0の場合 


    ER trcv_msg( ID mbxid, T_MSG **ppk_msg, TMO tmout )

引数説明
ppk_msg

受信したメッセージ･パケットのポインタを格納する領域のポインタ。

mbxid

メールボックスID番号。

tmout

タイムアウトの設定値。

  • TMO_FEVRの場合、永久にメッセージが受信できるのを待ちます。
  • TMO_POLの場合、メッセージが受信できなくてもタスクをスリープしません。
  • その他の正数はタイムアウト値となります。

戻り値説明
E_OK

正常終了。

E_ID

範囲外のメールボックスID番号。

E_NOEXS

指定したメールボックスID番号は登録されていない。

E_TMOUT

メッセージを受信できずにタイムアウト。

E_PAR

パラメータエラー。

E_CTX

非コンテキスト･タスクからの呼び出し。


・Ver3.0のサービスコールのソースコードは以下のようになります。


/****************************************************************************/
/*!
 *  @brief  メールボックスからの受信 (タイムアウトあり).
 *
 *  @param  [out]   ppk_msg メッセージ･パケットのアドレスを格納する領域のポインタ.
 *  @param  [in]    mbxid   メールボックスID番号.
 *  @param  [in]    tmout   タイムアウト設定.
 *
 *  @retval エラーコード.
 */
ER      trcv_msg( T_MSG **ppk_msg, ID mbxid, TMO tmout )
{
    ER ercd;

    wi_CommonLock();

    //! メールボックスからメッセージを受信する.
    ercd = wi_ReceiveMailBox( mbxid, ppk_msg, tmout );

    wi_CommonUnlock();
    return ercd;
}

・Ver4.0のサービスコールのソースコードは以下のようになります。


/****************************************************************************/
/*!
 *  @brief  メールボックスからの受信 (タイムアウトあり).
 *
 *  @param  [in]    mbxid   メールボックスID番号.
 *  @param  [out]   ppk_msg メッセージ･パケットのアドレスを格納する領域のポインタ.
 *  @param  [in]    tmout   タイムアウト設定.
 *
 *  @retval エラーコード.
 */
ER      trcv_msg( ID mbxid, T_MSG **ppk_msg, TMO tmout )
{
    ER ercd;

    wi_CommonLock();

    //! メールボックスからメッセージを受信する.
    ercd = wi_ReceiveMailBox( mbxid, ppk_msg, tmout );

    wi_CommonUnlock();
    return ercd;
}

メールボックスからメッセージを取得する関数を呼び出してメッセージを取得します。

メールボックスにメッセージが無い場合は、メッセージを受信するか、タイムアウトで設定した時間が経過するまでタスクをスリープさせます。

メールボックスからメッセージを取得する関数

メールボックスからメッセージを取得する関数のソースコードは以下のとおりです。



/****************************************************************************/
/*!
 *  @brief  メールボックスからの受信.
 *
 *  @param  [in]    id      メールボックスID番号.
 *  @param  [out]   ppk_msg メッセージ･パケットのアドレスを格納する領域のポインタ.
 *  @param  [in]    tmout   タイムアウト設定.
 *
 *  @retval エラーコード.
 */
ER      wi_ReceiveMailBox( INT id, T_MSG **msg, TMO tmout )
{
    ER          ercd;
    WIMBXOBJ    *p;

    //! メールボックスIDのオブジェクトを取得する.
    p = (WIMBXOBJ *)wi_FindObject( id, TMAX_MAXMBX, ObjList, &ercd );
    if( !p ){
        return ercd;
    }
    //! 不正な引数の場合はエラーにする.
    if( !msg ){
        return E_PAR;
    }
    //! メッセージ･パケット･リストにメッセージがある場合はメッセージを取り出して終了する.
    if( p->MsgQue ){
        *msg      = p->MsgQue;
        p->MsgQue = p->MsgQue->nextmsg;
        return E_OK;
    }
    //! メッセージを受信するまでタスクをスリープさせる.
    ercd = wi_TaskWait( id, TTW_MBX, tmout, p->Attribute, &(p->WaitQue) );
    if( ercd == E_OK ){
        if( p->MsgQue ){
            *msg      = p->MsgQue;
            p->MsgQue = p->MsgQue->nextmsg;
        }
    }
    return ercd;
}

メールボックスからメッセージを取得する関数は以下のような処理を行います。

  • 引数で指定されたメールボックスID番号に該当するメールボックス･オブジェクトを取り出します。
  • メッセージ･パケット･リストにメッセージが格納されていれば、リストの先頭のメッセージ･パケットを取り出して正常終了します。
  • メッセージ･パケット･リストにメッセージが格納されるか、タイムアウトになるまでタスクをスリープさせます。
  • タスクのスリープから復帰したときに正常終了で復帰した場合のみ、メッセージ･パケット･リストの先頭からメッセージ･パケットを取り出します。
商標に関する表示