xQueueReceive

[Queue Management]

queue. h

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

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

待ち行列からアイテムを受信する。 アイテムはコピーによって受け取ります、従って適切な大きさのバッファを提供しなくてはならない。 このバッファにコピーすべきバイト数は待ち行列を作成したときに定義した値です。
この関数は割り込みサービスルーチンでの使用は禁止です。 ISRでの使用にはxQueueReceiveFromISR を参照してください。
xQueueReceive（）はフル機能のタスク間通信APIの一部です。 代替の同等APIはxQueueAltReceive（）です。 両方のバージョンが同じパラメータを必要として、そして同じ値を返します。

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

pvBuffer 　　受信したアイテムがコピーされるバッファへのポインタ。

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

リターン：
もしアイテムが待ち行列から受信に成功した時はpdTRUEが戻る、 さもなければ 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 receive from the queue. 
void vADifferentTask( void *pvParameters ) 
{ 
    struct AMessage *pxRxedMessage;

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

    // ... Rest of task code. 
}