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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: fd2f14b2e44fbda6dd3f94a1d07f2bc9a7567aff Maintainer: nobody Status: ready -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.msg-receive">
 <refnamediv>
  <refname>msg_receive</refname>
  <refpurpose>Liest eine Nachricht aus einer Nachrichten-Warteschlange aus</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> liest die erste Nachricht vom Typ
   <parameter>desired_message_type</parameter> aus der durch
   <parameter>queue</parameter> angegeben Warteschlange aus.
  </simpara>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>queue</parameter></term>
    <listitem>
     <simpara>
      Die Nachrichten-Warteschlange.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>desired_message_type</parameter></term>
    <listitem>
     <simpara>
      Wenn <parameter>desired_message_type</parameter> gleich 0 ist, wird die
      erste Nachricht aus der Warteschlange zurückgegeben. Wenn
      <parameter>desired_message_type</parameter> größer als 0 ist, wird die
      erste Nachricht genau diesen Typs zurückgegeben. Wenn
      <parameter>desired_message_type</parameter> kleiner als 0 ist, wird die
      erste Nachricht kleiner oder gleich dem absoluten Wert von
      <parameter>desired_message_type</parameter> zurückgegeben. Wenn keine
      passende Nachricht existiert, blockiert diese Funktion solange, bis
      eine passende Nachricht verfügbar ist. Durch das Setzen des Flags
      <constant>MSG_IPC_NOWAIT</constant> im Parameter
      <parameter>flags</parameter> kann das blockierende Verhalten verhindert
      werden.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>received_message_type</parameter></term>
    <listitem>
     <simpara>
      In diesem Parameter wird der Typ der empfangenen Nachricht gespeichert.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>max_message_size</parameter></term>
    <listitem>
     <simpara>
      Die maximale Größe der zu akzeptierenden Nachricht wird durch
      <parameter>max_message_size</parameter> angegeben; Wenn die Nachricht
      in der Nachrichten-Warteschlange größer ist, als dieser Wert, schlägt
      die Funktion fehl (es sei denn, es wird das entsprechende Flag im
      Parameter <parameter>flags</parameter> gesetzt).
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>message</parameter></term>
    <listitem>
     <simpara>
      Die empfangene Nachricht wird in <parameter>message</parameter>
      gespeichert, es sei denn es tritt ein Fehler beim Empfang auf.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>unserialize</parameter></term>
    <listitem>
     <simpara>
      Wenn dieser Wert auf &true; gesetzt wird, wird die Nachricht behandelt,
      als wäre sie mit demselben Mechanismus serialisiert worden, wie das
      Session-Modul. Die Nachricht wird deserialisiert und zurückgegeben.
      Dies erlaubt einen einfachen Empfang von Arrays und komplexen
      Objektstrukturen von anderen PHP-Skripten. Wenn Sie den WDDX-Serializer
      verwenden, erlaubt es den Empfang von einer WDDX-kompatiblen Quelle.
     </simpara>
     <simpara>
      Wenn <parameter>unserialize</parameter> &false; ist, wird die Nachricht
      als binärsicherer String zurückgegeben.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>flags</parameter></term>
    <listitem>
     <para>
      Der optionale Parameter <parameter>flags</parameter> erlaubt die
      Weitergabe von Flags an den low-level msgrcv-Systemaufruf. Der
      Standardwert liegt bei 0, aber es können einer oder mehrere der
      folgenden Werte übergeben werden (AND- oder OR-verknüpft).
      <table>
       <title>Die Flag-Werte für msg_receive</title>
       <tgroup cols="2">
        <tbody>
         <row>
          <entry><constant>MSG_IPC_NOWAIT</constant></entry>
          <entry>
           Wenn kein Wert des übergebenen Typs
           <parameter>desired_message_type</parameter> in der Warteschlange
           vorhanden ist, gibt die Funktion sofort zurück, statt zu warten.
           Die Funktion schlägt fehl und gibt den Integerwert entsprechend an
           <constant>MSG_ENOMSG</constant> zurück.
          </entry>
         </row>
         <row>
          <entry><constant>MSG_EXCEPT</constant></entry>
          <entry>
           Dieses Flag sorgt in Kombination mit einem
           <parameter>desired_message_type</parameter> größer als 0 dafür,
           dass die Funktion die erste Nachricht zurück gbit, die nicht
           gleich <parameter>desired_message_type</parameter> ist.
          </entry>
         </row>
         <row>
          <entry><constant>MSG_NOERROR</constant></entry>
          <entry>
           Wenn die Nachricht länger als
           <parameter>max_message_size</parameter> ist, wird durch Setzen
           diese Flags die Nachricht auf
           <parameter>max_message_size</parameter> gekürzt, und die Funktion
           signalisiert keinen Fehler.
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>error_code</parameter></term>
    <listitem>
     <simpara>
      Wenn die Funktion fehlschlägt, wird der optionale
      <parameter>error_code</parameter> auf den Wert der
      System-errno-Variable gesetzt.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <simpara>
   &return.success;
  </simpara>
  <simpara>
   Bei erfolgreicher Ausführung wird die Datenstruktur der
   Nachrichten-Warteschlange folgendermaßen aktualisiert:
   <literal>msg_lrpid</literal> wird auf die Prozess-ID des aufrufenden
   Prozesses gesetzt, <literal>msg_qnum</literal> wird um 1 dekrementiert, und
   <literal>msg_rtime</literal> wird auf die aktuelle Zeit gesetzt.
  </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> erwartet nun eine
       <classname>SysvMessageQueue</classname>-Instanz; vorher wurde eine
       <type>resource</type> erwartet.
      </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
-->