Manuel PHP
Précédent |  | Suivant

# msg_receive

(PHP 4 >= 4.3.0, PHP 5)

msg_receive -- Reçoit un message depuis une file de messages

## Description

bool msg_receive ( resource queue, int desiredmsgtype, int &msgtype, int maxsize, mixed &message [, bool unserialize [, int flags [, int &errorcode]]] )

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).

Tableau 1. Iptions de la fonction msg_receive()

`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().

Précédent | Sommaire | Suivant
msg_get_queue | Niveau supérieur | msg_remove_queue