diff options
Diffstat (limited to 'lib/diameter/doc/src')
| -rw-r--r-- | lib/diameter/doc/src/.gitignore | 2 | ||||
| -rw-r--r-- | lib/diameter/doc/src/Makefile | 198 | ||||
| -rw-r--r-- | lib/diameter/doc/src/book.xml | 56 | ||||
| -rw-r--r-- | lib/diameter/doc/src/depend.sed | 34 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter.xml | 1175 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_app.xml | 615 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_compile.xml | 124 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_dict.xml | 613 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_examples.xml | 45 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_intro.xml | 95 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_sctp.xml | 135 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_soc.xml | 110 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_tcp.xml | 111 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_transport.xml | 203 | ||||
| -rw-r--r-- | lib/diameter/doc/src/diameter_using.xml | 43 | ||||
| -rw-r--r-- | lib/diameter/doc/src/files.mk | 52 | ||||
| -rw-r--r-- | lib/diameter/doc/src/notes.gif | bin | 0 -> 2005 bytes | |||
| -rw-r--r-- | lib/diameter/doc/src/notes.xml | 233 | ||||
| -rw-r--r-- | lib/diameter/doc/src/ref_man.xml | 48 | ||||
| -rw-r--r-- | lib/diameter/doc/src/user_man.xml | 44 |
20 files changed, 3936 insertions, 0 deletions
diff --git a/lib/diameter/doc/src/.gitignore b/lib/diameter/doc/src/.gitignore new file mode 100644 index 0000000000..feeb378fd8 --- /dev/null +++ b/lib/diameter/doc/src/.gitignore @@ -0,0 +1,2 @@ + +/depend.mk diff --git a/lib/diameter/doc/src/Makefile b/lib/diameter/doc/src/Makefile new file mode 100644 index 0000000000..1453138cb6 --- /dev/null +++ b/lib/diameter/doc/src/Makefile @@ -0,0 +1,198 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 2010-2011. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% + +ifneq ($(ERL_TOP),) +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk +else +include $(DIAMETER_TOP)/make/target.mk +include $(DIAMETER_TOP)/make/$(TARGET)/rules.mk +endif + +include ../../vsn.mk + +VSN = $(DIAMETER_VSN) + +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +include files.mk + +XML_REF_FILES = $(XML_REF1_FILES) $(XML_REF3_FILES) $(XML_REF4_FILES) + +XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) \ + $(XML_REF_FILES) \ + $(XML_PART_FILES) $(XML_CHAPTER_FILES) + +INTERNAL_HTML_FILES = $(TECHNICAL_DESCR_FILES:%.xml=$(HTMLDIR)/%.html) + +HTML_APP_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) +HTML_EXTRA_FILES = $(XML_EXTRA_FILES:%.xml=$(HTMLDIR)/%.html) +HTML_PART_FILES = $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +HTML_FILES = $(HTML_APP_FILES) $(HTML_EXTRA_FILES) $(HTML_PART_FILES) + +INFO_FILE = ../../info + +HTML_REF_FILES = $(XML_REF_FILES:%.xml=$(HTMLDIR)/%.html) + +HTML_CHAPTER_FILES = $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html) + +EXTRA_FILES = \ + $(DEFAULT_GIF_FILES) \ + $(DEFAULT_HTML_FILES) \ + $(HTML_REF_FILES) \ + $(HTML_CHAPTER_FILES) + +MAN1_FILES = $(XML_REF1_FILES:%.xml=$(MAN1DIR)/%.1) +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) +MAN4_FILES = $(XML_REF4_FILES:%.xml=$(MAN4DIR)/%.4) + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +STANDARD_DIR = ../standard +STANDARDS = + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- + +XML_FLAGS += +DVIPS_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- + +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +docs: pdf html man + +ldocs: local_docs $(INDEX_TARGET) + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +clean clean_docs: clean_pdf clean_html clean_man + rm -f errs core *~ + rm -f depend.mk + +clean_pdf: + rm -f $(PDFDIR)/* + +clean_man: + rm -f $(MAN1DIR)/* $(MAN3DIR)/* $(MAN4DIR)/* + +clean_html: + rm -rf $(HTMLDIR)/* + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +man: $(MAN1_FILES) $(MAN3_FILES) $(MAN4_FILES) + +$(INDEX_TARGET): $(INDEX_SRC) $(APP_FILE) + sed -e 's/%VSN%/$(VSN)/; \ + s/%ERLANG_SITE%/www\.erlang\.se\//; \ + s/%UP_ONE_LEVEL%/..\/..\/..\/doc\/index.html/; \ + s/%OFF_PRINT%/pdf\/diameter-$(VSN).pdf/' $< > $@ + +depend: depend.mk + +debug opt: + +info: + @echo "->Makefile<-" + @echo "" + @echo "DOCSUPPORT = $(DOCSUPPORT)" + @echo "" + @echo "INDEX_FILE = $(INDEX_FILE)" + @echo "INDEX_SRC = $(INDEX_SRC)" + @echo "INDEX_TARGET = $(INDEX_TARGET)" + @echo "" + @echo "XML_APPLICATION_FILES = $(XML_APPLICATION_FILES)" + @echo "XML_PART_FILES = $(XML_PART_FILES)" + @echo "XML_REF1_FILES = $(XML_REF1_FILES)" + @echo "XML_REF3_FILES = $(XML_REF3_FILES)" + @echo "XML_REF4_FILES = $(XML_REF4_FILES)" + @echo "XML_CHAPTER_FILES = $(XML_CHAPTER_FILES)" + @echo "" + @echo "GIF_FILES = $(GIF_FILES)" + @echo "" + @echo "TEX_FILES_USERS_GUIDE = $(TEX_FILES_USERS_GUIDE)" + @echo "TEX_FILES_REF_MAN = $(TEX_FILES_REF_MAN)" + @echo "TEX_FILES_BOOK = $(TEX_FILES_BOOK)" + @echo "" + @echo "MAN1_FILES = $(MAN1_FILES)" + @echo "MAN3_FILES = $(MAN3_FILES)" + @echo "MAN4_FILES = $(MAN4_FILES)" + @echo "" + @echo "HTML_FILES = $(HTML_FILES)" + @echo "TOP_HTML_FILES = $(TOP_HTML_FILES)" + @echo "" + @echo "DEFAULT_HTML_FILES = $(DEFAULT_HTML_FILES)" + @echo "DEFAULT_GIF_FILES = $(DEFAULT_GIF_FILES)" + @echo "" + @echo "" + + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +ifneq ($(ERL_TOP),) +include $(ERL_TOP)/make/otp_release_targets.mk +else +include $(DIAMETER_TOP)/make/release_targets.mk +endif + +release_docs_spec: $(LOCAL)docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DIR) $(RELEASE_PATH)/man/man1 + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DIR) $(RELEASE_PATH)/man/man4 + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(HTMLDIR)/*.* $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DATA) $(MAN1_FILES) $(RELEASE_PATH)/man/man1 + $(INSTALL_DATA) $(MAN3_FILES) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN4_FILES) $(RELEASE_PATH)/man/man4 + [ -z "$(LOCAL)" ] || cp -r $(HTMLDIR)/js $(RELSYSDIR)/doc/html + echo $(LOCAL) + +release_spec: + +depend.mk: depend.sed $(XML_REF_FILES) $(XML_CHAPTER_FILES) Makefile + (for f in $(XML_REF_FILES) $(XML_CHAPTER_FILES); do \ + sed -f $< $$f | sed "s@%FILE%@`basename $$f .xml`@g"; \ + done) \ + > $@ + +-include depend.mk + +.PHONY: clean clean_html clean_man clean_pdf \ + depend debug opt info \ + docs gifs html ldocs man pdf \ + release_docs_spec release_spec diff --git a/lib/diameter/doc/src/book.xml b/lib/diameter/doc/src/book.xml new file mode 100644 index 0000000000..960296528b --- /dev/null +++ b/lib/diameter/doc/src/book.xml @@ -0,0 +1,56 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE book SYSTEM "book.dtd"> + +<book xmlns:xi="http://www.w3.org/2001/XInclude"> + +<header titlestyle="normal"> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Diameter</title> +<prepared></prepared> +<docno></docno> +<date></date> +<rev></rev> +<file>book.xml</file> +</header> + +<insidecover> +</insidecover> + +<pagetext>Diameter</pagetext> + +<preamble> +<contents level="2"></contents> +</preamble> + +<parts lift="no"> +<xi:include href="user_man.xml"/> +</parts> + +<applications> +<xi:include href="ref_man.xml"/> +</applications> + +<releasenotes> +<xi:include href="notes.xml"/> +</releasenotes> + +<index></index> + +</book> diff --git a/lib/diameter/doc/src/depend.sed b/lib/diameter/doc/src/depend.sed new file mode 100644 index 0000000000..5973c4586e --- /dev/null +++ b/lib/diameter/doc/src/depend.sed @@ -0,0 +1,34 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 2011. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% + +# +# Generate dependencies for html output. The output is further +# massaged in Makefile. +# + +/^<com>\([^<]*\)<\/com>/b rf +/^<module>\([^<]*\)<\/module>/b rf + +/^<chapter>/!d + +s@@$(HTMLDIR)/%FILE%.html: %FILE%.xml@ +q + +:rf +s@@$(HTMLDIR)/\1.html: %FILE%.xml@ +q diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml new file mode 100644 index 0000000000..2cad70e3bc --- /dev/null +++ b/lib/diameter/doc/src/diameter.xml @@ -0,0 +1,1175 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> +<header> + +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>diameter(3)</title> + +<prepared>Anders Svensson</prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev>%VSN%</rev> +<file>diameter.xml</file> + +</header> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<module>diameter</module> +<modulesummary>Main API of the diameter application.</modulesummary> + +<description> +<p> +This module provides the interface with which a user +creates a service that sends and receives messages using the +Diameter protocol as defined in RFC 3588.</p> + +<p> +Basic usage consists of creating a representation of a +locally implemented Diameter peer and its capabilities with <seealso +marker="#start_service">start_service/2</seealso>, adding transport +capability using <seealso +marker="#add_transport">add_transport/2</seealso> and sending Diameter +requests and receiving Diameter answers with <seealso +marker="#call">call/4</seealso>. +Incoming Diameter requests are communicated as callbacks to a +<seealso +marker="diameter_app">diameter_app(3)</seealso> callback modules as +specified in the service configuration.</p> + +<p> +Beware the difference between <em>diameter application</em> and +<em>Diameter application</em>. +The former refers to the Erlang application named diameter whose main +api is defined here, the latter to an application of the Diameter +protocol in the sense of RFC 3588. +More generally, capitalized Diameter refers to the RFC +and diameter to this implementation.</p> + +<p> +The diameter application must be started before calling functions in +this module.</p> + +</description> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> +<section> +<title>DATA TYPES</title> + +<taglist> + +<tag><c>Address()</c></tag> +<tag><c>DiameterIdentity()</c></tag> +<tag><c>Time()</c></tag> +<tag><c>Unsigned32()</c></tag> +<tag><c>UTF8String()</c></tag> +<item> +<p> +Types corresponding to RFC 3588 AVP Data Formats. +Defined in <seealso marker="diameter_dict">diameter_dict(4)</seealso>.</p> + +<marker id="application_alias"/> +</item> + +<tag><c>application_alias() = term()</c></tag> +<item> +<p> +A name identifying a Diameter application in +service configuration passed to <seealso +marker="#start_service">start_service/2</seealso> and passed to +<seealso marker="#call">call/4</seealso> when sending requests +belonging to the application.</p> + +<marker id="application_module"/> +</item> + +<tag><c>application_module() = Mod | [Mod | ExtraArgs]</c></tag> +<item> +<code> +Mod = atom() +ExtraArgs = list() +</code> + +<p> +A module implementing the callback interface defined in <seealso +marker="diameter_app">diameter_app(3)</seealso>, along with any +extra arguments to be appended to those documented for the interface. +Any extra arguments are appended to the documented list of arguments for +each function. +Note that additional arguments specific to an outgoing request be +specified to <seealso marker="#call">call/4</seealso>, in which case +the call-specific arguments are appended to any specified with the +callback module.</p> + +<marker id="application_opt"/> +</item> + +<tag><c>application_opt()</c></tag> +<item> + +<p> +Options defining a Diameter application as configured in an +<c>application</c> option passed to +<seealso marker="#start_service">start_service/2</seealso>.</p> + +<taglist> + +<tag><c>{alias, application_alias()}</c></tag> +<item> +<p> +An unique identifier for the application in the scope of the +service. +Optional, defaults to the value of the <c>dictionary</c> option.</p> +</item> + +<tag><c>{dictionary, atom()}</c></tag> +<item> +<p> +The name of an encode/decode module for the Diameter +messages defined by the application. +These modules are generated from a specification file whose format is +documented in <seealso +marker="diameter_dict">diameter_dict(4)</seealso>.</p> +</item> + +<tag><c>{module, application_module()}</c></tag> +<item> +<p> +A callback module with which messages of the Diameter application are +handled. +See <seealso marker="diameter_app">diameter_app(3)</seealso> for +information on the required interface and semantics.</p> +</item> + +<tag><c>{state, term()}</c></tag> +<item> +<p> +The initial callback state. +Defaults to the value of the <c>alias</c> option if unspecified. +The prevailing state is passed to certain +<seealso marker="diameter_app">diameter_app(3)</seealso> +callbacks, which can then return a new state.</p> +</item> + +<tag><c>{call_mutates_state, true|false}</c></tag> +<item> +<p> +Specifies whether or not the <seealso +marker="diameter_app#pick_peer">pick_peer/4</seealso> +application callback (following from a call to +<seealso marker="#call">call/4</seealso>) +can modifiy state, +Defaults to <c>false</c> if unspecified.</p> + +<p> +Note that <seealso +marker="diameter_app#pick_peer">pick_peer</seealso> callbacks are +serialized when these are allowed to modify state, which is a +potential performance bottleneck. +A simple Diameter client may suffer no ill effects from using mutable +state but a server or agent that responds to incoming request but +sending its own requests should probably avoid it.</p> +</item> + +<tag><c>{answer_errors, callback|report|discard}</c></tag> +<item> +<p> +Determines the manner in which incoming answer messages containing +decode errors are handled. +If <c>callback</c> then errors result in a <seealso +marker="diameter_app#handle_answer">handle_answer/4</seealso> +callback in the same fashion as for <seealso +marker="diameter_app#handle_request">handle_request/3</seealso>, in the +<c>errors</c> field of the <c>diameter_packet</c> record passed into +the callback. +If <c>report</c> then an answer containing errors is discarded +without a callback and a warning report is written to the log. +If <c>discard</c> then an answer containing errors is silently +discarded without a callback. +In both the <c>report</c> and <c>discard</c> cases the return value +for the <seealso marker="#call">call/4</seealso> invocation in +question is as if a callback had taken place and returned +<c>{error, failure}</c>.</p> + +<p> +Defaults to <c>report</c> if unspecified.</p> +</item> + +</taglist> + +<marker id="call_opt"/> +</item> + +<tag><c>call_opt()</c></tag> +<item> + +<p> +Options available to <seealso marker="#call">call/4</seealso> when +sending an outgoing Diameter request.</p> + +<taglist> + +<tag><c>{extra, list()}</c></tag> +<item> +<p> +Extra arguments to append to callbacks to the callback +module in question. +These are appended to any extra arguments configured with the callback +itself. +Multiple options append to the argument list.</p> +</item> + +<tag><c>{filter, peer_filter()}</c></tag> +<item> +<p> +A filter to apply to the list of available peers before passing them to +the <seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> +callback for the application in question. +Multiple options are equivalent a single <c>all</c> filter on the +corresponding list of filters. +Defaults to <c>none</c>.</p> +</item> + +<tag><c>{timeout, Unsigned32()}</c></tag> +<item> +<p> +The number of milliseconds after which the request should +timeout. +Defaults to 5000.</p> +</item> + +<tag><c>detach</c></tag> +<item> +<p> +Causes <seealso marker="#call">call/4</seealso> to return <c>ok</c> as +soon as the request in +question has been encoded instead of waiting for and returning +the result from a subsequent +<seealso marker="diameter_app#handle_answer">handle_answer/4</seealso> +or <seealso +marker="diameter_app#handle_error">handle_error/4</seealso> +callback.</p> +</item> + +</taglist> + +<p> +An invalid option will cause <seealso marker="#call">call/4</seealso> +to fail.</p> + +<marker id="capability"/> +</item> + +<tag><c>capability()</c></tag> +<item> + +<p> +AVP values used in outgoing CER/CEA messages during capabilities exchange. +Can be configured both on a service and a transport, the latter taking +precedence over the former.</p> + +<taglist> + +<tag><c>{'Origin-Host', DiameterIdentity()}</c></tag> +<item> +<p> +Value of the Origin-Host AVP in outgoing messages.</p> +</item> + +<tag><c>{'Origin-Realm', DiameterIdentity()}</c></tag> +<item> +<p> +Value of the Origin-Realm AVP in outgoing messages.</p> +</item> + +<tag><c>{'Host-IP-Address', [Address()]}</c></tag> +<item> +<p> +Values of Host-IP-Address AVPs. +Optional.</p> + +<p> +The list of addresses is available to the start function of a +transport module, which either uses them as is or returns a new list +(typically as configured as <c>transport_config()</c> on the +transport module in question) in order for the correct list of +addresses to be sent in capabilities exchange messages.</p> +</item> + +<tag><c>{'Vendor-Id', Unsigned32()}</c></tag> +<item> +<p> +Value of the Vendor-Id AVP sent in an outgoing capabilities +exchange message.</p> +</item> + +<tag><c>{'Product-Name', UTF8String()}</c></tag> +<item> +<p> +Value of the Product-Name AVP sent in an outgoing capabilities +exchange message.</p> +</item> + +<tag><c>{'Origin-State-Id', Unsigned32()}</c></tag> +<item> +<p> +Value of Origin-State-Id to be included in outgoing messages sent by +diameter itself. +In particular, the AVP will be included in CER/CEA and DWR/DWA messages. +Optional.</p> + +<p> +Setting a value of <c>0</c> (zero) is equivalent to not setting a +value as documented in RFC 3588. +The function <seealso +marker="#origin_state_id">origin_state_id/0</seealso> +can be used as to retrieve a value that is set when the diameter +application is started.</p> +</item> + +<tag><c>{'Supported-Vendor-Id', [Unsigned32()]}</c></tag> +<item> +<p> +Values of Supported-Vendor-Id AVPs sent in an outgoing +capabilities exchange message. +Optional, defaults to the empty list.</p> +</item> + +<tag><c>{'Auth-Application-Id', [Unsigned32()]}</c></tag> +<item> +<p> +Values of Auth-Application-Id AVPs sent in an outgoing +capabilities exchange message. +Optional, defaults to the empty list.</p> +</item> + +<tag><c>{'Acct-Application-Id', [Unsigned32()]}</c></tag> +<item> +<p> +Values of Acct-Application-Id AVPs sent in an outgoing +capabilities exchange message. +Optional, defaults to the empty list.</p> +</item> + +<tag><c>{'Vendor-Specific-Application-Id', [Grouped()]}</c></tag> +<item> +<p> +Values of Vendor-Specific-Application-Id AVPs sent in +an outgoing capabilities exchange message. +Optional, defaults to the empty list.</p> +</item> + +<tag><c>{'Firmware-Revision', Unsigned32()}</c></tag> +<item> +<p> +Value of the Firmware-Revision AVP sent in an outgoing capabilities +exchange message. +Optional.</p> +</item> + +</taglist> + +<p> +Note that each tuple communicates one or more AVP values. +It is an error to specify duplicate tuples.</p> + +<marker id="evaluable"/> +</item> + +<tag><c>evaluable() = {M,F,A} | fun() | [evaluable() | A]</c></tag> +<item> +<p> +An expression that can be evaluated as a function in the following +sense.</p> + +<code> +eval([{M,F,A} | T]) -> + apply(M, F, T ++ A); +eval([[F|A] | T]) -> + eval([F | T ++ A]); +eval([F|A]) -> + apply(F, A); +eval(F) -> + eval([F]). +</code> + +<p> +Evaluating an evaluable() <c>E</c> on an argument list <c>A</c> +is meant in the sense of <c>eval([E|A])</c>.</p> + +<p> +Beware of using local funs (that is, fun expressions not of the +form <c>fun Module:Name/Arity</c>) in situations in which the fun is +not short-lived and code is to be upgraded at runtime since any +processes retaining such a fun will have a reference to old code.</p> + +<marker id="peer_filter"/> +</item> + +<tag><c>peer_filter() = term()</c></tag> +<item> +<p> +A filter passed to <seealso marker="#call">call/4</seealso> +in order to select candidate peers for a +<seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> +callback. +Has one of the following types.</p> + +<taglist> + +<tag><c>none</c></tag> +<item> +<p> +Matches any peer. +This is a convenience that provides a filter equivalent to no +filter at all.</p> +</item> + +<tag><c>host</c></tag> +<item> +<p> +Matches only those peers whose <c>Origin-Host</c> has the same value +as <c>Destination-Host</c> in the outgoing request in question, +or any peer if the request does not contain +a <c>Destination-Host</c> AVP.</p> +</item> + +<tag><c>realm</c></tag> +<item> +<p> +Matches only those peers whose <c>Origin-Realm</c> has the same value +as <c>Destination-Realm</c> in the outgoing request in question, +or any peer if the request does not contain +a <c>Destination-Realm</c> AVP.</p> +</item> + +<tag><c>{host, any|DiameterIdentity()}</c></tag> +<item> +<p> +Matches only those peers whose <c>Origin-Host</c> has the +specified value, or all peers if the atom <c>any</c>.</p> +</item> + +<tag><c>{realm, any|DiameterIdentity()</c></tag> +<item> +<p> +Matches only those peers whose <c>Origin-Realm</c> has the +value, or all peers if the atom <c>any</c>.</p> +</item> + +<tag><c>{eval, evaluable()}</c></tag> +<item> +<p> +Matches only those peers for which the specified evaluable() returns +<c>true</c> on the connection's <c>diameter_caps</c> record. +Any other return value or exception is equivalent to <c>false</c>.</p> +</item> + +<tag><c>{neg, peer_filter()}</c></tag> +<item> +<p> +Matches only those peers not matched by the specified filter.</p> +</item> + +<tag><c>{all, [peer_filter()]}</c></tag> +<item> +<p> +Matches only those peers matched by each filter of the specified list.</p> +</item> + +<tag><c>{any, [peer_filter()]}</c></tag> +<item> +<p> +Matches only those peers matched by at least one filter of the +specified list.</p> +</item> + +</taglist> + +<p> +Note that the <c>host</c> and <c>realm</c> filters examine the +outgoing request as passed to <seealso marker="#call">call/4</seealso>, +assuming that this is a record- or list-valued message() as documented +in <seealso marker="diameter_app">diameter_app(3)</seealso>, and that +the message contains at most one of each AVP. +If this is not the case then the <c>{host|realm, DiameterIdentity()}</c> +filters must be used to achieve the desired result. +Note also that an empty host/realm (which should not be typical) +is equivalent to an unspecified one for the purposes of filtering.</p> + +<p> +An invalid filter is equivalent to <c>{any, []}</c>, a filter +that matches no peer.</p> + +<marker id="service_event"/> +</item> + +<tag><c>service_event() = #diameter_event{}</c></tag> +<item> +<p> +Event message sent to processes that have subscribed using <seealso +marker="#subscribe">subscribe/1</seealso>.</p> + +<p> +The <c>info</c> field of the event record can be one of the +following.</p> + +<taglist> + +<tag><c>{up, Ref, Peer, Config, Pkt}</c></tag> +<tag><c>{up, Ref, Peer, Config}</c></tag> +<tag><c>{down, Ref, Peer, Config}</c></tag> +<item> +<code> +Ref = transport_ref() +Peer = diameter_app:peer() +Config = {connect|listen, [transport_opt()]} +Pkt = #diameter_packet{} +</code> + +<p> +Reports that the RFC 3539 watchdog state machine has +transitioned into (<c>up</c>) or out of (<c>down</c>) the open +state. +If a <c>diameter_packet</c> record is present in an <c>up</c> tuple +then there has been an exchange of capabilities exchange messages and +the record contains the received CER or CEA, otherwise the +connection has reestablished without the loss or transport +connectivity.</p> + +<p> +Note that a single up/down event for a given peer corresponds to +as many peer_up/down callbacks as there are Diameter +applications shared by the peer, as determined during capablilities +exchange. +That is, the event communicates connectivity with the +peer as a whole while the callbacks communicate connectivity with +respect to individual Diameter applications.</p> +</item> + +<tag><c>{reconnect, Ref, Opts}</c></tag> +<item> +<code> +Ref = transport_ref() +Opts = [transport_opt()] +</code> + +<p> +A connecting transport is attempting to establish/reestablish a +transport connection with a peer following <c>reconnect_timer</c> or +<c>watchdog_timer</c> expiry.</p> +</item> + +</taglist> + +<p> +For forward compatibility, a subscriber should be prepared to receive +<c>diameter_event.info</c> of forms other than those documented +above.</p> + +<marker id="service_name"/> +</item> + +<tag><c>service_name() = term()</c></tag> +<item> +<p> +The name of a service as passed to <seealso +marker="#start_service">start_service/2</seealso> and with which the +service is identified. +There can be at most one service with a given name on a given node. +Note that <c>erlang:make_ref/0</c> can be used to generate a service name +that is somewhat unique.</p> + +<marker id="service_opt"/> +</item> + +<tag><c>service_opt()</c></tag> +<item> +<p> +Options accepted by <seealso +marker="#start_service">start_service/2</seealso>. +Can be any <c>capability()</c> tuple as +well as the following.</p> + +<taglist> + +<tag><c>{application, [application_opt()]}</c></tag> +<item> +<p> +Defines a Diameter application supported by the service.</p> + +<p> +A service must define one application for each Diameter application it +intends to support. +For an outgoing Diameter request, the application is specified by +passing the desired application's <c>application_alias()</c> to +<seealso marker="#call">call/4</seealso>, while for an +incoming request the application identifier in the message +header determines the application (and callback module), the +application identifier being specified in the <seealso +marker="diameter_dict">dictionary</seealso> file defining the +application.</p> +</item> + +</taglist> + +<marker id="transport_opt"/> +</item> + +<tag><c>transport_opt()</c></tag> +<item> +<p> +Options accepted by <seealso +marker="#add_transport">add_transport/2</seealso>.</p> + +<taglist> +<tag><c>{transport_module, atom()}</c></tag> +<item> +<p> +A module implementing a transport process as defined in <seealso +marker="diameter_transport">diameter_transport(3)</seealso>. +Defaults to <c>diameter_tcp</c> if unspecified.</p> + +<p> +The interface required of a transport module is documented in <seealso +marker="diameter_transport">diameter_transport(3)</seealso>.</p> +</item> + +<tag><c>{transport_config, term()}</c></tag> +<item> +<p> +A term passed as the third argument to the <seealso +marker="diameter_transport#start">start/3</seealso> function of +the relevant <c>transport_module</c> in order to start a transport process. +Defaults to the empty list if unspecified.</p> +</item> + +<tag><c>{applications, [application_alias()]}</c></tag> +<item> +<p> +The list of Diameter applications to which usage of the transport +should be restricted. +Defaults to all applications configured on the service +in question.</p> +</item> + +<tag><c>{capabilities, [capability()]}</c></tag> +<item> +<p> +AVP's used to construct outgoing CER/CEA messages. +Any AVP specified takes precedence over a corresponding value specified +for the service in question.</p> +</item> + +<tag><c>{watchdog_timer, TwInit}</c></tag> +<item> +<code> +TwInit = Unsigned32() + | {M,F,A} +</code> + +<p> +The RFC 3539 watchdog timer. +An integer value is interpreted as the RFC's TwInit in milliseconds, +a jitter of ± 2 seconds being added at each rearming of the +timer to compute the RFC's Tw. +An MFA is expected to return the RFC's Tw directly, with jitter +applied, allowing the jitter calculation to be performed by +the callback.</p> + +<p> +An integer value must be at least 6000 as required by RFC 3539. +Defaults to 30000 if unspecified.</p> +</item> + +<tag><c>{reconnect_timer, Tc}</c></tag> +<item> +<code> +Tc = Unsigned32() +</code> + +<p> +For a connecting transport, the RFC 3588 Tc timer, in milliseconds. +Note that this timer determines the frequency with which the transport +will attempt to establish a connection with its peer only <em>before</em> +an initial connection is established: once there is an initial +connection it's watchdog_timer that determines the frequency of +reconnection attempts, as required by RFC 3539.</p> + +<p> +For a listening transport, the timer specifies the time after which a +previously connected peer will be forgotten: a connection after this time is +regarded as an initial connection rather than a reestablishment, +causing the RFC 3539 state machine to pass to state OPEN rather than +REOPEN. +Note that these semantics are not goverened by the RFC and +that a listening transport's reconnect_timer should be greater than its +peers's Tc plus jitter.</p> + +<p> +Defaults to 30000 for a connecting transport and 60000 for a listening +transport.</p> +</item> + +</taglist> + +<p> +Unrecognized options are silently ignored but are returned unmodified +by <seealso +marker="#service_info">service_info/2</seealso> and can be referred to +in predicate functions passed to <seealso +marker="#remove_transport">remove_transport/2</seealso>.</p> + +</item> + +</taglist> + +</section> + +<marker id="add_transport"/> +<funcs> + +<!-- ===================================================================== --> + +<func> +<name>add_transport(SvcName, {connect|listen, Options}) + -> {ok, Ref} | {error, Reason}</name> +<fsummary>Add transport capability to a service.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Options = [transport_opt()]</v> +<v>Ref = ref()</v> +<v>Reason = term()</v> +</type> +<desc> +<p> +Add transport capability to a service.</p> + +<p> +The service will start a transport process(es) in order to establish a +connection with the peer, either by connecting to the peer +(<c>connect</c>) or by accepting incoming connection requests +(<c>listen</c>). +A connecting transport establishes transport connections with at most +one peer, an listening transport potentially with many.</p> + +<p> +The diameter application takes responsibility for exchanging +CER/CEA with the peer. +Upon successful completion of capabilities exchange the service +calls each relevant application module's <seealso +marker="diameter_app#peer_up">peer_up/3</seealso> callback +after which the caller can exchange Diameter messages with the peer over +the transport. +In addition to CER/CEA, the service takes responsibility for the +handling of DWR/DWA and required by RFC 3539 as well as for DPR/DPA.</p> + +<p> +The returned reference uniquely identifies the transport within the +scope of the service. +Note that the function returns before a transport connection has been +established. +It is not an error to add a transport to a service that has not yet +been configured: a service can be started after configuring +transports.</p> + +<marker id="call"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>call(SvcName, App, Request, Options) -> ok | Answer | {error, Reason}</name> +<fsummary>Send a Diameter request message.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>App = application_alias()</v> +<v>Request = diameter_app:message() | term()</v> +<v>Answer = term()</v> +<v>Options = [call_opt()]</v> +</type> +<desc> +<p> +Send a Diameter request message and possibly return the answer or error.</p> + +<p> +<c>App</c> identifies the Diameter application in which the request is +defined and callbacks to the corresponding callback module +will follow as described below and in <seealso +marker="diameter_app">diameter_app(3)</seealso>. +Unless the <c>detach</c> option has been specified to cause an earlier +return, the call returns either when an answer message is received +from the peer or an error occurs. +In the case of an answer, the return value is as returned by a +<seealso +marker="diameter_app#handle_answer">handle_answer/4</seealso> +callback. +In the case of an error, whether or not the error is returned directly +by diameter or from a <seealso +marker="diameter_app#handle_error">handle_error/4</seealso> +callback depends on whether or not the outgoing request is +successfully encoded for transmission from the peer, the cases being +documented below.</p> + +<p> +If there are no suitable peers, or if +<seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> +rejects them by returning 'false', then <c>{error, no_connection}</c> +is returned. +Otherwise <seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> +is followed by a +<seealso +marker="diameter_app#prepare_request">prepare_request/3</seealso> +callback, the message is encoded and sent.</p> + +<p> +There are several error cases which may prevent an +answer from being received and passed to a +<seealso marker="diameter_app#handle_answer">handle_answer/4</seealso> +callback:</p> + +<list> + +<item> +<p> +If the initial encode of the outgoing request +fails, then the request process fails and <c>{error, encode}</c> +is returned.</p> +</item> + +<item> +<p> +If the request is successfully encoded and sent but +the answer times out then a +<seealso marker="diameter_app#handle_error">handle_error/4</seealso> +callback takes place with <c>Reason = timeout</c>.</p> +</item> + +<item> +<p> +If the request is successfully encoded and sent but the service in +question is stopped before an answer is received then a +<seealso marker="diameter_app#handle_error">handle_error/4</seealso> +callback takes place <c>Reason = cancel</c>.</p> +</item> + +<item> +<p> +If the transport connection with the peer goes down after the request +has been sent but before an answer has been received then an attempt +is made to resend the request to an alternate peer. +If no such peer is available, or if the subsequent +<seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> +callback rejects the candidates, then a +<seealso marker="diameter_app#handle_error">handle_error/4</seealso> +callback takes place with <c>Reason = failover</c>. +If a peer is selected then a +<seealso +marker="diameter_app#prepare_retransmit">prepare_retransmit/3</seealso> +callback takes place, after which the semantics are the same as +following an initial +<seealso marker="diameter_app#prepare_request"> +prepare_request/3</seealso> +callback.</p> +</item> + +<item> +<p> +If an encode error takes place during +retransmission then the request process fails and +<c>{error, failure}</c> is returned.</p> +</item> + +<item> +<p> +If an application callback made in processing the request fails +(pick_peer, prepare_request, prepare_retransmit, +handle_answer or handle_error) then either +<c>{error, encode}</c> or <c>{error, failure}</c> +is returned depending on whether or not there has been an +attempt to send the request over the transport.</p> +</item> + +</list> + +<p> +Note that <c>{error, encode}</c> is the only return value which +guarantees that the request has <em>not</em> been sent over the +transport.</p> + +<marker id="origin_state_id"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>origin_state_id() -> Unsigned32()</name> +<fsummary>Returns a reasonable Origin-State-Id.</fsummary> +<desc> +<p> +Return a reasonable value for use as Origin-State-Id in +outgoing messages.</p> + +<p> +The value returned is the number of seconds since 19680120T031408Z, +the first value that can be encoded as a Diameter Time(), +at the time the diameter application was started.</p> + +<marker id="remove_transport"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>remove_transport(SvcName, Pred) -> ok</name> +<fsummary>Remove previously added transports.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Pred = Fun | MFA | ref() | list() | true | false</v> +<v></v> +<v>Fun = fun((reference(), connect|listen, list()) -> boolean())</v> +<v> | fun((reference(), list()) -> boolean())</v> +<v> | fun((list()) -> boolean())</v> +<v>MFA = {atom(), atom(), list()}</v> +</type> +<desc> +<p> +Remove previously added transports.</p> + +<p> +<c>Pred</c> determines which transports to remove. +An arity-3-valued <c>Pred</c> removes all transports for which +<c>Pred(Ref, Type, Opts)</c> returns <c>true</c>, where <c>Type</c> and +<c>Opts</c> are as passed to <seealso +marker="#add_transport">add_transport/2</seealso> and <c>Ref</c> is +as returned by the corresponding call. +The remaining forms are equivalent to an arity-3 fun as follows.</p> + +<code> +Pred = fun(reference(), list()): fun(Ref, _, Opts) -> Pred(Ref, Opts) end +Pred = fun(list()): fun(_, _, Opts) -> Pred(Opts) end +Pred = reference(): fun(Ref, _, _) -> Pred == Ref end +Pred = list(): fun(_, _, Opts) -> [] == Pred -- Opts end +Pred = true: fun(_, _, _) -> true end +Pred = false: fun(_, _, _) -> false end +Pred = {M,F,A}: fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end +</code> + +<p> +Removing a transport causes all associated transport connections to +be broken. +A base application DPR message with +Disconnect-Cause <c>DO_NOT_WANT_TO_TALK_TO_YOU</c> will be sent +to each connected peer before disassociating the transport configuration +from the service and terminating the transport upon reception of +DPA or timeout.</p> + +<!-- TODO: document the timeout value, possibly make configurable. --> + +<marker id="service_info"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>service_info(SvcName, Item) -> Value</name> +<fsummary>Return specific information about a started service.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Value = term()</v> +</type> +<desc> +<p> +Return information about a started service.</p> + +<marker id="services"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>services() -> [SvcName]</name> +<fsummary>Return the list of started services.</fsummary> +<type> +<v>SvcName = service_name()</v> +</type> +<desc> +<p> +Return the list of started services.</p> + +<marker id="session_id"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>session_id(Ident) -> OctetString()</name> +<fsummary>Return a value for a Session-Id AVP.</fsummary> +<type> +<v>Ident = DiameterIdentity()</v> +</type> +<desc> +<p> +Return a value for a Session-Id AVP.</p> + +<p> +The value has the form required by section 8.8 of RFC 3588. +Ident should be the Origin-Host of the peer from which +the message containing the returned value will be sent.</p> + +<marker id="start"/> +</desc> +</func> + +<!-- ===================================================================== --> +<func> +<name>start() -> ok | {error, Reason}</name> +<fsummary>Start the diameter application.</fsummary> +<desc> +<p> +Start the diameter application.</p> + +<p> +The diameter application must be started before starting a service. +In a production system this will typically be accomplished by a boot +file, not by calling <c>start/0</c> explicitly.</p> + +<marker id="start_service"/> +</desc> +</func> + +<!-- ===================================================================== --> +<func> +<name>start_service(SvcName, Options) -> ok | {error, Reason}</name> +<fsummary>Start a Diameter service.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Options = [service_opt()]</v> +<v>Reason = term()</v> +</type> +<desc> +<p> +Start a diameter service.</p> + +<p> +A service defines a locally-implemented Diameter peer, specifying the +capabilities of the peer to be used during capabilities exchange and +the Diameter applications that it supports. +Transports are added to a service using <seealso +marker="#add_transport">add_transport/2</seealso>.</p> + +<marker id="stop_service"/> +</desc> +</func> + +<!-- ===================================================================== --> +<func> +<name>stop() -> ok | {error, Reason}</name> +<fsummary>Stop the diameter application.</fsummary> +<desc> +<p> +Stop the diameter application.</p> + +<p> +</p> + +<marker id="stop_service"/> +</desc> +</func> + +<!-- ===================================================================== --> +<func> +<name>stop_service(SvcName) -> ok | {error, Reason}</name> +<fsummary>Stop a Diameter service.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Reason = term()</v> +</type> +<desc> +<p> +Stop a diameter service.</p> + +<marker id="subscribe"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>subscribe(SvcName) -> true</name> +<fsummary>Subscribe to event messages.</fsummary> +<type> +<v>SvcName = service_name()</v> +</type> +<desc> +<p> +Subscribe to <c>service_event()</c> messages from a service.</p> + +<p> +It is not an error to subscribe to events from a service +that does not yet exist.</p> + +<marker id="unsubscribe"/> +</desc> +</func> + +<!-- ===================================================================== --> + +<func> +<name>unsubscribe(SvcName) -> true</name> +<fsummary>Unsubscribe to event messages.</fsummary> +<type> +<v>SvcName = service_name()</v> +</type> +<desc> +<p> +Unsubscribe to event messages from a service.</p> + +</desc> +</func> + +</funcs> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> +<section> +<title>SEE ALSO</title> + +<p> +<seealso marker="diameter_app">diameter_app(3)</seealso>, +<seealso marker="diameter_transport">diameter_transport(3)</seealso>, +<seealso marker="diameter_dict">diameter_dict(4)</seealso></p> + +</section> + +</erlref> diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml new file mode 100644 index 0000000000..a9ae0ebbec --- /dev/null +++ b/lib/diameter/doc/src/diameter_app.xml @@ -0,0 +1,615 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> +<header> + +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>diameter_app(3)</title> +<prepared>Anders Svensson</prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev>%REV%</rev> +<file>diameter_app.xml</file> + +</header> + +<module>diameter_app</module> +<modulesummary> +Callback module of a Diameter application.</modulesummary> + +<description> + +<p> +A diameter service as started by <seealso +marker="diameter#start_service">diameter:start_service/2</seealso> +configures one of more Diameter applications, each of whose +configuration specifies a callback that handles messages specific to +its application. +The messages and AVPs of the Diameter application are defined in a +dictionary file whose format is documented in +<seealso marker="diameter_dict">diameter_dict(4)</seealso> +while the callback module is documented here. +The callback module implements the Diameter application-specific +functionality of a service.</p> + +<p> +A callback module must export all of the functions documented below. +The functions themselves are of three distinct flavours:</p> + +<list> +<item> +<p> +<seealso marker="#peer_up">peer_up/3</seealso> and +<seealso marker="#peer_down">peer_down/3</seealso> signal the +attainment or loss of connectivity with a Diameter peer.</p> +</item> + +<item> +<p> +<seealso marker="#pick_peer">pick_peer/4</seealso>, +<seealso marker="#prepare_request">prepare_request/3</seealso>, +<seealso marker="#prepare_retransmit">prepare_retransmit/3</seealso>, +<seealso marker="#handle_answer">handle_answer/4</seealso> +and <seealso marker="#handle_error">handle_error/4</seealso> are (or may +be) called as a consequence of a call to <seealso +marker="diameter#call">diameter:call/4</seealso> to send an outgoing +Diameter request message.</p> +</item> + +<item> +<p> +<seealso marker="#handle_request">handle_request/3</seealso> +is called in response to an incoming Diameter request message.</p> +</item> + +</list> + +</description> + +<note> +<p> +The arities given for the the callback functions here assume no extra +arguments. +All functions will also be passed any extra arguments configured with +the callback module itself when calling <seealso +marker="diameter#start_service">diameter:start_service/2</seealso> +and, for the call-specific callbacks, any extra arguments passed to +<seealso marker="diameter#call">diameter:call/4</seealso>.</p> +</note> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<section> +<title>DATA TYPES</title> + +<taglist> + +<tag><c>capabilities() = #diameter_caps{}</c></tag> +<item> +<p> +A record containing the identities of +the local and remote Diameter peers having an established transport +connection, as well as the capabilities as +determined by capabilities exchange. +Each field of the record is a 2-tuple consisting of +values for the (local) host and (remote) peer. +Optional or possibly multiple values are encoded as lists of values, +mandatory values as the bare value.</p> +</item> + +<tag><c>message() = record() | list()</c></tag> +<item> +<p> +The representation of a Diameter message as passed to +<seealso marker="diameter#call">diameter:call/4</seealso>. +The record representation is as outlined in +<seealso +marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>: +a message as defined in a dictionary file is encoded as a record with +one field for each component AVP. +Equivalently, a message can also be encoded as a list whose head is +the atom-valued message name (the record name minus any +prefix specified in the relevant dictionary file) and whose tail is a +list of <c>{FieldName, FieldValue}</c> pairs.</p> + +<p> +A third representation allows a message to be specified as a list +whose head is a <c>diameter_header</c> record and whose tail is a list +of <c>diameter_avp</c> records. +This representation is used by diameter itself when relaying requests +as directed by the return value of a +<seealso marker="#handle_request">handle_request/3</seealso> +callback. +It differs from the other other two in that it bypasses the checks for +messages that do not agree with their definitions in the dictionary in +question (since relays agents must handle arbitrary request): messages +are sent exactly as specified.</p> + +</item> + +<tag><c>packet() = #diameter_packet{}</c></tag> +<item> +<p> +A container for incoming and outgoing Diameters message that's passed +through encode/decode and transport. +Fields of a packet() record should not be set in return values except +as documented.</p> +</item> + +<tag><c>peer_ref() = term()</c></tag> +<item> +<p> +A term identifying a transport connection with a Diameter peer. +Should be treated opaquely.</p> +</item> + +<tag><c>peer() = {peer_ref(), capabilities()}</c></tag> +<item> +<p> +A tuple representing a Diameter peer connection.</p> +</item> + +<tag><c>service_name() = term()</c></tag> +<item> +<p> +The service supporting the Diameter application. +Specified to <seealso +marker="diameter#start_service">diameter:start_service/2</seealso> +when starting the service.</p> +</item> + +<tag><c>state() = term()</c></tag> +<item> +<p> +The state maintained by the application callback functions +<seealso marker="#peer_up">peer_up/3</seealso>, +<seealso marker="#peer_down">peer_down/3</seealso> and (optionally) +<seealso marker="#pick_peer">pick_peer/4</seealso>. +The initial state is configured in the call to +<seealso +marker="diameter#start_service">diameter:start_service/2</seealso> +that configures the application on a service. +Callback functions returning a state are evaluated in a common +service-specific process while +those not returning state are evaluated in a request-specific +process.</p> +</item> + +</taglist> + +<marker id="peer_up"/> +</section> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<funcs> + +<func> +<name>Mod:peer_up(SvcName, Peer, State) -> NewState</name> +<fsummary>Invoked when a transport connection has been established</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Peer = peer()</v> +<v>State = NewState = state()</v> +</type> +<desc> +<p> +Invoked when a transport connection has been established +and a successful capabilities exchange has indicated that the peer +supports the Diameter application of the application on which +the callback module in question has been configured.</p> + +<marker id="peer_down"/> +</desc> +</func> + +<func> +<name>Mod:peer_down(SvcName, Peer, State) -> NewState</name> +<fsummary>Invoked when a transport connection has been lost.</fsummary> +<type> +<v>SvcName = service_name()</v> +<v>Peer = peer()</v> +<v>State = NewState = state()</v> +</type> +<desc> +<p> +Invoked when a transport connection has been lost following a previous +call to <seealso marker="#peer_up">peer_up/3</seealso>.</p> + +<marker id="pick_peer"/> +</desc> +</func> + +<func> +<name>Mod:pick_peer(Candidates, Reserved, SvcName, State) + -> {ok, Peer} | {Peer, NewState} | false</name> +<fsummary>Select a target peer for an outgoing request.</fsummary> +<type> +<v>Candidates = [peer()]</v> +<v>Peer = peer() | false</v> +<v>SvcName = service_name()</v> +<v>State = NewState = state()</v> +</type> +<desc> +<p> +Invoked as a consequence of a call to <seealso +marker="diameter#call">diameter:call/4</seealso> to select a destination +peer for an outgoing request, the return value indicating the selected peer. +A new application state can also be returned but only if the Diameter +application in question was +configured with the option <c>call_mutates_state</c> set to +<c>true</c>, as documented for <seealso +marker="diameter#start_service">diameter:start_service/2</seealso>.</p> + +<p> +The candidate peers list will only include those +which are selected by any <c>filter</c> option specified in the call to +<seealso marker="diameter#call">diameter:call/4</seealso>, and only +those which have indicated support for the Diameter application in +question. +The order of the elements is unspecified except that any +peers whose Origin-Host and Origin-Realm matches that of the +outgoing request (in the sense of a <c>{filter, {all, [host, realm]}}</c> +option to <seealso marker="diameter#call">diameter:call/4</seealso>) +will be placed at the head of the list.</p> + +<p> +The return values <c>false</c> and <c>{false, State}</c> are +equivalent when callback state is mutable, as are +<c>{ok, Peer}</c> and <c>{Peer, State}</c>. +Returning a peer as <c>false</c> causes <c>{error, no_connection}</c> +to be returned from <seealso marker="diameter#call">diameter:call/4</seealso>. +Returning a peer() from an initial pick_peer/4 callback will result in a +<seealso marker="#prepare_request">prepare_request/3</seealso> callback +followed by either <seealso +marker="#handle_answer">handle_answer/4</seealso> +or <seealso marker="#handle_error">handle_error/4</seealso> depending +on whether or not an answer message is received from the peer. +If transport with the peer is lost before this then a new <seealso +marker="#pick_peer">pick_peer/4</seealso> callback takes place to +select an alternate peer.</p> + +<p> +Note that there is no guarantee that a <seealso +marker="#pick_peer">pick_peer/4</seealso> callback to select +an alternate peer will be followed by any additional callbacks, only +that the initial <seealso +marker="#pick_peer">pick_peer/4</seealso> will be, since a +retransmission to an alternate peer is abandoned if an answer is +received from a previously selected peer.</p> + +<marker id="prepare_request"/> +</desc> + +</func> + +<func> +<name>Mod:prepare_request(Packet, SvcName, Peer) -> Action</name> +<fsummary>Return a request for encoding and transport.</fsummary> +<type> +<v>Packet = packet()</v> +<v>SvcName = service_name()</v> +<v>Peer = peer()</v> +<v>Action = {send, packet() | message()} | {discard, Reason} | discard</v> +</type> +<desc> +<p> +Invoked to return a request for encoding and transport. +Allows the sender to access the selected peer's capabilities +in order to set (for example) <c>Destination-Host</c> and/or +<c>Destination-Realm</c> in the outgoing request, although the +callback need not be limited to this usage. +Many implementations may simply want to return <c>{send, Packet}</c></p> + +<p> +A returned packet() should set the request to be encoded in its +<c>msg</c> field and can set the <c>transport_data</c> field in order +to pass information to the transport module. +Extra arguments passed to <seealso +marker="diameter#call">diameter:call/4</seealso> can be used to +communicate transport data to the callback. +A returned packet() can also set the <c>header</c> field to a +<c>diameter_header</c> record in order to specify values that should +be preserved in the outgoing request, although this should typically +not be necessary and allows the callback to set header values +inappropriately. +A returned <c>length</c>, <c>cmd_code</c> or <c>application_id</c> is +ignored.</p> + +<p> +Returning <c>{discard, Reason}</c> causes the request to be aborted +and the <seealso +marker="diameter#call">diameter:call/4</seealso> for which the +callback has taken place to return <c>{error, Reason}</c>. +Returning <c>discard</c> is equivalent to returning <c>{discard, +discarded}</c>.</p> + +<marker id="prepare_retransmit"/> +</desc> +</func> + +<func> +<name>Mod:prepare_retransmit(Packet, SvcName, Peer) -> Result</name> +<fsummary>Return a request for encoding and retransmission.</fsummary> +<type> +<v>Packet = packet()</v> +<v>SvcName = service_name()</v> +<v>Peer = peer()</v> +<v>Result = {send, packet() | message()} | {discard, Reason} | discard</v> +</type> +<desc> +<p> +Invoked to return a request for encoding and retransmission. +Has the same role as <seealso +marker="#prepare_request">prepare_request/3</seealso> in the case that +a peer connection is lost an an alternate peer selected but the +argument packet() is as returned by the initial +<c>prepare_request/3</c>.</p> + +<p> +Returning <c>{discard, Reason}</c> causes the request to be aborted +and a <seealso +marker="#handle_error">handle_error/4</seealso> callback to +take place with <c>Reason</c> as initial argument. +Returning <c>discard</c> is equivalent to returning <c>{discard, +discarded}</c>.</p> + +<marker id="handle_answer"/> +</desc> +</func> + +<func> +<name>Mod:handle_answer(Packet, Request, SvcName, Peer) -> Result</name> +<fsummary>Receive an answer message from a peer.</fsummary> +<type> +<v>Packet = packet()</v> +<v>Request = message()</v> +<v>SvcName = service_name()</v> +<v>Peer = peer()</v> +<v>Result = term()</v> +</type> +<desc> +<p> +Invoked when an answer message is received from a peer. +The return value is returned from the call to <seealso +marker="diameter#call">diameter:call/4</seealso> for which the +callback takes place unless the <c>detach</c> option was +specified.</p> + +<p> +The decoded answer record is in the <c>msg</c> field of the argument +packet(), +the undecoded binary in the <c>packet</c> field. +<c>Request</c> is the outgoing request message as was returned from +<seealso marker="#prepare_request">prepare_request/3</seealso> or +<seealso marker="#prepare_retransmit">prepare_retransmit/3</seealso> +before the request was passed to the transport.</p> + +<p> +For any given call to <seealso +marker="diameter#call">diameter:call/4</seealso> there is at most one +call to the handle_answer callback of the application in question: any +duplicate answer (due to retransmission or otherwise) is discarded. +Similarly, only one of <c>handle_answer/4</c> or <c>handle_error/4</c> is +called for any given request.</p> + +<p> +By default, an incoming answer message that cannot be successfully +decoded causes the request process in question to fail, causing the +relevant call to <seealso +marker="diameter#call">diameter:call/4</seealso> +to return <c>{error, failure} (unless the <c>detach</c> option was +specified)</c>. +In particular, there is no <c>handle_error/4</c> callback in this +case. +Application configuration may change this behaviour as described for +<seealso +marker="diameter#start_service">diameter:start_service/2</seealso>.</p> + +<marker id="handle_error"/> +</desc> +</func> + +<func> +<name>Mod:handle_error(Reason, Request, SvcName, Peer) -> Result</name> +<fsummary>Return an error from a outgoing request.</fsummary> +<type> +<v>Reason = timeout | failover | term()</v> +<v>Request = message()</v> +<v>SvcName = service_name()</v> +<v>Peer = peer()</v> +<v>Result = term()</v> +</type> +<desc> +<p> +Invoked when an error occurs before an answer message is received from +a peer in response to an outgoing request. +The return value is returned from the call to <seealso +marker="diameter#call">diameter:call/4</seealso> for which the +callback takes place (unless the <c>detach</c> option was +specified).</p> + +<p> +Reason <c>timeout</c> indicates that an answer message has not been +received within the required time. +Reason <c>failover</c> indicates +that the transport connection to the peer to which the request has +been sent has been lost but that not alternate node was available, +possibly because a <seealso marker="#pick_peer">pick_peer/4</seealso> +callback returned false.</p> + +<marker id="handle_request"/> +</desc> +</func> + +<func> +<name>Mod:handle_request(Packet, SvcName, Peer) -> Action</name> +<fsummary>Receive an incoming request.</fsummary> +<type> +<v>Packet = packet()</v> +<v>SvcName = term()</v> +<v>Peer = peer()</v> +<v>Action = Reply | {relay, Opts} | discard | {eval, Action, PostF}</v> +<v>Reply = {reply, message()} + | {protocol_error, 3000..3999}</v> +<v>Opts = diameter:call_opts()</v> +<v>PostF = diameter:evaluable()</v> +</type> +<desc> +<p> +Invoked when a request message is received from a peer. +The application in which the callback takes place (that is, the +callback module as configured with <seealso +marker="diameter#start_service">diameter:start_service/2</seealso>) +is determined by the Application Identifier in the header of the +incoming request message, the selected module being the one +whose corresponding <seealso +marker="diameter_dict#MESSAGE_RECORDS">dictionary</seealso> declares +itself as defining either the application in question or the Relay +application.</p> + +<p> +The argument packet() has the following signature.</p> + +<code> +#diameter_packet{header = #diameter_header{}, + avps = [#diameter_avp{}], + msg = record() | undefined, + errors = ['Unsigned32'() | {'Unsigned32'(), #diameter_avp{}}], + bin = binary(), + transport_data = term()} +</code> + +<p> +The <c>msg</c> field will be <c>undefined</c> only in case the request has +been received in the relay application. +Otherwise it contains the record representing the request as outlined +in <seealso +marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>.</p> + +<p> +The <c>errors</c> field specifies any Result-Code's identifying errors +that were encountered in decoding the request. +In this case diameter will set both Result-Code and +Failed-AVP AVP's in a returned +answer message() before sending it to the peer: +the returned message() need only set any other required AVP's. +Note that the errors detected by diameter are all of the 5xxx series +(Permanent Failures). +The <c>errors</c> list is empty if the request has been received in +the relay application.</p> + +<p> +The <c>transport_data</c> field contains an arbitrary term passed into +diameter from the transport module in question, or the atom +<c>undefined</c> if the transport specified no data. +The term is preserved in the packet() containing any answer message +sent back to the transport process unless another value is explicitly +specified.</p> + +<p> +The semantics of each of the possible return values are as follows.</p> + +<taglist> + +<tag><c>{reply, message()}</c></tag> +<item> +<p> +Send the specified answer message to the peer.</p> +</item> + +<tag><c>{protocol_error, 3000..3999}</c></tag> +<item> +<p> +Send an answer message to the peer containing the specified +protocol error. +Equivalent to</p> +<code> +{reply, ['answer-message' | Avps] +</code> +<p> +where <c>Avps</c> sets the Origin-Host, Origin-Realm, the specified +Result-Code and (if the request sent one) Session-Id AVP's.</p> + +<p> +Note that RFC 3588 mandates that only answers with a 3xxx series +Result-Code (protocol errors) may set the E bit. +Returning a non-3xxx value in a <c>protocol_error</c> tuple +will cause the request process in question to fail.</p> +</item> + +<tag><c>{relay, Opts}</c></tag> +<item> +<p> +Relay a request to another peer in the role of a Diameter relay agent. +If a routing loop is detected then the request is answered with +3005 (DIAMETER_LOOP_DETECTED). +Otherwise a Route-Record AVP (containing the sending peer's Origin-Host) is +added to the request and <seealso marker="#pick_peer">pick_peer/4</seealso> +and subsequent callbacks take place just as if <seealso +marker="diameter#call">diameter:call/4</seealso> had been called +explicitly. +The End-to-End Identifier of the incoming request is preserved in the +header of the relayed request.</p> + +<p> +The returned <c>Opts</c> should not specify <c>detach</c>. +A subsequent <seealso marker="#handle_answer">handle_answer/4</seealso> +callback for the relayed request must return its first +argument, the <c>diameter_packet</c> record containing the answer +message. +Note that the <c>extra</c> option can be specified to supply arguments +that can distinguish the relay case from others if so desired. +Any other return value (for example, from a +<seealso marker="#handle_error">handle_error/4</seealso> callback) +causes the request to be answered with 3002 (DIAMETER_UNABLE_TO_DELIVER).</p> +</item> + +<tag><c>discard</c></tag> +<item> +<p> +Discard the request.</p> +</item> + +<tag><c>{eval, Action, PostF}</c></tag> +<item> +<p> +Handle the request as if <c>Action</c> has been returned and then +evaluate <c>PostF</c> in the request process.</p> +</item> + +</taglist> + +<p> +Note that protocol errors detected by diameter will result in an +answer message without <c>handle_request/3</c> being invoked.</p> + +</desc> +</func> + +</funcs> + +</erlref> diff --git a/lib/diameter/doc/src/diameter_compile.xml b/lib/diameter/doc/src/diameter_compile.xml new file mode 100644 index 0000000000..72bac30709 --- /dev/null +++ b/lib/diameter/doc/src/diameter_compile.xml @@ -0,0 +1,124 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE comref SYSTEM "comref.dtd"> + +<comref> +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> + +The program may be used and/or copied only with the written permission +from Ericsson AB, or in accordance with the terms and conditions +stipulated in the agreement/contract under which the program has been +supplied. + +</legalnotice> + +<title>diameterc(1)</title> + +<prepared></prepared> +<docno></docno> +<date></date> +<rev></rev> +<file>diameter_compile.xml</file> +</header> + +<com>diameterc</com> +<comsummary><![CDATA[diameterc [<options>] <file>]]></comsummary> + +<description> + +<p> +The diameterc utility is used to transform diameter +<seealso marker="diameter_dict">dictionary files</seealso> +into Erlang source. +The resulting source implements the interface diameter requires +to encode and decode the dictionary's messages and AVP's.</p> + +</description> + +<section> +<title>USAGE</title> + +<taglist> + +<tag><![CDATA[diameterc [<options>] <file>]]></tag> +<item> +<p> +Transforms a single dictionary file. Valid options are as follows.</p> + +<!-- Leave -h/d/v undocumented, except for the usage message from the + utility itself. --> + +<taglist> +<tag><![CDATA[-o <dir>]]></tag> +<item> +<p> +Specifies the directory into which the generated source should be written. +Defaults to the current working directory.</p> +</item> + +<tag><![CDATA[-i <dir>]]></tag> +<item> +<p> +Specifies a directory to add to the code path. +Typically used to point at beam files corresponding to dictionaries +included by the one being compiled (using the <c>@includes</c> directive): +inclusion is a beam dependency, not an erl/hrl dependency.</p> + +<p> +Multiple <c>-i</c> options can be specified.</p> +</item> + +<tag><![CDATA[-E]]></tag> +<item> +<p> +Supresses erl generation.</p> +</item> + +<tag><![CDATA[-H]]></tag> +<item> +<p> +Supresses hrl generation.</p> +</item> + +</taglist> + +</item> +</taglist> + +</section> + +<!-- ===================================================================== --> + +<section> +<title>EXIT STATUS</title> + +<p> +Returns 0 on success, non-zero on failure.</p> + +</section> + +<!-- ===================================================================== --> + +<section> +<title>BUGS</title> + +<p> +The identification of errors in the source file is poor.</p> + +</section> + +<!-- ===================================================================== --> + +<section> +<title>SEE ALSO</title> + +<p> +<seealso marker="diameter_dict">diameter_dict(4)</seealso></p> + +</section> + +</comref> diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml new file mode 100644 index 0000000000..e7c530f1b8 --- /dev/null +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -0,0 +1,613 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "fileref.dtd"> + +<fileref> +<header> + +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>diameter_dict(4)</title> +<prepared>Anders Svensson</prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev>%VSN%</rev> +<file>diameter_dict.xml</file> +</header> + +<!-- ===================================================================== --> + +<file>diameter_dict</file> +<filesummary>Dictionary inteface of the diameter application.</filesummary> + +<description> +<p> +A diameter service as configured with <seealso +marker="diameter#start_service">diameter:start_service/2</seealso> +specifies one or more supported Diameter applications. +Each Diameter application specifies a dictionary module that knows how +to encode and decode its messages and AVP's. +The dictionary module is in turn generated from a file that defines +these messages and AVP's. +The format of such a file is defined in +<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso> below. +Users add support for their specific applications by creating +dictionary files, compiling them to Erlang modules using +<seealso marker="diameterc">diameterc</seealso> and configuring the +resulting dictionaries modules on a service.</p> + +<p> +The codec generation also results in a hrl file that defines records +for the messages and grouped AVP's defined for the application, these +records being what a user of the diameter application sends and receives. +(Modulo other available formats as discussed in <seealso +marker="diameter_app">diameter_app(3)</seealso>.) +These records and the underlying Erlang data types corresponding to +Diameter data formats are discussed in <seealso +marker="#MESSAGE_RECORDS">MESSAGE RECORDS</seealso> and <seealso +marker="#DATA_TYPES">DATA TYPES</seealso> respectively. +The generated hrl also contains defines for the possible values of +AVPs of type Enumerated.</p> + +<p> +The diameter application includes three dictionary modules +corresponding to applications defined in section 2.4 of RFC 3588: +<c>diameter_gen_base_rfc3588</c> for the Diameter Common Messages +application with application identifier 0, +<c>diameter_gen_accounting</c> for the Diameter Base Accounting +application with application identifier 3 and +<c>diameter_gen_relay</c>the Relay application with application +identifier 0xFFFFFFFF. +The Common Message and Relay applications are the only applications +that diameter itself has any specific knowledge of. +The Common Message application is used for messages that diameter +itself handles: CER/CEA, DWR/DWA and DPR/DPA. +The Relay application is given special treatment with regard to +encode/decode since the messages and AVP's it handles are not specifically +defined.</p> + +<marker id="FILE_FORMAT"/> +</description> + +<!-- ===================================================================== --> + +<section> +<title>FILE FORMAT</title> + +<p> +A dictionary file consists of distinct sections. +Each section starts with a line consisting of a tag +followed by zero or more arguments. +Each section ends at the the start of the next section or end of file. +Tags consist of an ampersand character followed by a keyword and are +separated from their arguments by whitespace. +Whitespace within a section separates individual tokens but its +quantity is insignificant.</p> + +<p> +The tags, their arguments and the contents of each corresponding +section are as follows. +Each section can occur at most once unless otherwise specified. +The order in which sections are specified is unimportant.</p> + +<taglist> + +<tag><c>@id Number</c></tag> +<item> +<p> +Defines the integer Number as the Diameter Application Id of the +application in question. +Required if the dictionary defines <c>@messages</c>. +The section has empty content.</p> + +<p> +The Application Id is set in the Diameter Header of outgoing messages +of the application, and the value in the header of an incoming message +is used to identify the relevant dictionary module.</p> + +<p> +Example:</p> + +<code> +@id 16777231 +</code> + +</item> + +<tag><c>@name Mod</c></tag> +<item> +<p> +Defines the name of the generated dictionary module. +The section has empty content. +Mod must match the regular expression '^[a-zA-Z0-9][-_a-zA-Z0-9]*$'; +that is, contains only alphanumerics, hyphens and underscores begin with an +alphanumeric.</p> + +<p> +A name is optional and defaults to the name of the dictionary file +minus any extension. +Note that a generated module must have a unique name an not colide +with another module in the system.</p> + +<p> +Example:</p> + +<code> +@name etsi_e2 +</code> + +</item> + +<tag><c>@prefix Name</c></tag> +<item> +<p> +Defines Name as the prefix to be added to record and constant names in +the generated dictionary module and hrl. +The section has empty content. +Name must be of the same form as a @name.</p> + +<p> +A prefix is optional but can +be used to disambiguate record and constant names +resulting from similarly named messages and AVP's in different +Diameter applications.</p> + +<p> +Example:</p> + +<code> +@prefix etsi_e2_ +</code> + +</item> + +<tag><c>@vendor Number Name</c></tag> +<item> +<p> +Defines the integer Number as the the default Vendor-ID of AVP's for +which the V flag is set. +Name documents the owner of the application +but is otherwise unused. +The section has empty content.</p> + +<p> +Example:</p> + +<code> +@vendor 13019 ETSI +</code> + +</item> + +<tag><c>@avp_vendor_id Number</c></tag> +<item> +<p> +Defines the integer Number as the Vendor-ID of the AVP's listed in the +section content, overriding the <c>@vendor</c> default. +The section content consists of AVP names. +Can occur zero or more times (with different values of Number).</p> + +<p> +Example:</p> + +<code> +@avp_vendor_id 2937 + +WWW-Auth +Domain-Index +Region-Set +</code> + +</item> + +<tag><c>@inherits Mod</c></tag> +<item> +<p> +Defines the name of a generated dictionary module containing AVP +definitions referenced by the dictionary but not defined by it. +The section content is empty.</p> + +<p> +Can occur 0 or more times (with different values of Mod) but all +dictionaries should typically inherit RFC3588 AVPs from +<c>diameter_gen_base_rfc3588</c>.</p> + +<p> +Example:</p> + +<code> +@inherits diameter_gen_base_rfc3588 +</code> + +</item> + +<tag><c>@avp_types</c></tag> +<item> +<p> +Defines the name, code, type and flags of individual AVPs. +The section consists of definitions of the form</p> + +<p><c>Name Code Type Flags</c></p> + +<p> +where Code is the integer AVP code, Flags is a string of V, +M and P characters indicating the flags to be +set on an outgoing AVP or a single - (minus) character if none are to +be set. +Type identifies either an AVP Data Format as defined in <seealso +marker="#DATA_TYPES">DATA TYPES</seealso> below or a +type as defined by a <c>@custom_types</c> tag.</p> + +<p> +Example:</p> + +<code> +@avp_types + +Location-Information 350 Grouped VM +Requested-Information 353 Enumerated V +</code> + +<p> +Note that the P flag has been deprecated by the Diameter Maintenance +and Extensions Working Group of the IETF: diameter will set the P flag +to 0 as mandated by the current draft standard.</p> + +</item> + +<tag><c>@custom_types Mod</c></tag> +<item> +<p> +Defines AVPs for which module Mod provides encode/decode. +The section contents consists of type names. +For each AVP Name defined with custom type Type, Mod should export the +function Name/3 with arguments encode|decode, Type and Data, +the latter being the term to be encoded/decoded. +The function returns the encoded/decoded value.</p> + +<p> +Can occur 0 or more times (with different values of Mod).</p> + +<p> +Example:</p> + +<code> +@custom_types rfc4005_types + +Framed-IP-Address +</code> +</item> + +<tag><c>@messages</c></tag> +<item> +<p> +Defines the messages of the application. +The section content consists of definitions of the form specified in +section 3.2 of RFC 3588, "Command Code ABNF specification".</p> + +<!-- RFC 4740 RTR/RTA --> +<code> +@messages + +RTR ::= < Diameter Header: 287, REQ, PXY > + < Session-Id > + { Auth-Application-Id } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + { Destination-Host } + { SIP-Deregistration-Reason } + [ Destination-Realm ] + [ User-Name ] + * [ SIP-AOR ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] + +RTA ::= < Diameter Header: 287, PXY > + < Session-Id > + { Auth-Application-Id } + { Result-Code } + { Auth-Session-State } + { Origin-Host } + { Origin-Realm } + [ Authorization-Lifetime ] + [ Auth-Grace-Period ] + [ Redirect-Host ] + [ Redirect-Host-Usage ] + [ Redirect-Max-Cache-Time ] + * [ Proxy-Info ] + * [ Route-Record ] + * [ AVP ] +</code> + +</item> + +<tag><c>@grouped</c></tag> +<item> +<p> +Defines the contents of the AVPs of the application having type +Grouped. +The section content consists of definitions of the form specified in +section 4.4 of RFC 3588, "Grouped AVP Values".</p> + +<p> +Example:</p> + +<code> +@grouped + +SIP-Deregistration-Reason ::= < AVP Header: 383 > + { SIP-Reason-Code } + [ SIP-Reason-Info ] + * [ AVP ] +</code> +</item> + +<tag><c>@enum Name</c></tag> +<item> +<p> +Defines values of AVP Name having type Enumerated. +Section content consists of names and corresponding integer values. +Integer values can be prefixed with 0x to be interpreted as +hexidecimal.</p> + +<p> +Can occur 0 or more times (with different values of Name). +The AVP in question can be defined in an inherited dictionary in order +to introduce additional values. +An AVP so extended must be referenced by in a <c>@messages</c> or +<c>@grouped</c> section.</p> + +<p> +Example:</p> + +<code> +@enum SIP-Reason-Code + +PERMANENT_TERMINATION 0 +NEW_SIP_SERVER_ASSIGNED 1 +SIP_SERVER_CHANGE 2 +REMOVE_SIP_SERVER 3 +</code> +</item> + +</taglist> + +<p> +Comments can be included in a dictionary file using semicolon: +text from a semicolon to end of line is ignored.</p> + +<marker id="MESSAGE_RECORDS"/> +</section> + +<!-- ===================================================================== --> + +<section> +<title>MESSAGE RECORDS</title> + +<p> +The hrl generated from a dictionary specification defines records for the +messages and grouped AVPs defined in <c>@messages</c> and +<c>@grouped</c> sections. +For each message or grouped AVP definition, a record is defined whose +name is the message or AVP name prefixed with any dictionary prefix +defined with <c>@prefix</c> and whose fields are the names of the AVPs +contained in the message or grouped AVP in the order specified in the +definition in question. +For example, the grouped AVP</p> + +<code> +SIP-Deregistration-Reason ::= < AVP Header: 383 > + { SIP-Reason-Code } + [ SIP-Reason-Info ] + * [ AVP ] +</code> + +<p> +will result in the following record definition given an empty +prefix.</p> + +<code> +-record('SIP-Deregistration-Reason' {'SIP-Reason-Code', + 'SIP-Reason-Info', + 'AVP'}). +</code> + +<p> +The values encoded in the fields of generated records depends on the +type and number of times the AVP can occur. +In particular, an AVP which is specified as occurring exactly once is +encoded as a value of the AVP's type while an AVP with any other +specification is encoded as a list of values of the AVP's type. +The AVP's type is as specified in the AVP definition, the RFC 3588 +types being described below.</p> + +<marker id="DATA_TYPES"/> +</section> + +<!-- ===================================================================== --> + +<section> +<title>DATA TYPES</title> + +<p> +The data formats defined in sections 4.2 ("Basic AVP Data +Formats") and 4.3 ("Derived AVP Data Formats") of RFC 3588 are encoded +as values of the types defined here. +Values are passed to <seealso +marker="diameter#call">diameter:call/4</seealso> +in a request record when sending a request, returned in a resulting +answer record and passed to a <seealso +marker="diameter_app#handle_request">handle_request</seealso> +callback upon reception of an incoming request.</p> + +<p> +<em>Basic AVP Data Formats</em></p> + +<marker id="OctetString"/> +<marker id="Integer32"/> +<marker id="Integer64"/> +<marker id="Unsigned32"/> +<marker id="Unsigned64"/> +<marker id="Float32"/> +<marker id="Float64"/> +<marker id="Grouped"/> + +<code> +OctetString() = [0..255] +Integer32() = -2147483647..2147483647 +Integer64() = -9223372036854775807..9223372036854775807 +Unsigned32() = 0..4294967295 +Unsigned64() = 0..18446744073709551615 +Float32() = '-infinity' | float() | infinity +Float64() = '-infinity' | float() | infinity +Grouped() = record() +</code> + +<p> +On encode, an OctetString() can be specified as an iolist(), +excessively large floats (in absolute value) are equivalent to +<c>infinity</c> or <c>'-infinity'</c> and excessively large integers +result in encode failure. +The records for grouped AVPs are as discussed in the previous +section.</p> + +<p> +<em>Derived AVP Data Formats</em></p> + +<marker id="Address"/> +<code> +Address() = OctetString() + | tuple() +</code> + +<p> +On encode, an OctetString() IPv4 address is parsed in the usual +x.x.x.x format while an IPv6 address is parsed in any of the formats +specified by section 2.2 of RFC 2373, "Text Representation of +Addresses". +An IPv4 tuple() has length 4 and contains values of type 0..255. +An IPv6 tuple() has length 8 and contains values of type 0..65535. +The tuple representation is used on decode.</p> + +<marker id="Time"/> +<code> +Time() = {date(), time()} + +where + + date() = {Year, Month, Day} + time() = {Hour, Minute, Second} + + Year = integer() + Month = 1..12 + Day = 1..31 + Hour = 0..23 + Minute = 0..59 + Second = 0..59 +</code> + +<p> +Additionally, values that can be encoded are +limited by way of their encoding as four octets as required by RFC +3588 with the required extension from RFC 2030. +In particular, only values between <c>{{1968,1,20},{3,14,8}}</c> +and <c>{{2104,2,26},{9,42,23}}</c> (both inclusive) can be encoded.</p> + +<marker id="UTF8String"/> +<code> +UTF8String() = [integer()] +</code> + +<p> +List elements are the UTF-8 encodings of the individual characters +in the string. +Invalid codepoints will result in encode/decode failure.</p> + +<marker id="DiameterIdentity"/> +<code> +DiameterIdentity() = OctetString() +</code> + +<p> +A value must have length at least 1.</p> + +<marker id="DiameterURI"/> +<code> +DiameterURI() = OctetString() + | #diameter_URI{type = Type, + fqdn = FQDN, + port = Port, + transport = Transport, + protocol = Protocol} + +where + + Type = aaa | aaas + FQDN = OctetString() + Port = integer() + Transport = sctp | tcp + Protocol = diameter | radius | 'tacacs+' +</code> + +<p> +On encode, fields port, transport and protocol default to 3868, sctp +and diameter respectively. +The grammar of an OctetString-valued DiameterURI() is as specified in +section 4.3 of RFC 3588. +The record representation is used on decode.</p> + +<marker id="Enumerated"/> +<code> +Enumerated() = Integer32() +</code> + +<p> +On encode, values can be specified using the macros defined in a +dictionary's hrl file.</p> + +<marker id="IPFilterRule"/> +<marker id="QoSFilterRule"/> +<code> +IPFilterRule() = OctetString() +QoSFilterRule() = OctetString() +</code> + +<p> +Values of these types are not currently parsed by diameter.</p> + +</section> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<section> +<title>SEE ALSO</title> + +<p> +<seealso marker="diameterc">diameterc(1)</seealso>, +<seealso marker="diameter">diameter(3)</seealso>, +<seealso marker="diameter_app">diameter_app(3)</seealso></p> + +</section> + +</fileref> diff --git a/lib/diameter/doc/src/diameter_examples.xml b/lib/diameter/doc/src/diameter_examples.xml new file mode 100644 index 0000000000..966d1f1eee --- /dev/null +++ b/lib/diameter/doc/src/diameter_examples.xml @@ -0,0 +1,45 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> +<header> + +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> + +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Examples</title> +<prepared></prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_examples.xml</file> +</header> + +<!-- ===================================================================== --> + +<p> +To be written. +Example code can be found in the diameter application's +<c>examples</c> subdirectory.</p> + +</chapter> + diff --git a/lib/diameter/doc/src/diameter_intro.xml b/lib/diameter/doc/src/diameter_intro.xml new file mode 100644 index 0000000000..ef08002a8b --- /dev/null +++ b/lib/diameter/doc/src/diameter_intro.xml @@ -0,0 +1,95 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> + +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Introduction</title> +<prepared></prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_intro.xml</file> +</header> + +<p> +The diameter application is an implementation of the Diameter protocol +as defined by RFC 3588. +It supports arbitrary Diameter applications by way of a +<em>dictionary</em> interface that allows messages and AVP's to be +defined and input into diameter as configuration. +It has support for all roles defined in the RFC: client, server and +agent. +This chapter provides a short overview of the application.</p> + +<p> +A Diameter peer is implemented by configuring a <em>service</em> and +one or more <em>transports</em> using the interface module +<seealso marker="diameter">diameter</seealso>. +The service configuration defines the Diameter applications to be +supported by the peer and, typically, the capabilities that it should +send to remote peers at capabilities exchange upon the establishment +of transport connections. +A transport is configured on a service and provides protocol-specific +send/receive functionality by way of a transport interface defined by +diameter and implemented by a transport module. +The diameter application provides two transport modules: <seealso +marker="diameter_tcp">diameter_tcp</seealso> and <seealso +marker="diameter_sctp">diameter_sctp</seealso> for transport over TCP +(using <c>gen_tcp</c>) and SCTP (using <c>gen_sctp</c>) respectively. +Other transports can be provided by any module that implements +diameter's <seealso marker="diameter_transport">transport +interface</seealso>.</p> + +<p> +While a service typically implements a single Diameter peer (as +identified by an Origin-Host AVP), transports can themselves be +associated with capabilities AVP's so that a single service be used to +implement more than one Diameter peer.</p> + +<p> +Each Diameter application defined on a service is configured with a +callback module that implements the <seealso +marker="diameter_app">application interface</seealso> through which +diameter communicates the connectivity of remote peers, requests peer +selection for outgoing requests, and communicates the reception of +incoming Diameter request and answer messages. +An application using diameter implements these application callback +modules to provide the functionality of the Diameter peer(s) it +implements.</p> + +<p> +Each Diameter application is also configured with one or more +dictionary modules +that provide encode/decode functionality for outgoing/incoming +Diameter messages. +A module is generated from a <seealso +marker="diameter_dict">specification file</seealso> using the <seealso +marker="diameterc">diameterc</seealso> utility. +Dictionaries for the RFC 3588 Diameter Common Messages, Base +Accounting and Relay applications are provided by the diameter +application.</p> + +</chapter> + diff --git a/lib/diameter/doc/src/diameter_sctp.xml b/lib/diameter/doc/src/diameter_sctp.xml new file mode 100644 index 0000000000..c1e839b8e1 --- /dev/null +++ b/lib/diameter/doc/src/diameter_sctp.xml @@ -0,0 +1,135 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>diameter_sctp(3)</title> +<prepared>Anders Svensson</prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_sctp.xml</file> +</header> + +<module>diameter_sctp</module> +<modulesummary>Diameter transport over SCTP.</modulesummary> + +<description> + +<p> +This module implements diameter transport over SCTP using gen_sctp. +It can be specified as the value of a transport_module option to +<seealso +marker="diameter#add_transport">diameter:add_transport/2</seealso> +and implements the behaviour documented in +<seealso marker="diameter_transport">diameter_transport(3)</seealso>.</p> + +<marker id="start"/> +</description> + +<!-- ===================================================================== --> + +<funcs> + +<func> +<name>start({Type, Ref}, Svc, [Opt]) + -> {ok, Pid, [LAddr]} | {error, Reason}</name> +<fsummary>Start a transport process.</fsummary> +<type> +<v>Type = connect | accept</v> +<v>Ref = reference()</v> +<v>Svc = #diameter_service{}</v> +<v>Opt = {raddr, ip_address()} | {rport, integer()} | term()</v> +<v>Pid = pid()</v> +<v>LAddr = ip_address()</v> +<v>Reason = term()</v> +</type> +<desc> + +<p> +The start function required by <seealso +marker="diameter_transport#start">diameter_transport(3)</seealso>.</p> + +<p> +The only diameter_sctp-specific argument is the options list. +Options <c>raddr</c> and <c>rport</c> specify the remote address +and port for a connecting transport and not valid for a listening +transport. +The former is required while latter defaults to 3868 if unspecified. +More than one <c>raddr</c> option can be specified, in which case the +connecting transport in question attempts each in sequence until +an association is established. +Remaining options are any accepted by gen_sctp:open/1, with the exception +of options <c>mode</c>, <c>binary</c>, <c>list</c>, <c>active</c> +and <c>sctp_events</c>. +Note that options <c>ip</c> and <c>port</c> specify the local address +and port respectively.</p> + +<p> +Multiple <c>ip</c> options can be specified for a multihomed peer. +If none are specified then the values of Host-IP-Address +on the service are used. (In particular, one of these must be specified.) +Option <c>port</c> defaults to 3868 for a listening transport and 0 for a +connecting transport.</p> + +<p> +diameter_sctp uses the <c>transport_data</c> field of +the <c>diameter_packet</c> record to communicate the stream on which an +inbound message has been received, or on which an outbound message +should be sent: the value will be of the form <c>{stream, Id}</c> +on an inbound message passed to a <seealso +marker="diameter_app#handle_request">handle_request</seealso> or <seealso +marker="diameter_app#handle_answer">handle_answer</seealso> callback. +For an outbound message, either <c>undefined</c> (explicitly of +by specifying the outbound message as a <c>binary()</c>) or a tuple +should be set in the return value of <seealso +marker="diameter_app#handle_request">handle_request</seealso> +(typically by retaining the value passed into this function) +or <seealso +marker="diameter_app#prepare_request">prepare_request</seealso>. +The value <c>undefined</c> uses a "next outbound stream" id and then +increments this modulo the total number outbound streams. That +is, successive values of <c>undefined</c> cycle through all outbound +streams.</p> + +<!-- TODO: Some way of getting at the number of available outbound --> +<!-- streams. --> + +</desc> +</func> + +</funcs> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<section> +<title>SEE ALSO</title> + +<p> +<seealso marker="diameter_transport">diameter_transport(3)</seealso></p> + +</section> + +</erlref> diff --git a/lib/diameter/doc/src/diameter_soc.xml b/lib/diameter/doc/src/diameter_soc.xml new file mode 100644 index 0000000000..4f8581a904 --- /dev/null +++ b/lib/diameter/doc/src/diameter_soc.xml @@ -0,0 +1,110 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> + +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Standards Compliance</title> +<prepared></prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_soc.xml</file> + +</header> + +<p> +Known points of questionable or non-compliance.</p> + +<!-- ===================================================================== --> + +<section> +<title>RFC 3588</title> + +<list> + +<item> +<p> +The End-to-End Security framework (section 2.9) isn't implemented +since it is largely unspecified. +The document that was to describe it +(reference [AAACMS]) was abandoned in an uncompleted state several +years ago and the current draft RFC deprecates the framework, +including the P Flag in the AVP header.</p> +</item> + +<item> +<p> +There is no TLS support. +It's unclear (aka uninvestigated) how TLS would impact +diameter but IPsec can be used without it needing to know.</p> +</item> + +<item> +<p> +There is no explicit support for peer discovery (section 5.2). +It can possibly be implemented on top of diameter as is but this is +probably something that diameter should do. +The current draft deprecates portions of the original RFC's mechanisms +however.</p> +</item> + +<item> +<p> +The peer state machine's election process (section 5.6.4) isn't +implemented as specified since it assumes knowledge of a +peer's Origin-Host before sending it a CER. (The identity becoming known +upon reception of CEA.) +The possibility of configuring +the peer's Origin-Host could be added, along with handling of the case +that it sends something else, but for many applications this will +just be unnecessary configuration of a value that it has no control over.</p> +</item> +<!-- Transport protocol plus address/port, which we do know when + sending and receiving CER, is enough to definitely identify + the peer. However, there's nothing stopping a peer from using + different identities on different transport protocols, even + if it's maybe a bit far-fetched. --> + +</list> + +</section> + +<!-- ===================================================================== --> + +<section> +<title>RFC 3539</title> + +<p> +RFC 3539 is more difficult to comply to since it discusses +problems as much as it requires functionality but all the MUST's are +covered, the watchdog state machine being the primary one. +Of the optional functionality, load balancing is left to the +diameter user (since it's the one deciding who to send to) and +there is no Congestion Manager.</p> + +</section> + +</chapter> diff --git a/lib/diameter/doc/src/diameter_tcp.xml b/lib/diameter/doc/src/diameter_tcp.xml new file mode 100644 index 0000000000..a502e53972 --- /dev/null +++ b/lib/diameter/doc/src/diameter_tcp.xml @@ -0,0 +1,111 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>diameter_tcp(3)</title> +<prepared>Anders Svensson</prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_tcp.xml</file> +</header> + +<module>diameter_tcp</module> +<modulesummary>Diameter transport over TCP.</modulesummary> + +<description> + +<p> +This module implements diameter transport over TCP using gen_tcp. +It can be specified as the value of a transport_module option to +<seealso +marker="diameter#add_transport">diameter:add_transport/2</seealso> +and implements the behaviour documented in +<seealso marker="diameter_transport">diameter_transport(3)</seealso>.</p> + +<marker id="start"/> +</description> + +<!-- ===================================================================== --> + +<funcs> + +<func> +<name>start({Type, Ref}, Svc, [Opt]) + -> {ok, Pid, [LAddr]} | {error, Reason}</name> +<fsummary>Start a transport process.</fsummary> +<type> +<v>Type = connect | accept</v> +<v>Ref = reference()</v> +<v>Svc = #diameter_service{}</v> +<v>Opt = {raddr, ip_address()} | {rport, integer()} | term()</v> +<v>Pid = pid()</v> +<v>LAddr = ip_address()</v> +<v>Reason = term()</v> +</type> +<desc> + +<p> +The start function required by <seealso +marker="diameter_transport#start">diameter_transport(3)</seealso>.</p> + +<p> +The only diameter_tcp-specific argument is the options list. +Options <c>raddr</c> and <c>rport</c> specify the remote address +and port for a connecting transport and not valid for a listening +transport. +Remaining options are any accepted by gen_tcp:connect/3 for +a connecting transport, or gen_tcp:listen/2 for a listening transport, +with the exception of <c>binary</c>, <c>packet</c> and <c>active</c>. +Also, option <c>port</c> can be specified for a listening transport +to specify the local listening port, the default being the standardized +3868 if unspecified. +Note that option <c>ip</c> specifies the local address.</p> + +<p> +If the service specifies more than one Host-IP-Address and +option <c>ip</c> is unspecified then then the +first of the service's addresses is used as the local address.</p> + +<p> +The returned local address list has length one.</p> + +</desc> +</func> + +</funcs> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<section> +<title>SEE ALSO</title> + +<p> +<seealso marker="diameter_transport">diameter_transport(3)</seealso></p> + +</section> + +</erlref> diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml new file mode 100644 index 0000000000..37cc871e75 --- /dev/null +++ b/lib/diameter/doc/src/diameter_transport.xml @@ -0,0 +1,203 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>diameter_transport(3)</title> +<prepared>Anders Svensson</prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_transport.xml</file> +</header> + +<module>diameter_transport</module> +<modulesummary>Diameter transport interface.</modulesummary> + +<description> + +<p> +A module specified as a <c>transport_module</c> to <seealso +marker="diameter#add_transport">diameter:add_transport/2</seealso> +must implement the interface documented here. +The interface consists of a function with which +diameter starts a transport process and a message interface with which +the transport process communicates with the process that starts it (aka its +parent).</p> + +<marker id="start"/> +</description> + +<!-- ===================================================================== --> + +<funcs> + +<func> +<name>Mod:start({Type, Ref}, Svc, Opts) + -> {ok, Pid} | {ok, Pid, LAddrs} | {error, Reason}</name> +<fsummary>Start a transport process.</fsummary> +<type> +<v>Type = connect | accept</v> +<v>Ref = reference()</v> +<v>Svc = #diameter_service{}</v> +<v>Opts = term()</v> +<v>Pid = pid()</v> +<v>LAddrs = [ip_address()]</v> +<v>Reason = term()</v> +</type> +<desc> +<p> +Start a transport process. +Called by diameter as a consequence of a call to <seealso +marker="diameter#add_transport">diameter:add_transport/2</seealso> in +order to establish or accept a transport connection respectively. +A transport process maintains a connection with a single remote peer.</p> + +<p> +The first argument indicates whether the transport process in question +is being started for a connecting (<c>connect</c>) or listening +(<c>accept</c>) transport. +In the latter case, transport processes are started as required to +accept connections from multiple peers. +Ref is in each case the same value that was returned from the +call to <seealso +marker="diameter#add_transport">diameter:add_transport/2</seealso> +that has lead to starting of a transport process.</p> + +<p> +A transport process must implement the message interface documented below. +It should retain the pid of its parent, monitor the parent and terminate if +it dies. +It should not link to the parent. +It should exit if its transport connection with its peer is lost.</p> + +<p> +Transport processes for a given service are started sequentially.</p> + +<p> +The start function should use the 'Host-IP-Address' list on the service, +namely <c>Svc#diameter_service.host_ip_address</c>, and/or +<c>Opts</c> to select an appropriate list of local IP addresses, +and should return this list if different from the service addresses. +The returned list is used to populate 'Host-IP-Address' AVPs in outgoing +capabilities exchange messages, the service addresses being used +otherwise.</p> + +<marker id="MESSAGES"/> +</desc> +</func> + +</funcs> + +<!-- ===================================================================== --> + +<section> +<title>MESSAGES</title> + +<p> +All messages sent over the transport interface are of the +form <c>{diameter, term()}</c>.</p> + +<p> +A transport process can expect the following messages from +diameter.</p> + +<taglist> + +<tag><c>{diameter, {send, Packet}}</c></tag> +<item> +<p> +An outbound Diameter message. +Packet can be either <c>binary()</c> (the message to be sent) +or a <c>#diameter_packet{}</c> whose <c>transport_data</c> field +containes a value other than undefined.</p> +</item> + +<tag><c>{diameter, {close, Pid}}</c></tag> +<item> +<p> +A request to close the transport connection. +The transport process should terminate after closing the +connection. +Pid is the pid() of the parent process.</p> +</item> + +</taglist> + +<p> +A transport process should send the following messages +to its parent.</p> + +<taglist> + +<tag><c>{diameter, {self(), connected}}</c></tag> +<item> +<p> +Inform the parent that the transport process with Type = accept has +established a connection with the peer. +Not sent if the transport process has Type = connect.</p> +</item> + +<tag><c>{diameter, {self(), connected, Remote}}</c></tag> +<item> +<p> +Inform the parent that the transport process with Type = connect +has established a connection with a peer. +Not sent if the transport process has Type = accept. +Remote is an arbitrary term that uniquely identifies the remote +endpoint to which the transport has connected.</p> +</item> + +<tag><c>{diameter, {recv, Packet}}</c></tag> +<item> +<p> +An inbound Diameter message. +Packet can be either <c>binary()</c> (the message to be sent) +or <c>#diameter_packet{}</c> +whose <c>packet</c> field contains a <c>binary()</c>. +Any value (other than undefined) set in +the <c>transport_data</c> field will be passed back with a +corresponding answer message in the case that the inbound message is a +request unless the sender sets another value. +How the <c>transport_data</c> is used/interpreted is up to the +transport module.</p> +</item> + +</taglist> + +</section> + +<!-- ===================================================================== --> +<!-- ===================================================================== --> + +<section> +<title>SEE ALSO</title> + +<p> +<seealso marker="diameter_tcp">diameter_tcp(3)</seealso>, +<seealso marker="diameter_sctp">diameter_sctp(3)</seealso></p> + +</section> + +</erlref> diff --git a/lib/diameter/doc/src/diameter_using.xml b/lib/diameter/doc/src/diameter_using.xml new file mode 100644 index 0000000000..809b76bdf3 --- /dev/null +++ b/lib/diameter/doc/src/diameter_using.xml @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> + +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Using the stack</title> +<prepared></prepared> +<responsible></responsible> +<docno></docno> +<approved></approved> +<checked></checked> +<date></date> +<rev></rev> +<file>diameter_using.xml</file> + +</header> + +<p> +To be written.</p> + +<!-- ===================================================================== --> + +</chapter> diff --git a/lib/diameter/doc/src/files.mk b/lib/diameter/doc/src/files.mk new file mode 100644 index 0000000000..79d53abceb --- /dev/null +++ b/lib/diameter/doc/src/files.mk @@ -0,0 +1,52 @@ +#-*-makefile-*- ; force emacs to enter makefile-mode + +# %CopyrightBegin% +# +# Copyright Ericsson AB 2010-2011. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% + +XML_APPLICATION_FILES = \ + ref_man.xml + +XML_REF1_FILES = \ + diameter_compile.xml + +XML_REF3_FILES = \ + diameter.xml \ + diameter_app.xml \ + diameter_transport.xml \ + diameter_tcp.xml \ + diameter_sctp.xml + +XML_REF4_FILES = \ + diameter_dict.xml + +XML_PART_FILES = \ + user_man.xml + +XML_EXTRA_FILES = + +XML_CHAPTER_FILES = \ + diameter_intro.xml \ + diameter_using.xml \ + diameter_examples.xml \ + diameter_soc.xml \ + notes.xml + +BOOK_FILES = \ + book.xml + +GIF_FILES = \ + notes.gif diff --git a/lib/diameter/doc/src/notes.gif b/lib/diameter/doc/src/notes.gif Binary files differnew file mode 100644 index 0000000000..e000cca26a --- /dev/null +++ b/lib/diameter/doc/src/notes.gif diff --git a/lib/diameter/doc/src/notes.xml b/lib/diameter/doc/src/notes.xml new file mode 100644 index 0000000000..e2723f3e99 --- /dev/null +++ b/lib/diameter/doc/src/notes.xml @@ -0,0 +1,233 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Release Notes</title> +<prepared></prepared> +<docno></docno> +<date></date> +<rev></rev> +<file>notes.xml</file> +</header> + +<p> +Releases are listed in reverse chronological order, most recent +first.</p> + +<!-- ===================================================================== --> + +<section><title>Diameter 0.10</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Handle #sctp_paddr_change and #sctp_pdapi_event from + gen_sctp.</p> + <p> + The events are enabled by default but diameter_sctp + neither disabled nor dealt with them. Reception of such + an event caused a transport process to crash.</p> + <p> + Own Id: OTP-9538</p> + </item> + <item> + <p> + Fix header folding bug.</p> + <p> + A prepare_request callback from diameter can return a + diameter_header record in order to set values in the + header of an outgoing request. A fault in + diameter_lib:fold_tuple/3 caused the subsequent encode of + the outgoing request to fail.</p> + <p> + Own Id: OTP-9577</p> + </item> + <item> + <p> + Fix bugs in sending of answer-message replies.</p> + <p> + 3001 (DIAMETER_COMMAND_UNSUPPORTED) was not sent since + the decode placed the AVP list in the wrong field of the + diameter_packet, causing the subsequent encode to fail. + Session-Id was also set improperly, causing encode to + fail even in this case.</p> + <p> + Own Id: OTP-9578</p> + </item> + <item> + <p> + Fix improper use of error_logger:info_report/2.</p> + <p> + Function doesn't take a format string and arguments as it + was called. Instead use error_logger:info_report/1 and + use the same report format as used for warning and error + reports.</p> + <p> + Own Id: OTP-9579</p> + </item> + <item> + <p> + Fix and clarify semantics of peer filters.</p> + <p> + An eval filter returning a non-true value caused the call + process to fail and the doc was vague on how an exception + was treated. Clarify that the non-tuple host/realm + filters assume messages of a certain form.</p> + <p> + Own Id: OTP-9580</p> + </item> + <item> + <p> + Fix and clarify relay behaviour.</p> + <p> + Implicit filtering of the sending peer in relaying a + request could cause loop detection to be preempted in a + manner not specified by RFC3588. Reply with 3002 + (DIAMETER_UNABLE_TO_DELIVER) on anything but an answer to + a relayed request.</p> + <p> + Own Id: OTP-9583</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + @id required in dictionary files only when @messages is + specified.</p> + <p> + @id defines an application identifier and this is used + only when sending or receiving messages. A dictionary can + define only AVP's however, to be included by other + dictionaries using @inherits, in which case it makes no + sense to require @id.</p> + <p> + Note that message definitions are not inherited with + @inherits, only AVP's</p> + <p> + Own Id: OTP-9467</p> + </item> + <item> + <p> + Allow @enum when AVP is defined in an inherited + dictionary.</p> + <p> + 3GPP standards (for one) extend the values allowed for + RFC 3588 AVP's of type Enumerated. Previously, extending + an AVP was only possible by completely redefining the + AVP.</p> + <p> + Own Id: OTP-9469</p> + </item> + <item> + <p> + Migrate testsuites to pure common test and add both + suites and testcases.</p> + <p> + Own Id: OTP-9553</p> + </item> + <item> + <p> + Requests of arbitrary form.</p> + <p> + diameter:call/4 can be passed anything, as long as the + subsequent prepare_request callback returns a term that + can be encoded.</p> + <p> + Own Id: OTP-9581</p> + </item> + </list> + </section> + +</section> + +<section> +<title>diameter 0.9</title> + +<p> +Initial release of the diameter application.</p> + +<p> +Known issues or limitations:</p> + +<list> + +<item> +<p> +Some agent-related functionality is not entirely complete. +In particular, support for proxy agents, that advertise specific +Diameter applications but otherwise relay messages in much the same +way as relay agents (for which a <seealso +marker="diameter_app#handle_request">handle_request/3</seealso> +callback can return a <c>relay</c> tuple), will be completed in an +upcoming release. +There may also be more explicit support for redirect agents, although +redirect behaviour can be implemented with the current +functionality.</p> + +</item> + +<item> +<p> +There is some asymmetry in the treatment of messages sent as +<c>diameter_header/avp</c> records and those sent in the "normal" +fashion, and not all of this is documented. +This is related to the previous point since this form of sending a +message was introduced specifically to handle relay agent behaviour +using the same callback interface as for client/server behaviour.</p> +</item> + +<item> +<p> +The User's Guide is currently quite thin. +The introductory chapter followed by the examples (in the application +<c>examples</c> subdirectory) may be sufficient +for those having some familiarity with the Diameter protocol but the +intention is to provide more introductory text. +The reference documentation is quite complete, although some points +could likely be expanded upon.</p> +</item> + +<item> +<p> +The function <seealso +marker="diameter#service_info">diameter:service_info/2</seealso> +can be used to retrieve information about a started service +(statistics, information about connected peers, etc) but +this is not yet documented and both the input and output may change +in the next release.</p> +</item> + + +</list> + +<p> +See <seealso marker="diameter_soc">Standards Compliance</seealso> for +standards-related issues.</p> +</section> + +</chapter> diff --git a/lib/diameter/doc/src/ref_man.xml b/lib/diameter/doc/src/ref_man.xml new file mode 100644 index 0000000000..137ce79094 --- /dev/null +++ b/lib/diameter/doc/src/ref_man.xml @@ -0,0 +1,48 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE application SYSTEM "application.dtd"> + +<application xmlns:xi="http://www.w3.org/2001/XInclude"> + +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Diameter Reference Manual</title> +<prepared></prepared> +<docno></docno> +<date></date> +<rev></rev> +<file>ref_man.xml</file> +</header> + +<description> +<p> +The Diameter application is a framework for building +applications on top of the Diameter protocol. </p> + +</description> + +<xi:include href="diameter.xml"/> +<xi:include href="diameter_compile.xml"/> +<xi:include href="diameter_app.xml"/> +<xi:include href="diameter_dict.xml"/> +<xi:include href="diameter_transport.xml"/> +<xi:include href="diameter_tcp.xml"/> +<xi:include href="diameter_sctp.xml"/> + +</application> diff --git a/lib/diameter/doc/src/user_man.xml b/lib/diameter/doc/src/user_man.xml new file mode 100644 index 0000000000..a6416c7e23 --- /dev/null +++ b/lib/diameter/doc/src/user_man.xml @@ -0,0 +1,44 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + +<header> +<copyright> +<year>2011</year> +<holder>Ericsson AB. All Rights Reserved.</holder> +</copyright> +<legalnotice> +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +</legalnotice> + +<title>Diameter Users Guide</title> +<prepared></prepared> +<docno></docno> +<date></date> +<rev></rev> +<file>user_man.xml</file> +</header> +<description> + +<p> +The diameter application is a framework for building +applications on top of the Diameter protocol. </p> +</description> + +<xi:include href="diameter_intro.xml"/> +<xi:include href="diameter_using.xml"/> +<xi:include href="diameter_examples.xml"/> +<xi:include href="diameter_soc.xml"/> + +</part> |
