archived-doc-es/reference/sem/functions/msg-receive.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: fd2f14b2e44fbda6dd3f94a1d07f2bc9a7567aff Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.msg-receive">
 <refnamediv>
  <refname>msg_receive</refname>
  <refpurpose>Recibe un mensaje desde una cola de mensajes</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>msg_receive</methodname>
   <methodparam><type>SysvMessageQueue</type><parameter>queue</parameter></methodparam>
   <methodparam><type>int</type><parameter>desired_message_type</parameter></methodparam>
   <methodparam><type>int</type><parameter role="reference">received_message_type</parameter></methodparam>
   <methodparam><type>int</type><parameter>max_message_size</parameter></methodparam>
   <methodparam><type>mixed</type><parameter role="reference">message</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>unserialize</parameter><initializer>&true;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter role="reference">error_code</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <simpara>
   <function>msg_receive</function> recibe el primer mensaje de la
   cola <parameter>queue</parameter>, cuyo tipo está especificado por
   <parameter>desired_message_type</parameter>.
  </simpara>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>queue</parameter></term>
    <listitem>
     <simpara>
      Descriptor de recurso de cola de mensajes
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>desired_message_type</parameter></term>
    <listitem>
     <simpara>
      Si <parameter>desired_message_type</parameter> vale 0, se devuelve el primer mensaje
      de la cola. Si <parameter>desired_message_type</parameter> vale
      más que 0, entonces se devolverá el primer mensaje de ese tipo.
      Si <parameter>desired_message_type</parameter> vale menos que 0, se devolverá el primer
      mensaje de la cola cuyo tipo sea inferior o igual al valor absoluto
      de <parameter>desired_message_type</parameter>. Si no hay mensajes
      que cumplan los criterios, el script esperará a que llegue un mensaje
      de ese tipo a la cola. Este bloqueo puede evitarse especificando la opción
      <constant>MSG_IPC_NOWAIT</constant> en el parámetro
      <parameter>flags</parameter>.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>received_message_type</parameter></term>
    <listitem>
     <simpara>
      El tipo de mensaje recibido se almacenará en este parámetro.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>max_message_size</parameter></term>
    <listitem>
     <simpara>
      El tamaño máximo de mensaje se establece mediante
      <parameter>max_message_size</parameter>; si el mensaje de la cola es más grande
      que este tamaño, la función fallará (a menos que se utilice una opción
      <parameter>flags</parameter>, descrita a continuación).
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>message</parameter></term>
    <listitem>
     <simpara>
      El mensaje recibido se almacenará en el parámetro <parameter>message</parameter>,
      a menos que haya habido errores al recibir el mensaje.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>unserialize</parameter></term>
    <listitem>
     <simpara>
      Cuando esto es cierto, el mensaje se trata como si hubiera sido serializado
      con el mismo mecanismo que el módulo de sesión. El mensaje será entonces
      deserializado y devuelto al script. Esto permitirá recibir fácilmente
      arrays u objetos complejos en su script, enviados por otros scripts PHP,
      o, si se utiliza WDDX, desde cualquier fuente compatible con WDDX.
     </simpara>
     <simpara>
      Si <parameter>unserialize</parameter> vale &false;,
      el mensaje se devolverá intacto, sin modificar los valores binarios.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>flags</parameter></term>
    <listitem>
     <para>
      El parámetro <parameter>flags</parameter> permite pasar opciones
      para configurar las llamadas msgrcv. Por omisión, vale 0, pero se pueden
      especificar una o varias opciones combinándolas con el operador OR.
      <table>
       <title>Opciones de la función <function>msg_receive</function></title>
       <tgroup cols="2">
        <tbody>
         <row>
          <entry><constant>MSG_IPC_NOWAIT</constant></entry>
          <entry>Si no hay mensajes del tipo
           <parameter>desired_message_type</parameter>, se devuelve inmediatamente
           y no se espera. La función fallará y devolverá un entero
           correspondiente a <constant>MSG_ENOMSG</constant>.
          </entry>
         </row>
         <row>
          <entry><constant>MSG_EXCEPT</constant></entry>
          <entry>Al utilizar esta opción en combinación con
          un tipo <parameter>desired_message_type</parameter> superior a 0, la
          función leerá el primer mensaje que no sea
          del tipo solicitado por <parameter>desired_message_type</parameter>.</entry>
         </row>
         <row>
          <entry><constant>MSG_NOERROR</constant></entry>
          <entry>
           Si el mensaje es más grande que <parameter>max_message_size</parameter>,
           esta opción truncará el mensaje al tamaño de
           <parameter>max_message_size</parameter> y no reportará errores.
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>errorcode</parameter></term>
    <listitem>
     <simpara>
      Si la función falla, el parámetro opcional
      <parameter>error_code</parameter> se establecerá al valor
      de la variable del sistema errno.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <simpara>
   &return.success;
  </simpara>
  <simpara>
   Al recibir un mensaje con éxito, la cola se actualiza
   de la siguiente manera: <literal>msg_lrpid</literal> toma el valor del identificador
   de proceso del proceso llamante, <literal>msg_qnum</literal> se decrementa en
   1 y <literal>msg_rtime</literal> toma la fecha y hora actuales.
  </simpara>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>queue</parameter> ahora espera una <classname>SysvMessageQueue</classname>;
       anteriormente, se esperaba un <type>resource</type>.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>msg_remove_queue</function></member>
   <member><function>msg_send</function></member>
   <member><function>msg_stat_queue</function></member>
   <member><function>msg_set_queue</function></member>
  </simplelist>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->