msg_receive
(PHP 4 >= 4.3.0, PHP 5)
msg_receive — Reçoit un message depuis une file de messages
Description
msg_receive() reçoit le premier message de la file queue , type spécifié par desiredmsgtype . Le type de message qui a été reçu sera stocké dans le paramètre msgtype . La taille maximale de message est fixée par maxsize ; si le message de la file est plus grand que cette taille, la fonction échouera (à moins que vous n'utilisiez une option flags , décrite ci-dessous). Le message reçu sera stocké dans le paramètre message , à moins qu'il n'y ait eu des erreurs de réception du message, auquel cas le paramètre optionnel errorcode se verra assigner le numéro d'erreur.
Si desiredmsgtype vaut 0, le premier message de la file est retourné. Si desiredmsgtype vaut plus que 0, alors le premier message de ce type sera retourné. Si desiredmsgtype vaut moins que 0, le premier message de la file ayant un type inférieur ou égaql à la valeur absolue de desiredmsgtype sera retourné. Si aucun message ne correspond aux critères, votre script attendra la venue d'un tel message dans la file. Vous pouvez éviter ce bloquage en précisant l'option MSG_IPC_NOWAIT dans le paramètre flags .
unserialize vaut par défaut TRUE ; quand c'est le cas, le message est traité comme s'il avait été linéarisé avec le même mécanisme que le module de session. Le message sera alors délinéarisé, puis retourné au script. Cela vous permettra de recevoir facilement des tableaux ou des objets complexes dans votre script, émis par d'autres scripts PHP. Si unserialize vaut FALSE, le message sera retourné intact, et sans modifier les valeurs binaires.
Le paramètre flags permet de passer des options pour configurer les appels msgrcv. Par défaut, il vaut 0, mais vous pouvez spécifier une ou plusieurs options en les combinant avec l'opérateur OR).
| MSG_IPC_NOWAIT | S'il n'y a pas de message du type desiredmsgtype , retourne immédiatement, et n'attend pas. La fonction échouera et retournera un entier correspondant à MSG_ENOMSG. |
| MSG_EXCEPT | En utilisant cette option en combinaison avec un type desiredmsgtype supérieur à 0, la fonction va lire le premier message qui n'est pas du type demandé par desiredmsgtype . |
| MSG_NOERROR | Si le message est plus grand que maxsize , cette option va tronquer le message à la taille de maxsize et ne signalera pas d'erreur. |
Lors de la réception réussie d'un message, la file est mise à jour comme ceci : msg_lrpid prend la valeur de l'identifiant de processus du processus appelant, msg_qnum est décrementé de 1 et msg_rtime prend la date et l'heure courante.
msg_receive() retourne TRUE en cas de succès et FALSE en cas d'échec. Si la fonction échoue, le paramètre optionnel errorcode contiendra le numéro d'erreur rencontré.
Voir aussi msg_remove_queue(), msg_send(), msg_stat_queue() et msg_set_queue().