msg_receive()
will receive the first message from the specified
queue
of the type specified by
desiredmsgtype
. The type of the message that was received will be stored in
msgtype
. The maximum size of message to be accepted is specified by
the
maxsize
; if the message in the queue is larger than this size the
function will fail (unless you set
flags
as described below). The received message will be stored in
message
, unless there were errors receiving the message, in which case
the optional
errorcode
will be set to the value of the system errno variable to help
you identify the cause.
If
desiredmsgtype
is 0, the message from the front of the queue is returned. If
desiredmsgtype
is greater than 0, then the first message of that type is
returned. If
desiredmsgtype
is less than 0, the first message on the queue with the lowest
type less than or equal to the absolute value of
desiredmsgtype
will be read. If no messages match the criteria, your script
will wait until a suitable message arrives on the queue. You
can prevent the script from blocking by specifying
MSG_IPC_NOWAIT in the
flags
parameter.
unserialize
defaults to
TRUE
; if it is set to
TRUE
, the message is treated as though it was serialized using the
same mechanism as the session module. The message will be
unserialized and then returned to your script. This allows you
to easily receive arrays or complex object structures from
other PHP scripts, or if you are using the WDDX serializer,
from any WDDX compatible source. If
unserialize
is
FALSE
, the message will be returned as a binary-safe string.
The optional
flags
allows you to pass flags to the low-level msgrcv system call.
It defaults to 0, but you may specify one or more of the
following values (by adding or ORing them together).
表 1Flag values for msg_receive
MSG_IPC_NOWAIT | If there are no messages of the desiredmsgtype , return immediately and do not wait. The function will fail and return an integer value corresponding to ENOMSG. |
MSG_EXCEPT | Using this flag in combination with a desiredmsgtype greater than 0 will cause the function to receive the first message that is not equal to desiredmsgtype . |
MSG_NOERROR | If the message is longer than maxsize , setting this flag will truncate the message to maxsize and will not signal an error. |
Upon successful completion the message queue data
structure is updated as follows:
msg_lrpid
is set to the process-ID of the calling process,
msg_qnum
is decremented by 1 and
msg_rtime
is set to the current time.
msg_receive()
returns
TRUE
on success or
FALSE
on failure. If the function fails, the optional
errorcode
will be set to the value of the system errno variable.
See also:
msg_remove_queue()
,
msg_send()
,
msg_stat_queue()
and
msg_set_queue()
.
This function was introduced in PHP 4.3.0 (not yet
released).