📄 x4089.htm
字号:
>hostname</TT
> with an optional
<TT
CLASS="LITERAL"
>/resource</TT
> depending on the
situation.</P
><P
>If no <TT
CLASS="LITERAL"
>to</TT
> attribute is specified, then
the message will be directed back to the <I
CLASS="EMPHASIS"
>sender</I
>,
or the server, depending on the circumstances.
This may or may not be what you want.</P
><P
>(This is also the case with the <TT
CLASS="LITERAL"
>to</TT
> attribute
for the <TT
CLASS="LITERAL"
><iq/></TT
> element, however
it is not the case with the
<TT
CLASS="LITERAL"
><presence/></TT
>
element.
<A
NAME="PRESENCE-TO"
HREF="#FTN.PRESENCE-TO"
>[1]</A
>
See <A
HREF="x4089.htm#JABTDG-CH-5-SB-2"
>the sidebar <I
>Element Handling by the Jabber Server</I
></A
> for an explanation.)</P
></DD
></DL
></DIV
><TABLE
CLASS="SIDEBAR"
BORDER="1"
CELLPADDING="5"
><TR
><TD
><DIV
CLASS="SIDEBAR"
><A
NAME="JABTDG-CH-5-SB-2"
></A
><P
><B
>Element Handling by the Jabber Server</B
></P
><P
>When elements (packets) make their way over the
<TT
CLASS="LITERAL"
>jabber:client</TT
> XML stream and arrive at the
Jabber server, they're delivered to the JSM which provides many of the
services associated with Jabber's IM features, such as roster management,
presence subscription, offline storage and so on. Each packet received runs
a gauntlet of handlers before being delivered to its ultimate destination
specified by the value of the <TT
CLASS="LITERAL"
>to</TT
> attribute.</P
><P
>In some cases, a packet has no 'ultimate destination' and is deemed to have
been 'handled' without reaching a final delivery point.</P
><P
>In the case of a simple <TT
CLASS="LITERAL"
><message/></TT
>
packet with a JID specified in the <TT
CLASS="LITERAL"
>to</TT
>
attribute, the packet will not be swallowed by a handler, but be delivered to
that JID destination. In the case of a simple
<TT
CLASS="LITERAL"
><presence/></TT
> packet without a
<TT
CLASS="LITERAL"
>to</TT
> attribute (a normal notification of
availability) </P
></DIV
></TD
></TR
></TABLE
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>id</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:
<TT
CLASS="LITERAL"
><message <TT
CLASS="USERINPUT"
><B
>id='JCOM_12'</B
></TT
>></TT
></P
><P
>When a message is sent, and a reply is expected, it is often useful to
give the outbound message an identifier. When the recipient responds,
the identifier is included in the response. In this way, the originator
of the message can work out which reply corresponds to which original
message.</P
><P
>At the Jabber server, this works because a reply is usually built from
a copy of the original message, with the
<TT
CLASS="LITERAL"
>from</TT
> and
<TT
CLASS="LITERAL"
>to</TT
> attributes switched around. So the
<TT
CLASS="LITERAL"
>id</TT
> attribute remains untouched and in
place.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="JABTDG-CH-5-SECT-5.4.1.2"
>Message Subelements</A
></H3
><P
>While the <TT
CLASS="LITERAL"
><message/></TT
> element itself
is a container for the information being carried, the subelements are used to
hold and describe the information being carried. Depending on the
circumstances and the message type, different subelements can be used.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>subject</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:</P
><P
><PRE
CLASS="SCREEN"
><message to='qmacro@jabber.org' from='piers@jabber.org/Home'>
<TT
CLASS="USERINPUT"
><B
><subject>Time to meet?</subject></B
></TT
>
<body>What time to you want to meet this afternoon?</body>
</message></PRE
></P
><P
>The <TT
CLASS="LITERAL"
><subject/></TT
> subelement
is used to set a message subject. Message subjects are not that common
in <TT
CLASS="LITERAL"
>chat</TT
> type messages, but are more appropriate in <TT
CLASS="LITERAL"
>normal</TT
> type messages
where the subject can be displayed in the style of a list of inbox items.
This subelement is also used in <TT
CLASS="LITERAL"
>groupchat</TT
> type messages to set the
subject (or <TT
CLASS="LITERAL"
>topic</TT
>) of a conference room.</P
></DD
><DT
>body</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:</P
><P
><PRE
CLASS="SCREEN"
><message to='qmacro@yak' from='john@yak' type='chat'>
<TT
CLASS="USERINPUT"
><B
><body>Hey - got a minute?</body></B
></TT
>
</message></PRE
></P
><P
>Naturally, the <TT
CLASS="LITERAL"
><body/></TT
> subelement carries
the body of the message.</P
></DD
><DT
>error</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:</P
><P
><PRE
CLASS="SCREEN"
><message to='piers@pipetree.com/Home' from='qmacro@jaber.org' type='error'>
<body>Are you there?</body>
<TT
CLASS="USERINPUT"
><B
><error code='502'>Unable to resolve hostname.</error></B
></TT
>
</message></PRE
></P
><P
>The <TT
CLASS="LITERAL"
><error/></TT
> subelement is for
carrying error information in a problem situation. In this example,
the original message sent by <TT
CLASS="LITERAL"
>piers@pipetree.com</TT
>
was a simple “Are you there?” to what he thought was
<TT
CLASS="LITERAL"
>qmacro</TT
>'s id on the Jabber server at
<TT
CLASS="FILENAME"
>jabber.org</TT
>.
However, the <TT
CLASS="LITERAL"
>to</TT
> attribute was specified
incorrectly (<TT
CLASS="FILENAME"
>jaber.org</TT
>) and the Jabber server on
<TT
CLASS="FILENAME"
>pipetree.com</TT
> wasn't able to resolve the hostname. So
Piers receives his message back with
an additional <TT
CLASS="LITERAL"
><error/></TT
>
subelement, and the message type has been switched to <TT
CLASS="LITERAL"
>error</TT
>
(the <TT
CLASS="LITERAL"
>type='error'</TT
> attribute).</P
><P
>The <TT
CLASS="LITERAL"
><error/></TT
> subelement
carries two pieces of related information: an error number, specified
in the <TT
CLASS="LITERAL"
>code</TT
> attribute, and the error
text. <A
HREF="x4089.htm#JABTDG-CH-5-TAB-3"
>Table 5-3</A
>
shows a list of the standard error codes and texts. The
entity generating the error can specify a custom error text to go with
the error code; if none is specified, the standard text as shown is used.</P
></DD
><DT
>html</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:</P
><P
><PRE
CLASS="SCREEN"
><message id="3" to="dj@yak" type="chat">
<TT
CLASS="USERINPUT"
><B
><html xmlns="http://www.w3.org/1999/xhtml">
<body>
<span style="font-family: Arial; font-size: 10pt">
This is really <em>nice!</em>
</span>
<br/>
</body>
</html></B
></TT
>
<body>This is really nice!</body>
</message></PRE
></P
><P
>The <TT
CLASS="LITERAL"
><html/></TT
> tag is for
support of XHTML-formatted messages. The normal
<TT
CLASS="LITERAL"
><body/></TT
> tag carries plain
text; text formatted with XHTML markup can be carried in
<TT
CLASS="LITERAL"
><message/></TT
> elements inside
the <TT
CLASS="LITERAL"
><html/></TT
> subelement.</P
><P
>The markup must be qualified by the XHTML namespace
<TT
CLASS="LITERAL"
>http://www.w3.org/1999/xhtml</TT
>
(as shown in the example) and conform to the markup described in the
XHTML-Basic specification defined at
<TT
CLASS="LITERAL"
>http://www.w3.org/TR/xhtml-basic</TT
>.</P
><P
>Note that the content of the message must also be repeated in a normal
<TT
CLASS="LITERAL"
><body/></TT
> subelement without
formatting, to comply with the “lowest common denominator” support for
different Jabber clients—not all of them will be able to interpret the XHTML
formatting so will need to receive the message content in a way that they
can understand.</P
><P
>The <TT
CLASS="LITERAL"
><html/></TT
> subelement
effectively is a wrapper around a second, <TT
CLASS="LITERAL"
>alternative</TT
>,
<TT
CLASS="LITERAL"
><body/></TT
> subelement.</P
></DD
><DT
>thread</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:</P
><P
><PRE
CLASS="SCREEN"
><message to='qmacro@jabber.org' type='chat'>
<TT
CLASS="USERINPUT"
><B
><thread>B19217AFEEBDC2611971DD1E8B23AAE4</thread></B
></TT
>
<body>Yes, they're at http://docs.jabber.org</body>
</message></PRE
></P
><P
>The <TT
CLASS="LITERAL"
><thread/></TT
> subelement
is used by clients to group together snippets of conversations (between
users) so that the whole conversation can be visually presented in a
meaningful way. Typically a conversation on a particular topic—a
<I
CLASS="EMPHASIS"
>thread</I
>—will be displayed in a single window. Giving
each conversation thread an identity enables a distinction to be made when
more than one conversation is being held at once and <TT
CLASS="LITERAL"
>chat</TT
> type messages
which are component parts of these conversations are
being received (possibly from the same correspondent) in an unpredictable
sequence.</P
><P
>Only when a new topic or branch of conversation is initiated must a client
generate a thread value. At all other times, the correspondent client must
simply include the <TT
CLASS="LITERAL"
><thread/></TT
>
tag in the response. Here thread value is generated from a hash of
the message originator's JID and the current time.</P
></DD
><DT
>x</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:</P
><P
><PRE
CLASS="SCREEN"
><message to='dj@yak' type='chat' from='sabine@yak/laptop'>
<body>Hi - let me know when you get back. Thanks.</body>
<TT
CLASS="USERINPUT"
><B
><x xmlns='jabber:x:delay' from='dj@yak' stamp='20010514T14:44:09'>
Offline Storage
</x></B
></TT
>
</message></PRE
></P
><P
>The <TT
CLASS="LITERAL"
><x/></TT
> subelement is special.
While the other subelements like
<TT
CLASS="LITERAL"
><body/></TT
> and
<TT
CLASS="LITERAL"
><thread/></TT
> are fixed into the
Jabber building blocks design, the
<TT
CLASS="LITERAL"
><x/></TT
> subelement allows
<TT
CLASS="LITERAL"
><message/></TT
> elements to be
extended to suit requirements. What the
<TT
CLASS="LITERAL"
><x/></TT
> subelement does is
provide an anchor-point for further information to be attached to messages in a
structured way.</P
><P
>The information attached to a message is often called
the <I
CLASS="EMPHASIS"
>payload</I
>. Multiple anchor-points can be used (as in the example)
to convey multiple payloads,
and each one must be <I
CLASS="EMPHASIS"
>qualified</I
> using a namespace.</P
><P
>Just as the content of XML streams is qualified by a namespace (one
from the list in <A
HREF="x3837.htm#JABTDG-CH-5-TAB-2"
>Table 5-2</A
>
earlier in this Chapter), so the content of
the <TT
CLASS="LITERAL"
><x/></TT
> <I
CLASS="EMPHASIS"
>attachment</I
> must
be qualified. There are a number of Jabber-standard namespaces that are
defined for various purposes. One of these,
<TT
CLASS="LITERAL"
>jabber:x:delay</TT
>, is used in the
example. They are described in <A
HREF="c5281.htm"
>Chapter 5a</A
>. But there's
nothing to stop you defining your own namespace to describe (and qualify)
the data that you wish to transport in a
<TT
CLASS="LITERAL"
><message/></TT
>. Namespaces beginning
<TT
CLASS="LITERAL"
>jabber:</TT
> are reserved, anything else is OK.</P
><P
>Briefly, you can see how payloads are attached from the
example. For every <TT
CLASS="LITERAL"
><x/></TT
>
subelement, there's an <TT
CLASS="LITERAL"
>xmlns</TT
> attribute
that qualifies it, and the data contained within the
<TT
CLASS="LITERAL"
><x/></TT
> tag is formatted
depending on the namespace.</P
><P
>In the example, the payload is carried in addition to the
<TT
CLASS="LITERAL"
><body/></TT
> subelement.
However, as the <TT
CLASS="LITERAL"
><body/></TT
> is
actually <I
CLASS="EMPHASIS"
>optional</I
> in a message, it is possible to
transmit structured payloads between Jabber entities without the need
for “conventional” message content.</P
></DD
></DL
></DIV
><DIV
CLASS="TABLE"
><A
NAME="JABTDG-CH-5-TAB-3"
></A
><P
><B
>Table 5-3. Standard Error Codes and Texts</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
ALIGN="LEFT"
VALIGN="TOP"
>Code</TH
><TH
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -