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 org.jivesoftware.smack.packet.ExtensionElement;
022import org.jivesoftware.smack.packet.Message;
023import org.jivesoftware.smack.packet.Stanza;
024import org.jivesoftware.smack.packet.id.StanzaIdUtil;
025import org.jivesoftware.smack.provider.ExtensionElementProvider;
026
027import org.xmlpull.v1.XmlPullParser;
028import org.xmlpull.v1.XmlPullParserException;
029
030/**
031 * Represents a <b>message delivery receipt request</b> entry as specified by
032 * <a href="http://xmpp.org/extensions/xep-0184.html">Message Delivery Receipts</a>.
033 *
034 * @author Georg Lukas
035 */
036public class DeliveryReceiptRequest implements ExtensionElement
037{
038    public static final String ELEMENT = "request";
039
040    @Override
041    public String getElementName()
042    {
043        return ELEMENT;
044    }
045
046    @Override
047    public String getNamespace()
048    {
049        return DeliveryReceipt.NAMESPACE;
050    }
051
052    @Override
053    public String toXML()
054    {
055        return "<request xmlns='" + DeliveryReceipt.NAMESPACE + "'/>";
056    }
057
058    /**
059     * Get the {@link DeliveryReceiptRequest} extension of the packet, if any.
060     *
061     * @param p the packet
062     * @return the {@link DeliveryReceiptRequest} extension or {@code null}
063     * @deprecated use {@link #from(Stanza)} instead
064     */
065    @Deprecated
066    public static DeliveryReceiptRequest getFrom(Stanza p) {
067        return from(p);
068    }
069
070    /**
071     * Get the {@link DeliveryReceiptRequest} extension of the packet, if any.
072     *
073     * @param packet the packet
074     * @return the {@link DeliveryReceiptRequest} extension or {@code null}
075     */
076    public static DeliveryReceiptRequest from(Stanza packet) {
077        return packet.getExtension(ELEMENT, DeliveryReceipt.NAMESPACE);
078    }
079
080    /**
081     * Add a delivery receipt request to an outgoing packet.
082     *
083     * Only message packets may contain receipt requests as of XEP-0184,
084     * therefore only allow Message as the parameter type.
085     *
086     * @param message Message object to add a request to
087     * @return the Message ID which will be used as receipt ID
088     */
089    public static String addTo(Message message) {
090        if (message.getStanzaId() == null) {
091            message.setStanzaId(StanzaIdUtil.newStanzaId());
092        }
093        message.addExtension(new DeliveryReceiptRequest());
094        return message.getStanzaId();
095    }
096
097    /**
098     * This Provider parses and returns DeliveryReceiptRequest packets.
099     */
100    public static class Provider extends ExtensionElementProvider<DeliveryReceiptRequest> {
101        @Override
102        public DeliveryReceiptRequest parse(XmlPullParser parser,
103                        int initialDepth) throws XmlPullParserException,
104                        IOException {
105            return new DeliveryReceiptRequest();
106        }
107    }
108}