(PHP 4 >= 4.3.0, PHP 5)
msg_receive — Riceve un messaggio da una coda
$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).
MSG_IPC_NOWAIT |
Se non ci sono messaggi del
tipo_desiderato, la funzione ritorna immediatamente senza
aspettare. La funzione fallirà e restituirà un valore intero
corrispondente a ENOMSG.
|
MSG_EXCEPT |
Usando questo flag in combinazione con
tipo_desiderato maggiore di 0, si forza la
funzione a ricevere il primo messaggio che non sia uguale a
tipo_desiderato. |
MSG_NOERROR |
Se il messaggio è più lungo di dimensione_max,
l'attivazione di questo flag troncherà il messaggio a
dimensione_max e non sarà segnalato alcun errore.
|
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().