7.93.9 msg_receive() Reçoit un message depuis une file de messages

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 reception du message, auquel cas le paramètre optionnel errorcode se verra assigné 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ée. 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 mssage est traité comme si 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	Si 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 à 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 .

Cette fonction a été introduite en PHP 4.3.0.