From 21f03ba683b80b24ec25f91ec36a76fe22721795 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Thu, 19 May 2011 12:25:17 +0200 Subject: Fix broken make dependencies by generating them. --- lib/diameter/doc/src/.gitignore | 2 ++ lib/diameter/doc/src/Makefile | 31 +++++++++++++++---------------- lib/diameter/doc/src/depend.sed | 34 ++++++++++++++++++++++++++++++++++ 3 files changed, 51 insertions(+), 16 deletions(-) create mode 100644 lib/diameter/doc/src/.gitignore create mode 100644 lib/diameter/doc/src/depend.sed 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 index f2a91a88b7..22e21936fd 100644 --- a/lib/diameter/doc/src/Makefile +++ b/lib/diameter/doc/src/Makefile @@ -35,8 +35,10 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) # ---------------------------------------------------- include files.mk +XML_REF_FILES = $(XML_REF1_FILES) $(XML_REF3_FILES) $(XML_REF4_FILES) + XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) \ - $(XML_REF1_FILES) $(XML_REF3_FILES) $(XML_REF4_FILES) \ + $(XML_REF_FILES) \ $(XML_PART_FILES) $(XML_CHAPTER_FILES) INTERNAL_HTML_FILES = $(TECHNICAL_DESCR_FILES:%.xml=$(HTMLDIR)/%.html) @@ -49,9 +51,7 @@ HTML_FILES = $(HTML_APP_FILES) $(HTML_EXTRA_FILES) $(HTML_PART_FILES) INFO_FILE = ../../info -HTML_REF_FILES = $(XML_REF1_FILES:%.xml=$(HTMLDIR)/%.html) \ - $(XML_REF3_FILES:%.xml=$(HTMLDIR)/%.html) \ - $(XML_REF4_FILES:%.xml=$(HTMLDIR)/%.html) +HTML_REF_FILES = $(XML_REF_FILES:%.xml=$(HTMLDIR)/%.html) HTML_CHAPTER_FILES = $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html) @@ -98,6 +98,7 @@ 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)/* @@ -118,7 +119,9 @@ $(INDEX_TARGET): $(INDEX_SRC) $(APP_FILE) s/%UP_ONE_LEVEL%/..\/..\/..\/doc\/index.html/; \ s/%OFF_PRINT%/pdf\/diameter-$(VSN).pdf/' $< > $@ -depend debug opt: +depend: depend.mk + +debug opt: info: @echo "->Makefile<-" @@ -181,17 +184,13 @@ release_docs_spec: $(LOCAL)docs release_spec: -$(HTMLDIR)/diameter_app.html: diameter_app.xml -$(HTMLDIR)/diameter_compile.html: diameter_compile.xml -$(HTMLDIR)/diameter_debug.html: diameter_debug.xml -$(HTMLDIR)/diameter_dict.html: diameter_dict.xml -$(HTMLDIR)/diameter_intro.html: diameter_intro.xml -$(HTMLDIR)/diameter_run.html: diameter_run.xml -$(HTMLDIR)/diameter.html: diameter.xml -$(HTMLDIR)/diameter_tcp.html: diameter_tcp.xml -$(HTMLDIR)/diameter_transport.html: diameter_transport.xml -$(HTMLDIR)/diameter_soc.html: diameter_soc.xml -$(HTMLDIR)/diameter_sctp.html: diameter_sctp.xml +depend.mk: depend.sed Makefile files.mk + (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 \ diff --git a/lib/diameter/doc/src/depend.sed b/lib/diameter/doc/src/depend.sed new file mode 100644 index 0000000000..10fd56bac0 --- /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>/b rf +/^\([^<]*\)<\/module>/b rf + +/^/!d + +s@.*@$(HTMLDIR)/%FILE%.html: %FILE%.xml@ +q + +:rf +s@@$(HTMLDIR)/\1.html: %FILE%.xml@ +q -- cgit v1.2.3 From a9a922ccfd5361c7c47d4a23cad97ded0bfde8cd Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Thu, 19 May 2011 12:28:37 +0200 Subject: Fix broken doc links. --- lib/diameter/doc/src/diameter_app.xml | 2 +- lib/diameter/doc/src/diameter_dict.xml | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index c2fecce768..d78882c18d 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -236,7 +236,7 @@ the callback module in question has been configured.

Invoked when a transport connection has been lost following a previous -call to peer_up/3.

+call to peer_up/3.

 diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml index 5bc3cab9e4..166c7a8c9d 100644 --- a/lib/diameter/doc/src/diameter_dict.xml +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -76,7 +76,7 @@ A generated hrl also contains defines for the values of defined for AVPs of type Enumerated.

-See diameterc for a +See diameterc for a utility that transforms dictionary files into codec modules needed at runtime.

@@ -248,7 +248,7 @@ 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 DATA TYPES below or a +marker="#DATA_TYPES">DATA TYPES below or a type as defined by a @custom_types tag.

@@ -594,7 +594,7 @@ Values of these types are not parsed by diameter.

SEE ALSO

-diameterc(1)

+diameterc(1)

-- cgit v1.2.3 From 4b94d2f1a48b6701bfe46f344935a379c313fc7d Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Thu, 19 May 2011 14:46:48 +0200 Subject: Trivial depend.sed simplification. --- lib/diameter/doc/src/depend.sed | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/diameter/doc/src/depend.sed b/lib/diameter/doc/src/depend.sed index 10fd56bac0..5973c4586e 100644 --- a/lib/diameter/doc/src/depend.sed +++ b/lib/diameter/doc/src/depend.sed @@ -26,7 +26,7 @@ /^/!d -s@.*@$(HTMLDIR)/%FILE%.html: %FILE%.xml@ +s@@$(HTMLDIR)/%FILE%.html: %FILE%.xml@ q :rf -- cgit v1.2.3 From 7715953ce12be54b1889ebf5af4ba694186370a8 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Fri, 20 May 2011 12:25:28 +0200 Subject: Minor make depend fixes. --- lib/diameter/doc/src/Makefile | 2 +- lib/diameter/src/app/Makefile | 2 +- lib/diameter/src/compiler/Makefile | 2 +- lib/diameter/src/transport/Makefile | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/diameter/doc/src/Makefile b/lib/diameter/doc/src/Makefile index 22e21936fd..1453138cb6 100644 --- a/lib/diameter/doc/src/Makefile +++ b/lib/diameter/doc/src/Makefile @@ -184,7 +184,7 @@ release_docs_spec: $(LOCAL)docs release_spec: -depend.mk: depend.sed Makefile files.mk +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) \ diff --git a/lib/diameter/src/app/Makefile b/lib/diameter/src/app/Makefile index 8985ca4911..6de220d282 100644 --- a/lib/diameter/src/app/Makefile +++ b/lib/diameter/src/app/Makefile @@ -187,7 +187,7 @@ depend: depend.mk # has already been made since it's currently not smart enough to not # force a rebuild of those beams dependent on generated hrls, and this # is a no-no at make release. -depend.mk: depend.sed $(MODULES:%=%.erl) modules.mk Makefile +depend.mk: depend.sed $(MODULES:%=%.erl) Makefile (for f in $(MODULES); do \ sed -f $< $$f.erl | sed "s@/@/$$f@"; \ done) \ diff --git a/lib/diameter/src/compiler/Makefile b/lib/diameter/src/compiler/Makefile index 8512eb515a..3ab76064ac 100644 --- a/lib/diameter/src/compiler/Makefile +++ b/lib/diameter/src/compiler/Makefile @@ -130,7 +130,7 @@ force: depend: depend.mk # Generate dependencies makefile. -depend.mk: ../app/depend.sed $(ERL_FILES) modules.mk Makefile +depend.mk: ../app/depend.sed $(ERL_FILES) Makefile for f in $(MODULES); do \ sed -f $< $$f.erl | sed "s@/@/$$f@"; \ done \ diff --git a/lib/diameter/src/transport/Makefile b/lib/diameter/src/transport/Makefile index 5dc1772796..4b53100fd2 100644 --- a/lib/diameter/src/transport/Makefile +++ b/lib/diameter/src/transport/Makefile @@ -130,7 +130,7 @@ force: depend: depend.mk # Generate dependencies makefile. -depend.mk: ../app/depend.sed $(ERL_FILES) modules.mk Makefile +depend.mk: ../app/depend.sed $(ERL_FILES) Makefile for f in $(MODULES); do \ sed -f $< $$f.erl | sed "s@/@/$$f@"; \ done \ -- cgit v1.2.3 From ce1bb47f364c58822339fa4b05e823aa52b3d7cb Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Fri, 20 May 2011 12:32:34 +0200 Subject: Minor diameter_service fix when sending a diameter_header/avp list plus an example fix. --- lib/diameter/examples/server_cb.erl | 9 +++------ lib/diameter/src/app/.gitignore | 1 + lib/diameter/src/app/diameter_service.erl | 16 +++++----------- 3 files changed, 9 insertions(+), 17 deletions(-) diff --git a/lib/diameter/examples/server_cb.erl b/lib/diameter/examples/server_cb.erl index b8705aedfc..43b8e24b5c 100644 --- a/lib/diameter/examples/server_cb.erl +++ b/lib/diameter/examples/server_cb.erl @@ -74,11 +74,8 @@ handle_request(#diameter_packet{msg = Req, errors = []}, _SvcName, {_, Caps}) {reply, answer(RT, Id, OH, OR)}; %% ... or one that wasn't. 3xxx errors are answered by diameter itself -%% but these are non-3xxx errors for which we must contruct a reply. -%% Returning a packet with the non-[] errors field will cause -%% diameter to add the appropriate result code and Failed-AVPs avps. -%% We just have to return the relevant answer record with any required -%% avps. +%% but these are 5xxx errors for which we must contruct a reply. +%% diameter will set Result-Code and Failed-AVP's. handle_request(#diameter_packet{msg = Req} = Pkt, _SvcName, {_, Caps}) when is_record(Req, diameter_base_RAR) -> #diameter_caps{origin_host = {OH,_}, @@ -91,7 +88,7 @@ handle_request(#diameter_packet{msg = Req} = Pkt, _SvcName, {_, Caps}) 'Origin-Realm' = OR, 'Session-Id' = Id}, - {reply, Pkt#diameter_packet{msg = Ans}}; + {reply, Ans}; %% Should really reply to other base messages that we don't support %% but simply discard them instead. diff --git a/lib/diameter/src/app/.gitignore b/lib/diameter/src/app/.gitignore index 1310a0da6b..d388e61877 100644 --- a/lib/diameter/src/app/.gitignore +++ b/lib/diameter/src/app/.gitignore @@ -2,4 +2,5 @@ /diameter_gen_*.erl /diameter_gen_*.hrl /depend.mk +/diameter.mk diff --git a/lib/diameter/src/app/diameter_service.erl b/lib/diameter/src/app/diameter_service.erl index 82a8d7a994..63b0649dc4 100644 --- a/lib/diameter/src/app/diameter_service.erl +++ b/lib/diameter/src/app/diameter_service.erl @@ -1278,18 +1278,15 @@ send_request({TPid, Caps, App}, Msg, Opts, Caller, SvcName) -> %% make_packet/1 %% %% Turn an outgoing request as passed to call/4 into a diameter_packet -%% record in preparation for a prepare_request callback. There are two -%% cases: a diameter_packet as argument when we're calling call/4 -%% ourselves in order to relay a request or a bare message in case the -%% call came by way of diameter:call/4. +%% record in preparation for a prepare_request callback. make_packet(Bin) when is_binary(Bin) -> #diameter_packet{header = diameter_codec:decode_header(Bin), bin = Bin}; -make_packet(#diameter_packet{msg = [#diameter_header{} | _]} = Pkt) -> - Pkt; +make_packet(#diameter_packet{msg = [#diameter_header{} = Hdr | Avps]} = Pkt) -> + Pkt#diameter_packet{msg = [make_header(Hdr) | Avps]}; make_packet(#diameter_packet{header = Hdr} = Pkt) -> Pkt#diameter_packet{header = make_header(Hdr)}; @@ -1955,6 +1952,7 @@ is_loop(Code, Vid, OH, Avps) -> %% %% Send a locally originating reply. +%% No errors or a diameter_header/avp list. reply(Msg, Dict, TPid, #diameter_packet{errors = Es, transport_data = TD} = ReqPkt) @@ -1964,11 +1962,7 @@ reply(Msg, Dict, TPid, #diameter_packet{errors = Es, incr(send, Pkt, Dict, TPid), %% count result codes in sent answers send(TPid, Pkt#diameter_packet{transport_data = TD}); -%% Simplify the handling of error cases by accepting a list consisting -%% of an answer record followed by failed AVPs to be packed into a -%% Failed-AVP field, either directly or into an AVP field. Only if -%% the message is a tuple-list or record however, not a list -%% with a list of #diameter_header{} and #diameter_avp{}. +%% Or not: set Result-Code and Failed-AVP AVP's. reply(Msg, Dict, TPid, #diameter_packet{errors = [H|_] = Es} = Pkt) -> reply(rc(Msg, rc(H), [A || {_,A} <- Es], Dict), Dict, -- cgit v1.2.3 From 14b63ae11e0a7c3d028ec4ff6e4532705a800157 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Fri, 20 May 2011 12:34:22 +0200 Subject: Various documentation fixes and improvements. Added an introductory chapter to the User's Guide as well as more detailed release notes. --- lib/diameter/doc/src/diameter.xml | 121 +++++++++++------- lib/diameter/doc/src/diameter_app.xml | 182 ++++++++++++++++------------ lib/diameter/doc/src/diameter_dict.xml | 67 +++++----- lib/diameter/doc/src/diameter_examples.xml | 5 + lib/diameter/doc/src/diameter_intro.xml | 58 ++++++++- lib/diameter/doc/src/diameter_transport.xml | 2 +- lib/diameter/doc/src/diameter_using.xml | 3 + lib/diameter/doc/src/notes.xml | 59 ++++++++- 8 files changed, 338 insertions(+), 159 deletions(-) diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index 9774183a2a..36b6cbf0cf 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -415,6 +415,12 @@ eval(F) -> Evaluating an evaluable() E on an argument list A is meant in the sense of eval([E|A]).

+

+Beware of using local funs (that is, fun expressions not of the +form fun Module:Name/Arity) 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.

+ @@ -712,7 +718,7 @@ transport.

Unrecognized options are silently ignored but are returned unmodified by service_info/1,2 and can be referred to +marker="#service_info">service_info/2 and can be referred to in predicate functions passed to remove_transport/2.

@@ -739,7 +745,9 @@ marker="#remove_transport">remove_transport/2.

-Add transport capability to a service. +Add transport capability to a service.

+ +

The service will start a transport process(es) in order to establish a connection with the peer, either by connecting to the peer (connect) or by accepting incoming connection requests @@ -761,10 +769,8 @@ handling of DWR/DWA and required by RFC 3539 as well as for DPR/DPA.

The returned reference uniquely identifies the transport within the scope of the service. -Not that the function returns before a transport connection has been -established.

- -

+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.

@@ -776,7 +782,7 @@ transports.

-call(SvcName, App, Request, Options) -> Answer | {error, Reason} +call(SvcName, App, Request, Options) -> ok | Answer | {error, Reason} Send a Diameter request message. SvcName = service_name() @@ -794,15 +800,19 @@ Send a Diameter request message and possibly return the answer or error.

defined and callbacks to the corresponding callback module will follow as described below and in diameter_app(3). -The call returns either when an answer message is received from the -peer or an error occurs, unless the detach option has been -specified. -If detach is not specified then the form of an Answer is -as returned from a handle_answer/4 or +Unless the detach 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 handle_answer/4 +callback. +In the case of an error, whether or not the error is returned directly +by diameter or from a handle_error/4 -callback.

+callback depends on whether or not the outgoing request is +successfully encoded for transmission from the peer, the cases being +documented below.

If there are no suitable peers, or if @@ -888,7 +898,8 @@ attempt to send the request over the transport.

Note that {error, encode} is the only return value which -guarantees that the request has not been sent over the transport.

+guarantees that the request has not been sent over the +transport.

 @@ -902,9 +913,11 @@ guarantees that the request has not been sent over the transport.

Return a reasonable value for use as Origin-State-Id in -outgoing messages. -The value returned is the number of seconds since 19680120T031408Z -(the first value that can be encoded as a Time()) +outgoing messages.

+ +

+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.

@@ -959,25 +972,7 @@ DPA or timeout.

- - - - - - - -service_info(SvcName) -> Info -Return information about a started service. - -SvcName = service_name() -Info = [{Item, Value}] - - -

-Return information about a started service. -Equivalent to service_info(SvcName, all).

- - + @@ -992,7 +987,7 @@ Equivalent to service_info(SvcName, all).

-Return specific information about a started service.

+Return information about a started service.

 @@ -1018,17 +1013,36 @@ Return the list of started services.

session_id(Ident) -> OctetString() -Return a value for a Session-Id AVP +Return a value for a Session-Id AVP. Ident = DiameterIdentity()

-Return a value for a Session-Id AVP. +Return a value for a Session-Id AVP.

+ +

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.

+ + + + + + +start() -> ok | {error, Reason} +Start the diameter application. + +

+Start the diameter application.

+ +

+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 start/0 explicitly.

+ @@ -1036,7 +1050,7 @@ the message containing the returned value will be sent.

start_service(SvcName, Options) -> ok | {error, Reason} -Start a Diameter service +Start a Diameter service. SvcName = service_name() Options = [service_opt()] @@ -1044,7 +1058,9 @@ the message containing the returned value will be sent.

-Start a diameter service. +Start a diameter service.

+ +

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. @@ -1055,10 +1071,25 @@ marker="#add_transport">add_transport/2.

 + + +stop() -> ok | {error, Reason} +Stop the diameter application. + +

+Stop the diameter application.

+ +

+

+ + + + + stop_service(SvcName) -> ok | {error, Reason} -Stops a Diameter service. +Stop a Diameter service. SvcName = service_name() Reason = term() @@ -1075,7 +1106,7 @@ Stop a diameter service.

subscribe(SvcName) -> true -Subscribe to event messages from a service. +Subscribe to event messages. SvcName = service_name() @@ -1095,7 +1126,7 @@ that does not yet exist.

unsubscribe(SvcName) -> true - +Unsubscribe to event messages. SvcName = service_name() diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index d78882c18d..fc359b9d1d 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -47,23 +47,12 @@ 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 -specification file whose format is documented in +dictionary file whose format is documented in diameter_dict(4) while the callback module is documented here. The callback module implements the Diameter application-specific functionality of a service.

- -

-The arities of the callback functions below assume no extra arguments. -All functions will also be passed any extra arguments configured with -the callback module itself when calling diameter:start_service/2 -and, except for peer_up, peer_down and handle_request, any extra -arguments passed to diameter:call/4.

- -

A callback module must export all of the functions documented below. The functions themselves are of three distinct flavours:

@@ -72,8 +61,8 @@ The functions themselves are of three distinct flavours:

peer_up/3 and -peer_down/3 signal the attainment -or loss of communicativity with a Diameter peer.

+peer_down/3 signal the +attainment or loss of connectivity with a Diameter peer.

 @@ -98,6 +87,17 @@ is called in response to an incoming Diameter request message.

+ +

+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 diameter:start_service/2 +and, for the call-specific callbacks, any extra arguments passed to +diameter:call/4.

+ + @@ -131,8 +131,8 @@ 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 in the dictionary file) and whose tail is a list of -{FieldName, FieldValue} pairs.

+prefix specified in the relevant dictionary file) and whose tail is a +list of {FieldName, FieldValue} pairs.

A third representation allows a message to be specified as a list @@ -144,7 +144,8 @@ as directed by the return value of a 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: messages are sent exactly as specified.

+question (since relays agents must handle arbitrary request): messages +are sent exactly as specified.

 @@ -153,8 +154,8 @@ question: messages are sent exactly as specified.

A container for incoming and outgoing Diameters message that's passed through encode/decode and transport. -Defined in diameter.hrl. -Fields should not be altered except as documented.

+Fields of a packet() record should not be set in return values except +as documented.

peer_ref() = term() @@ -243,11 +244,11 @@ call to peer_up/3.

 -Mod:pick_peer(Cands, Reserved, SvcName, State) +Mod:pick_peer(Candidates, Reserved, SvcName, State) -> {ok, Peer} | {Peer, NewState} | false Select a target peer for an outgoing request. -Cands = [Peer] +Candidates = [peer()] Peer = peer() | false SvcName = service_name() State = NewState = state() @@ -266,11 +267,9 @@ marker="diameter#start_service">diameter:start_service/2.

The candidate peers list will only include those which are selected by any filter option specified in the call to -diameter:call/4.

- +diameter:call/4, and only +those which have indicated support for the Diameter application in +question.

The return values false and {false, State} are @@ -326,13 +325,14 @@ A returned packet() should set the request to be encoded in its to pass information to the transport module. Extra arguments passed to diameter:call/4 can be used to -communicate transport data to the callback.

- -

-Any returned packet() can set the header field to a +communicate transport data to the callback. +A returned packet() can also set the header field to a diameter_header record in order to specify values that should -be preserved in the outgoing request. -A specified message_length is ignored.

+be preserved in the outgoing request, although this should typically +not be necessary and allows the callback to set header values +inappropriately. +A returned length, cmd_code or application_id is +ignored.

Returning {discard, Reason} causes the request to be aborted @@ -361,7 +361,7 @@ Invoked to return a request for encoding and retransmission. Has the same role as prepare_request/3 in the case that a peer connection is lost an an alternate peer selected but the -Packet passed to prepare_retransmit/3 is as returned by +argument packet() is as returned by the initial prepare_request/3.

@@ -391,10 +391,12 @@ discarded}.

Invoked when an answer message is received from a peer. The return value is returned from the call to diameter:call/4 for which the -callback takes place.

+callback takes place unless the detach option was +specified.

-The decoded answer record is in the msg field of Packet, +The decoded answer record is in the msg field of the argument +packet(), the undecoded binary in the packet field. Request is the outgoing request message as was returned from prepare_request/3 or @@ -414,8 +416,10 @@ By default, an incoming answer message that cannot be successfully decoded causes the request process in question to fail, causing the relevant call to diameter:call/4 -to return {error, failure}. -There is no handle_error/4 callback in this case. +to return {error, failure} (unless the detach option was +specified). +In particular, there is no handle_error/4 callback in this +case. Application configuration may change this behaviour as described for diameter:start_service/2.

@@ -440,7 +444,8 @@ 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 diameter:call/4 for which the -callback takes place.

+callback takes place (unless the detach option was +specified).

Reason timeout indicates that an answer message has not been @@ -449,8 +454,7 @@ Reason failover 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 pick_peer/4 -callback returned false. -

+callback returned false.

@@ -463,40 +467,33 @@ callback returned false. Packet = packet() SvcName = term() Peer = peer() -Action = Reply | NoReply | Relay | {eval, Action, ContF} +Action = Reply | {relay, Opts} | discard | {eval, Action, ContF} Reply = {reply, message()} - | {protocol_error, ResultCode} -NoReply = discard -Relay = {relay, Opts} -Opts = list() + | {protocol_error, 3000..3999} +Opts = diameter:call_opts() ContF = diameter:evaluable() -ResultCode = 3000..3999

-Invoked when a request message is received from a peer.

- -

+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 diameter:start_service/2) is determined by the Application Identifier in the header of the -incoming Diameter request message, the selected module being the one +incoming request message, the selected module being the one whose corresponding dictionary declares -itself as defining the application in question, or the RFC 3588 relay -application if the specific application is unsupported but the relay -application has been advertised.

+itself as defining either the application in question or the Relay +application.

-The packet() in which the incoming request is communicated has the -following signature.

+The argument packet() has the following signature.

#diameter_packet{header = #diameter_header{}, avps = [#diameter_avp{}], msg = record() | undefined, - errors = [integer() | {integer(), #diameter_avp{}}], + errors = ['Unsigned32'() | {'Unsigned32'(), #diameter_avp{}}], bin = binary(), transport_data = term()} @@ -509,12 +506,16 @@ in diameter_dict(4).

-The errors field specifies any non-protocol errors that were -encountered in decoding the request and can be returned in a -reply tuple to have diameter set the Result-Code and Failed-AVP -AVP's appropriately. -The list is empty if the request has been received in the relay -application.

+The errors 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 errors list is empty if the request has been received in +the relay application.

The transport_data field contains an arbitrary term passed into @@ -525,34 +526,59 @@ sent back to the transport process unless another value is explicitly specified.

-The semantics of each of the possible return values are as follows. -(TODO: more.)

+The semantics of each of the possible return values are as follows.

-{reply, Answer} +{reply, message()}

Send the specified answer message to the peer.

 -{relay, Opts} +{protocol_error, 3000..3999}

-Relay a request to another peer.

- - -{protocol_error, ResultCode} - +Send an answer message to the peer containing the specified +protocol error. +Equivalent to

+ +{reply, ['answer-message' | Avps] +

-Send an answer message to the peer containing the specified 3xxx -protocol error.

+where Avps sets the Origin-Host, Origin-Realm, the specified +Result-Code and (if the request sent one) Session-Id AVP's.

-RFC 3588 mandates that only answers with a 3xxx series +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 {protocol_error, ResultCode} -tuple will cause the request process in question to fail.

+Returning a non-3xxx value in a protocol_error tuple +will cause the request process in question to fail.

+ + +{relay, Opts} + +

+Relay a request to another peer. +The appropriate Route-Record AVP will be added to the relayed request +by diameter and pick_peer/4 +and prepare_request/3 +callback will take place just as if diameter:call/4 had been called +explicitly. +However, returning a relay tuple also causes the End-to-End +Identifier to be preserved in the header of the relayed request as +required by RFC 3588.

+ +

+The returned Opts should not specify detach and +the handle_answer/4 +callback following from a relayed request must return its first +argument, the diameter_packet record containing the answer +message. +Note that the extra option can be specified to supply arguments +that can distinguish the relay case from others if so desired, +although the form of the request message may be sufficient.

 discard @@ -565,14 +591,14 @@ Discard the request.

Handle the request as if Action has been returned and then -evaluate the evaluable() ContF in the request process.

+evaluate ContF in the request process.

Note that diameter will respond to protocol errors in an incoming -request without invoking the a handle_request/3 callback.

+request without invoking handle_request/3.

 diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml index 166c7a8c9d..a87f59bad5 100644 --- a/lib/diameter/doc/src/diameter_dict.xml +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -48,37 +48,41 @@ 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 -FILE FORMAT below.

+FILE FORMAT below. +Users add support for their specific applications by creating +dictionary files, compiling them to Erlang modules using +diameterc and configuring the +resulting dictionaries modules on a service.

-The codec generation also results in an hrl that defines records +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. +records being what a user of the diameter application sends and receives. +(Modulo other available formats as discussed in diameter_app(3).) These records and the underlying Erlang data types corresponding to Diameter data formats are discussed in MESSAGE RECORDS and DATA TYPES respectively.

- - - - -

-The diameter application defines the base application of RFC 3588 in -the file diameter_gen_base_rfc3588.dia, and -this is the only application that diameter itself has any specific -knowledge of. -Other applications are callback modules configured for an application -as far as diameter is concerned.

- -

-A generated hrl also contains defines for the values of defined for +marker="#DATA_TYPES">DATA TYPES respectively. +The generated hrl also contains defines for the possible values of AVPs of type Enumerated.

-See diameterc for a -utility that transforms dictionary files into codec modules needed -at runtime.

+The diameter application includes three dictionary modules +corresponding to applications defined in section 2.4 of RFC 3588: +diameter_gen_base_rfc3588 for the Diameter Common Messages +application with application identifier 0, +diameter_gen_accounting for the Diameter Base Accounting +application with application identifier 3 and +diameter_gen_relaythe 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.

@@ -89,7 +93,7 @@ at runtime.

FILE FORMAT

-A specification file consists of distinct sections. +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. @@ -223,7 +227,7 @@ The section content is empty.

Can occur 0 or more times (with different values of Mod) but all dictionaries should typically inherit RFC3588 AVPs from -diameter_gen_base_rfc3588.

+diameter_gen_base_rfc3588.

Example:

@@ -263,7 +267,8 @@ Requested-Information 353 Enumerated V

Note that the P flag has been deprecated by the Diameter Maintenance -and Extensions Working Group of the IETF.

+and Extensions Working Group of the IETF: diameter will set the P flag +to 0 as mandated by the current draft standard.

@@ -446,7 +451,7 @@ as values of the types defined here. Values are passed to diameter:call/4 in a request record when sending a request, returned in a resulting -answer record and passed to a diameter_app(3) handle_request callback upon reception of an incoming request.

@@ -476,8 +481,8 @@ Grouped() = record()

On encode, an OctetString() can be specified as an iolist(), excessively large floats (in absolute value) are equivalent to -infinity or '-infinity' and excessively large integers result in -encode failure. +infinity or '-infinity' and excessively large integers +result in encode failure. The records for grouped AVPs are as discussed in the previous section.

@@ -583,7 +588,7 @@ QoSFilterRule() = OctetString()

-Values of these types are not parsed by diameter.

+Values of these types are not currently parsed by diameter.

@@ -594,7 +599,9 @@ Values of these types are not parsed by diameter.

SEE ALSO

-diameterc(1)

+diameterc(1), +diameter(3), +diameter_app(3)

diff --git a/lib/diameter/doc/src/diameter_examples.xml b/lib/diameter/doc/src/diameter_examples.xml index 344b237866..966d1f1eee 100644 --- a/lib/diameter/doc/src/diameter_examples.xml +++ b/lib/diameter/doc/src/diameter_examples.xml @@ -36,5 +36,10 @@ under the License. +

+To be written. +Example code can be found in the diameter application's +examples subdirectory.

+ diff --git a/lib/diameter/doc/src/diameter_intro.xml b/lib/diameter/doc/src/diameter_intro.xml index 0009b2b77d..ef08002a8b 100644 --- a/lib/diameter/doc/src/diameter_intro.xml +++ b/lib/diameter/doc/src/diameter_intro.xml @@ -36,10 +36,60 @@ under the License.

The diameter application is an implementation of the Diameter protocol as defined by RFC 3588. -It supports arbitrary Diameter applications by allowing a client to -specify the commands and AVP's to be supported and has support for -implementing all roles defined in the RFC: client, server and agent. -

+It supports arbitrary Diameter applications by way of a +dictionary 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.

+ +

+A Diameter peer is implemented by configuring a service and +one or more transports using the interface module +diameter. +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: diameter_tcp and diameter_sctp for transport over TCP +(using gen_tcp) and SCTP (using gen_sctp) respectively. +Other transports can be provided by any module that implements +diameter's transport +interface.

+ +

+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.

+ +

+Each Diameter application defined on a service is configured with a +callback module that implements the application interface 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.

+ +

+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 specification file using the diameterc utility. +Dictionaries for the RFC 3588 Diameter Common Messages, Base +Accounting and Relay applications are provided by the diameter +application.

 diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml index be1bb2c56e..37cc871e75 100644 --- a/lib/diameter/doc/src/diameter_transport.xml +++ b/lib/diameter/doc/src/diameter_transport.xml @@ -33,7 +33,7 @@ under the License. diameter_transport -Diameter transport behaviour. +Diameter transport interface. diff --git a/lib/diameter/doc/src/diameter_using.xml b/lib/diameter/doc/src/diameter_using.xml index 737a0a3941..809b76bdf3 100644 --- a/lib/diameter/doc/src/diameter_using.xml +++ b/lib/diameter/doc/src/diameter_using.xml @@ -35,6 +35,9 @@ under the License. +

+To be written.

+ diff --git a/lib/diameter/doc/src/notes.xml b/lib/diameter/doc/src/notes.xml index 8fdb88749e..eafddd7d1e 100644 --- a/lib/diameter/doc/src/notes.xml +++ b/lib/diameter/doc/src/notes.xml @@ -40,8 +40,65 @@ first.

diameter 0.9

-First OTP release.

+Initial release of the diameter application.

+

+Known issues or limitations:

+ + + + +

+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 handle_request/3 +callback can return a relay 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.

+ + + + +

+There is some asymmetry in the treatment of messages sent as +diameter_header/avp 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.

+ + + +

+The User's Guide is currently quite thin. +The introductory chapter followed by the examples (in the application +examples 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.

+ + + +

+The function diameter:service_info/2 +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.

+ + + + + +

+See Standards Compliance for +standards-related issues.

-- cgit v1.2.3 From f2bff722fdb93cf021d9b80f383046cf36435ff3 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Fri, 20 May 2011 13:28:59 +0200 Subject: Remove undocumented interface functions plus comment fix. --- lib/diameter/include/diameter.hrl | 2 +- lib/diameter/src/app/diameter.erl | 24 +----------------------- 2 files changed, 2 insertions(+), 24 deletions(-) diff --git a/lib/diameter/include/diameter.hrl b/lib/diameter/include/diameter.hrl index 8bd1ad1e51..0fa7fd406f 100644 --- a/lib/diameter/include/diameter.hrl +++ b/lib/diameter/include/diameter.hrl @@ -110,7 +110,7 @@ %% The diameter service and diameter_apps records are only passed %% through the transport interface when starting a transport process, %% although typically a transport implementation will (and probably -%% should) only be interested diameter_service.host_ip_address. +%% should) only be interested host_ip_address. -record(diameter_service, {pid, diff --git a/lib/diameter/src/app/diameter.erl b/lib/diameter/src/app/diameter.erl index 5f2ab82475..2f721421d8 100644 --- a/lib/diameter/src/app/diameter.erl +++ b/lib/diameter/src/app/diameter.erl @@ -35,7 +35,6 @@ %% Information. -export([services/0, - service_info/1, service_info/2]). %% Start/stop the application. In a "real" application this should @@ -44,12 +43,6 @@ -export([start/0, stop/0]). -%% Backwards compatibility. --export([add_connector/2, - add_listener/2, - remove_connector/2, - remove_listener/2]). - -include("diameter_internal.hrl"). -include("diameter_types.hrl"). @@ -109,7 +102,7 @@ services() -> [Name || {Name, _} <- diameter_service:services()]. %%% -------------------------------------------------------------------------- -%%% service_info/[12] +%%% service_info/2 %%% -------------------------------------------------------------------------- -spec service_info(service_name(), atom() | [atom()]) @@ -118,9 +111,6 @@ services() -> service_info(SvcName, Option) -> diameter_service:info(SvcName, Option). -service_info(SvcName) -> - service_info(SvcName, all). - %%% -------------------------------------------------------------------------- %%% add_transport/3 %%% -------------------------------------------------------------------------- @@ -133,12 +123,6 @@ add_transport(SvcName, {T, Opts} = Cfg) when is_list(Opts), (T == connect orelse T == listen) -> diameter_config:add_transport(SvcName, Cfg). -add_listener(SvcName, Opts) -> - add_transport(SvcName, {listen, Opts}). - -add_connector(SvcName, Opts) -> - add_transport(SvcName, {connect, Opts}). - %%% -------------------------------------------------------------------------- %%% remove_transport/2 %%% -------------------------------------------------------------------------- @@ -149,12 +133,6 @@ add_connector(SvcName, Opts) -> remove_transport(SvcName, Pred) -> diameter_config:remove_transport(SvcName, Pred). -remove_listener(SvcName, Pred) -> - remove_transport(SvcName, {listen, Pred}). - -remove_connector(SvcName, Pred) -> - remove_transport(SvcName, {connect, Pred}). - %%% -------------------------------------------------------------------------- %%% # subscribe(SvcName) %%% -- cgit v1.2.3