xQueuePeek

[Queue Management]

FreeRTOS.org V4.5.0 以降で利用可能です。

queue.h

portBASE_TYPE xQueuePeek( xQueueHandle xQueue, void *pvBuffer, portTickType xTicksToWait );

これは xQueueGenericReceive () 機能を呼び出すマクロです。

アイテムを待ち行列から受信し、そのアイテムを待ち行列から取り除かないで保持したままとする。
アイテムはコピーによって受け取られます、従って適切な大きさのバッファを用意しなくてはならない。 このバッファにコピーすべきバイト数は待ち行列を作成したときに定義した値です。受信に成功したアイテムが待ち行列に残っています、それで次のコール、あるいは xQueueReceive() のコールによって再び受信されます。
このマクロは割り込みサービスルーチンでは使用禁止です。
xQueuePeek () は API. xQueueAltPeek () が代わりの API 同等物であるという完全に呼び物にされるタスク間コミュニケーションの一部です。xQueuePeek（）は、フル機能のタスク間通信APIの一部です。 代替の同等APIはxQueueAltPeek（）です。 両方のバージョンが同じパラメータを必要として、そして同じ値を返します。

パラメータ：
xQueue 　　アイテムを受信すべき待ち行列へのハンドル。

pvBuffer 　　受信アイテムがコピーされるバッファへのポインタ。 これは、少なくとも十分な大きさ（キューが作成された時アイテムが定義されたサイズ）に保持する必要があります。

xTicksToWait 　　もし待ち行列がコールの時点で空であったなら、受信アイテムを待ちタスクをブロックする最大の時間 時間はチック（システムクロック）ピリオドで定義されます、定数portTICK_RATE_MS は必要ならチック数をリアルタイムに変換するのに使用する。もし INCLUDE_vTaskSuspend が「１」にした場合、ブロックタイムを portMAX_DELAY と明示すると、タスクを（要因がなくなるまで、タイムアウトなしで）いつまでもブロックさせる

リターン：
もしアイテムが受信に成功（peeked）なら待ち行列からｐｄTRUEが戻る、さもなければ pdFALSEが戻る。

使用例：

 struct AMessage
 {
    portCHAR ucMessageID;
    portCHAR ucData[ 20 ];
 } xMessage;

 xQueueHandle xQueue;

 // Task to create a queue and post a value.
 void vATask( void *pvParameters )
 {
 struct AMessage *pxMessage;

    // Create a queue capable of containing 10 pointers to AMessage structures.
    // These should be passed by pointer as they contain a lot of data.
    xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );
    if( xQueue == 0 )
    {
        // Failed to create the queue.
    }

    // ...

    // Send a pointer to a struct AMessage object.  Don't block if the
    // queue is already full.
    pxMessage = & xMessage;
    xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );

    // ... Rest of task code.
 }

 // Task to peek the data from the queue.
 void vADifferentTask( void *pvParameters )
 {
 struct AMessage *pxRxedMessage;

    if( xQueue != 0 )
    {
        // Peek a message on the created queue.  Block for 10 ticks if a
        // message is not immediately available.
        if( xQueuePeek( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )
        {
            // pcRxedMessage now points to the struct AMessage variable posted
            // by vATask, but the item still remains on the queue.
        }
    }

    // ... Rest of task code.
 }