io.pkts.packet.sip.header.FromHeader Maven / Gradle / Ivy

Go to download
/**
 * 
 */
package io.pkts.packet.sip.header;

import io.pkts.buffer.Buffer;
import io.pkts.buffer.Buffers;
import io.pkts.packet.sip.SipParseException;
import io.pkts.packet.sip.address.Address;
import io.pkts.packet.sip.header.impl.FromHeaderImpl;

import java.util.Random;


/**
 * Source: RFC 3261 section 8.1.1.3
 * 
 * 
 * The From header field indicates the logical identity of the initiator of the
 * request, possibly the user's address-of-record. Like the To header field, it
 * contains a URI and optionally a display name. It is used by SIP elements to
 * determine which processing rules to apply to a request (for example,
 * automatic call rejection). As such, it is very important that the From URI
 * not contain IP addresses or the FQDN of the host on which the UA is running,
 * since these are not logical names.
 * 
 * 
 * 
 * The From header field allows for a display name. A UAC SHOULD use the display
 * name "Anonymous", along with a syntactically correct, but otherwise
 * meaningless URI (like sip:[email protected]), if the identity of the
 * client is to remain hidden.
 * 
 * 
 * 
 * Usually, the value that populates the From header field in requests generated
 * by a particular UA is pre-provisioned by the user or by the administrators of
 * the user's local domain. If a particular UA is used by multiple users, it
 * might have switchable profiles that include a URI corresponding to the
 * identity of the profiled user. Recipients of requests can authenticate the
 * originator of a request in order to ascertain that they are who their From
 * header field claims they are (see Section 22 for more on authentication).
 * 
 * 
 * 
 * The From field MUST contain a new "tag" parameter, chosen by the UAC. See
 * Section 19.3 for details on choosing a tag.
 * 
 * 
 * 
 * For further information on the From header field, see Section 20.20.
 * Examples:
 * 
 * 
 * 
 * 
 * 
 *    From: "Bob" <sips:[email protected]>tag=a48s
 *    From: sip:[email protected];tag=887s
 *    From: Anonymous <sip:[email protected]>;tag=hyh8
 * 
 * 
 * 
 * 
 * @author [email protected]
 */
public interface FromHeader extends AddressParametersHeader {

    Buffer NAME = Buffers.wrap("From");

    Buffer COMPACT_NAME = Buffers.wrap("f");

    /**
     * Get the tag parameter.
     * 
     * @return the tag or null if it hasn't been set.
     * @throws SipParseException
     *             in case anything goes wrong while extracting tag.
     */
    Buffer getTag() throws SipParseException;

    @Override
    FromHeader clone();

    @Override
    default boolean isFromHeader() {
        return true;
    }

    @Override
    default FromHeader toFromHeader() {
        return this;
    }

    /**
     * Frame the value as a {@link FromHeader}.
     *
     * @param buffer
     * @return
     * @throws SipParseException in case anything goes wrong while parsing.
     */
    static FromHeader frame(final Buffer buffer) throws SipParseException {
        final Buffer original = buffer.slice();
        final Object[] result = AddressParametersHeader.frame(buffer);
        return new FromHeaderImpl(original, (Address) result[0], (Buffer) result[1]);
    }

    /**
     * Frame the value as a {@link FromHeader}.
     *
     * @param buffer
     * @return
     * @throws SipParseException in case anything goes wrong while parsing.
     */
    static FromHeader frame(final String buffer) throws SipParseException {
        return frame(Buffers.wrap(buffer));
    }

    /**
     * Generate a new tag that can be used as a tag parameter for the {@link FromHeader}. A
     * tag-parameter only has to be unique within the same Call-ID space so therefore it doesn't
     * have to be cryptographically strong etc.
     * 
     * @return
     */
    static Buffer generateTag() {
        // TODO: fix this and move it to a better place.
        return Buffers.wrap(Integer.toHexString(new Random().nextInt()));
    }

    static AddressParametersHeader.Builder builder() {
        return new Builder();
    }

    static AddressParametersHeader.Builder withHost(final Buffer host) throws SipParseException {
        return builder().withHost(host);
    }

    static AddressParametersHeader.Builder withHost(final String host) throws SipParseException {
        return builder().withHost(host);
    }

    static AddressParametersHeader.Builder withAddress(final Address address) throws SipParseException {
        return builder().withAddress(address);
    }

    @Override
    AddressParametersHeader.Builder copy();

    class Builder extends AddressParametersHeader.Builder {

        private Builder() {
            super(NAME);
        }

        @Override
        public FromHeader internalBuild(final Buffer rawValue, final Address address, final Buffer params) throws SipParseException {
            return new FromHeaderImpl(rawValue, address, params);
        }
    }

}