msg_receive

Descrizione

bool msg_receive ( resource coda, int tipo_desiderato, int &tipo_messaggio, int dimensione_max, mixed &messaggio [, bool unserialize [, int flags [, int codice_errore [, int &codice_errore]]]] )

La funzione msg_receive() riceve il primo messaggio dalla coda specificata in coda del tipo indicato in tipo_desiderato. Il tipo di messaggio che è stato ricevuto viene memorizzato in tipo_messaggio. La dimensione massima del messaggio accettata viene indicata in dimensione_max; se il messaggio nella coda è più grande, la funzione darà esito negativo (a meno che non sia impostato il parametro flags come descritto in seguito). Il messaggio ricevuto sarà memorizzato in messaggio, a meno che non si verifichino degli errori in ricezione, in tal caso il parametro opzionale errorcode sarà valorizzato con il valore della variabile errno per aiutare ad identificare la causa.

Se il parametro tipo_desiderato è 0, verrà restituito il primo messaggio dalla coda. Se, invece, tipo_desiderato è maggiore di 0, sarà restuito il primo messaggio di quel tipo. Mentre se tipo_desiderato è minore di 0, sarà restituito dalla coda il primo messaggio con il tipo più basso o uguale al valore assoluto di tipo_desiderato. Se nessun messaggio soddisfa i criteri impostati, lo script attenderà fino all'arrivo nella coda di un messaggio adeguato. Si può evitare il blocco dello script indicando MSG_IPC_NOWAIT nel parametro flags.

Il parametro unserialize (default TRUE), se viene impostato a TRUE indica di trattare il messaggio come se fosse serializzato utilizzando lo stesso meccanismo del modulo delle sessioni. In tal modo il messaggio può essere deserializzato e restituito allo script. Questo permette di ricevere facilmente array o complesse strutture oggetto da altri script PHP, o, se si sta utilizzando il serializzatore WDDX, da sorgenti compatibili con WDDX. Se unserialize è impostato a FALSE, il messaggio sarà restituito come una stringa.

Il parametro opzionale flags permette di passare flag alla chiamata di sistema msgrcv. Il default è 0, ma possono essere specificati uno o più dei seguenti valori (sommandoli o legandoli con OR).

Una volta eseguita con successo la ricezione, la struttura dati della coda dei messaggi verrà aggiornata come segue: msg_lrpid sarà impostato all'ID di processo del processo chiamante, msg_qnum verrà decrementato di 1 e msg_rtime sarà impostato all'ora corrente.

La funzione msg_receive() restituisce TRUE se ha successo oppure FALSE se non riesce. Se la funzione fallisce, il parametro opzionale codice_errore verrà impostato al valore della variabile errno.

Vedere anche: msg_remove_queue(), msg_send(), msg_stat_queue() e msg_set_queue().