001/*
002 *
003 * Copyright 2013-2014 the original author or authors
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.jivesoftware.smackx.receipts;
018
019import java.io.IOException;
020
021import javax.xml.namespace.QName;
022
023import org.jivesoftware.smack.packet.ExtensionElement;
024import org.jivesoftware.smack.packet.Message;
025import org.jivesoftware.smack.packet.MessageBuilder;
026import org.jivesoftware.smack.packet.Stanza;
027import org.jivesoftware.smack.packet.XmlEnvironment;
028import org.jivesoftware.smack.provider.ExtensionElementProvider;
029import org.jivesoftware.smack.xml.XmlPullParser;
030import org.jivesoftware.smack.xml.XmlPullParserException;
031
032import org.jxmpp.JxmppContext;
033
034/**
035 * Represents a <b>message delivery receipt request</b> entry as specified by
036 * <a href="http://xmpp.org/extensions/xep-0184.html">Message Delivery Receipts</a>.
037 *
038 * @author Georg Lukas
039 */
040public class DeliveryReceiptRequest implements ExtensionElement {
041    public static final String ELEMENT = "request";
042    public static final String NAMESPACE = DeliveryReceipt.NAMESPACE;
043    public static final QName QNAME = new QName(NAMESPACE, ELEMENT);
044
045    @Override
046    public String getElementName() {
047        return ELEMENT;
048    }
049
050    @Override
051    public String getNamespace() {
052        return DeliveryReceipt.NAMESPACE;
053    }
054
055    @Override
056    public String toXML(org.jivesoftware.smack.packet.XmlEnvironment enclosingNamespace) {
057        return "<request xmlns='" + DeliveryReceipt.NAMESPACE + "'/>";
058    }
059
060    /**
061     * Get the {@link DeliveryReceiptRequest} extension of the packet, if any.
062     *
063     * @param p the packet
064     * @return the {@link DeliveryReceiptRequest} extension or {@code null}
065     * @deprecated use {@link #from(Stanza)} instead
066     */
067    @Deprecated
068    public static DeliveryReceiptRequest getFrom(Stanza p) {
069        return from(p);
070    }
071
072    /**
073     * Get the {@link DeliveryReceiptRequest} extension of the packet, if any.
074     *
075     * @param packet the packet
076     * @return the {@link DeliveryReceiptRequest} extension or {@code null}
077     */
078    public static DeliveryReceiptRequest from(Stanza packet) {
079        return packet.getExtension(DeliveryReceiptRequest.class);
080    }
081
082    /**
083     * Add a delivery receipt request to an outgoing packet.
084     *
085     * Only message packets may contain receipt requests as of XEP-0184,
086     * therefore only allow Message as the parameter type.
087     *
088     * @param message Message object to add a request to
089     * @return the Message ID which will be used as receipt ID
090     */
091    // TODO: Deprecate in favor of addTo(MessageBuilder) once connection's stanza interceptors use StanzaBuilder.
092    public static String addTo(Message message) {
093        message.throwIfNoStanzaId();
094
095        message.addExtension(new DeliveryReceiptRequest());
096        return message.getStanzaId();
097    }
098
099    /**
100     * Add a delivery receipt request to an outgoing packet.
101     *
102     * Only message packets may contain receipt requests as of XEP-0184,
103     * therefore only allow Message as the parameter type.
104     *
105     * @param messageBuilder Message object to add a request to
106     */
107    public static void addTo(MessageBuilder messageBuilder) {
108        messageBuilder.throwIfNoStanzaId();
109
110        messageBuilder.overrideExtension(new DeliveryReceiptRequest());
111    }
112
113    /**
114     * This Provider parses and returns DeliveryReceiptRequest packets.
115     */
116    public static class Provider extends ExtensionElementProvider<DeliveryReceiptRequest> {
117        @Override
118        public DeliveryReceiptRequest parse(XmlPullParser parser,
119                        int initialDepth, XmlEnvironment xmlEnvironment, JxmppContext jxmppContext) throws XmlPullParserException,
120                        IOException {
121            return new DeliveryReceiptRequest();
122        }
123    }
124}