Module sipheader

Various functions for parsing headers or formatting headers for printing.

Introduced in: 15 Nov 2002 by Magnus Ahltorp <ahltorp@nada.kth.se>

Authors: Magnus Ahltorp (ahltorp@nada.kth.se).

Description

Various functions for parsing headers or formatting headers for printing.

Note: some functions do several passes over the same string() to parse it, e.g. 1 pass to find start and end delimiter and one pass for reading the the elements from start to end index, and probably a additional scan to reach the remainder of the string. This performance can be improved, by using a accumulator equiped parser that returns the Match and Rest part of the string, in a single scan.

Note: elements are often only partially parsed - this reduces the amount of parsing done on entries which will only be passed along, but while this improves performance it increases the need for later exception handling.

Function Index

auth/1 Parse an authorization header.
auth_print/1Equivalent to auth_print(Auth, false).
auth_print/2 Generate the value of an WWW-Authenticate that we need when challenging a REGISTER, or a Proxy-Authenticate that we put in other challenges of a request.
build_header_binary/1 Build a SIP header we can combine with a first line and body to create a message to send out on the wire.
callid/1 Get Call-Id: from header.
comma/1 split a comma separated string into separate strings, along the commas (don't include them).
contact/1 Return the parsed Contact: header from Header.
contact_print/1 Take a list of contact records, and return a list of those contacts as strings.
cseq/1 Parse CSeq: header data.
cseq_print/1 Print data parsed with cseq/1.
dialogid/1 Get what in RFC3261 is referred to as a dialog ID.
dict_to_param/1 convert a dictionary containing parameters back into a "name=value" format - the inverse of param_to_dict/1.
event_package/1 Get the Event package name from Header.
expires/1 Get the value of the "Expires" header.
from/1 Parse From: header data.
get_client_transaction_id/1 When we receive a response, we use this function to get an Id which we look up in our transaction state database to see if we have a client transaction handler that should get this response.
get_server_transaction_ack_id_2543/1 When we receive an ACK that has no RFC3261 Via branch parameter, we use this function to get an Id that we then look up in our transaction state database to try and find an existing server transaction that this ACK should be delivered to.
get_server_transaction_id/1 Turn a request into a transaction id, that can be stored in our transaction state database together with a reference to the process handling this request (server transaction handler) if this is a new transaction, or looked up in the database to find an existing handler if this is a resend of the same request or an ACK to a non-2xx response to INVITE.
get_tag/1 Get From- or To-tag from from- or to-header value.
get_via_branch/1 Get the branch from the TopVia parameters, and then remove any YXA loop cookie from it.
get_via_branch_full/1 Get the whole Via branch (inclusive any loop cookie) from Via.
httparg/1 Make dict out of parameters separated by ampersand (&).
is_required/2 Check if Extension appears in a Required: header.
is_supported/2 Check if Extension appears in a Supported: header.
param_to_dict/1 Convert SIP parameter strings into a dictionary.
record_route/1 Return the parsed Record-Route: header from Header.
remove_loop_cookie/1 Removes our special YXA loop cookie from a branch, if it really is an YXA generated branch.
route/1 Return the parsed Route: header from Header.
to/1 Parse To: header data.
topvia/1 get the first Via entry from Header.
via/1 Parse Via: header data.
via_is_equal/2 Compare two Via records according to the rules in RFC3261 20.42 (Via).
via_is_equal/3 Compare one or more parts of two Via records according to RFC3261 20.42.
via_params/1 convert parameters stored in Via to a dictionary.
via_print/1 Print via record() or list() of via record().
via_sentby/1 Extract sent-by part of a via record().

Function Details

auth/1

auth(In) -> dict()

throws {siperror, Status, Reason} | {siperror, Status, Reason, ExtraHeaders}

Parse an authorization header. Note : In is a string like "Digest username=\"test\",realm=\"example.org\" ...", a SIP message can have multiple of those header values in it. This function only handles one at a time. XXX We should preserve the type in the repsonse as well. Define a new record for parsed authentication data and use that.

auth_print/1

auth_print(Auth) -> [string()]

Equivalent to auth_print(Auth, false).

auth_print/2

auth_print(Auth, Stale) -> [string()]

Generate the value of an WWW-Authenticate that we need when challenging a REGISTER, or a Proxy-Authenticate that we put in other challenges of a request.

build_header_binary/1

build_header_binary(Header) -> binary()

throws {siperror, Status, Reason} | {siperror, Status, Reason, ExtraHeaders}

Build a SIP header we can combine with a first line and body to create a message to send out on the wire. We try to prioritize speed here, so we don't spend extra cycles making the resulting data uniformed. We might return a list of lists of binaries, or just binaries.

callid/1

callid(Header) -> string()

Get Call-Id: from header.

comma/1

comma(String) -> [string()]

split a comma separated string into separate strings, along the commas (don't include them). Each substring is cleared of any preceding or trailing spaces. example: "foo, bar, zop, \"quoted, hi\"" -> ["foo","bar","zop", "\"quoted, hi\""]

contact/1

contact(Header) -> [#contact{}]

Return the parsed Contact: header from Header.

contact_print/1

contact_print(Contacts) -> [string()]

Take a list of contact records, and return a list of those contacts as strings

cseq/1

cseq(Header::In) -> {Seq, Method} | {unparseable, String}

Parse CSeq: header data.

cseq_print/1

cseq_print(X1::{Seq, Method}) -> string()

Print data parsed with cseq/1.

dialogid/1

dialogid(Header) -> {CallID, FromTag, ToTag}

Get what in RFC3261 is referred to as a dialog ID. This will be the same for all requests in a dialog. Note though that the ToTag might be 'none' and later get set.

dict_to_param/1

dict_to_param(Dict) -> [string()]

convert a dictionary containing parameters back into a "name=value" format - the inverse of param_to_dict/1

event_package/1

event_package(Header) -> EventPackage

Get the Event package name from Header.

expires/1

expires(Header) -> Expires

Get the value of the "Expires" header.

from/1

from(Header::In) -> {DisplayName, URI}

Parse From: header data.

See also: name_header/1.

get_client_transaction_id/1

get_client_transaction_id(Response) -> Id

When we receive a response, we use this function to get an Id which we look up in our transaction state database to see if we have a client transaction handler that should get this response. This is specified in RFC3261 #17.1.3 (Matching Responses to Client Transactions).

get_server_transaction_ack_id_2543/1

get_server_transaction_ack_id_2543(Request) -> Id

When we receive an ACK that has no RFC3261 Via branch parameter, we use this function to get an Id that we then look up in our transaction state database to try and find an existing server transaction that this ACK should be delivered to. This is specified in RFC3261 #17.2.3 (Matching Requests to Server Transactions). Note : When using this function, you have to make sure the To-tag of this ACK matches the To-tag of the response you think this might be the ACK for! Note : RFC3261 #17.2.3 relevant text : The ACK request matches a transaction if the Request- URI, From tag, Call-ID, CSeq number (not the method), and top Via header field match those of the INVITE request which created the transaction, and the To tag of the ACK matches the To tag of the response sent by the server transaction. Note : We are supposed to do the comparison of for example, the URI, according to the matching rules for URIs but that would require us to do a full table scan for every ACK. XXX perhaps we should divide the Id into two parts - one that is byte-by-byte and used as table index, and another part for elements that require more exhaustive matching.

get_server_transaction_id/1

get_server_transaction_id(Request) -> Id

Turn a request into a transaction id, that can be stored in our transaction state database together with a reference to the process handling this request (server transaction handler) if this is a new transaction, or looked up in the database to find an existing handler if this is a resend of the same request or an ACK to a non-2xx response to INVITE. This is specified in RFC3261 #17.2.3 (Matching Requests to Server Transactions).

get_tag/1

get_tag(X1::[String]) -> Tag

Get From- or To-tag from from- or to-header value. Note : This function really ought to parse String using contact:new() in order to not be fooled by $> appearing more than once, tag= not written in lowercase etc.

get_via_branch/1

get_via_branch(TopVia) -> Branch

Get the branch from the TopVia parameters, and then remove any YXA loop cookie from it. This function should typically only be called on a Via that matches this proxy so that should be ok - we won't be altering anyone elses branches.

get_via_branch_full/1

get_via_branch_full(Via) -> Branch

Get the whole Via branch (inclusive any loop cookie) from Via.

httparg/1

httparg(String) -> dict()

Make dict out of parameters separated by ampersand (&). Note : Only used in admin_www. Perhaps move there?

is_required/2

is_required(Extension, Header) -> true | false

Check if Extension appears in a Required: header.

is_supported/2

is_supported(Extension, Header) -> true | false

Check if Extension appears in a Supported: header.

param_to_dict/1

param_to_dict(Param) -> dict()

Convert SIP parameter strings into a dictionary.

record_route/1

record_route(Header) -> [#contact{}]

Return the parsed Record-Route: header from Header.

remove_loop_cookie/1

remove_loop_cookie(Branch) -> Branch | NewBranch

Removes our special YXA loop cookie from a branch, if it really is an YXA generated branch.

route/1

route(Header) -> [#contact{}]

Return the parsed Route: header from Header.

to/1

to(Header::In) -> {DisplayName, URI}

Parse To: header data.

See also: name_header/1.

topvia/1

topvia(Header) -> #via{} | none

get the first Via entry from Header

via/1

via(Header::In) -> [#via{}]

throws {error, Reason}

Parse Via: header data.

via_is_equal/2

via_is_equal(A, B) -> true | false

Compare two Via records according to the rules in RFC3261 20.42 (Via)

via_is_equal/3

via_is_equal(A, B, T::CmpList) -> true | false

Compare one or more parts of two Via records according to RFC3261 20.42.

via_params/1

via_params(Via) -> dict()

convert parameters stored in Via to a dictionary

via_print/1

via_print(Via) -> [ViaStr]

Print via record() or list() of via record().

via_sentby/1

via_sentby(Via) -> {Proto, Host, Port}

Extract sent-by part of a via record()


Generated by EDoc, Oct 17 2007, 16:48:26.