Issue 4 - Dialogic
Contents
1. Help Screen DSI DTU Diameter Test Utility Release 1 01 Part of the Dialogic R DSI Development Package Copyright C 2012 Dialogic Inc All Rights Reserved Syntax dtu jar m lt gt dmr lt gt dsth lt gt dstr lt gt numreq maxin lt gt maxssn lt gt traceoff DTU Sends Diameter Session Requests Example java jar dtu jar numreq1000 Options m DTU Module Id Sets the module id for DTU dmr DMR Module Id Sets the module id for the Diameter Module DMR dsth Des dstr Des Set the Des Host Realm ination Host and Realm addresses ct ct ct numreq Number of requests Sets the total number of Update Location Requests to send maxin Max sessions in flight Sets the maximum number of session active at once maxssn Max session Sets the maximum number of session ids to use basessn Base session id Sets the base session id to use default 0 nc NetworkContext Sets the Network Context value mode Mode Sets the mode for the sessions to use Send ULR Set mode to 0 default Send CCR Set mode to 1 traceoff Turn Trace Off Typical Output DSI DTU Diameter Test Utility Release 1 01 Part of the Dialogic R DSI Development Package Copyright C 2012 Dialogic Inc All Rights Reserved 26 6 1 2 6 2 Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 DTU module id Oxld DMR module id 0x74 1 MaxSsnNum 1024 MaxI2. DSI gctload In another console window start the test application BIN dmrapitest DMR API Test Application Result Code 2000 Origin Host origin host avp Origin Realm origin realm avp Accuracy Fulfilment Indicator 0 Vendor ID 67 Feature List 45 Feature List ID 56 C Example Overview The following sections give a more detailed overview of the C Functional API as used in the example code supplied Generating a Diameter Session Step 1 Generate a diameter context The diameter context object is used to store and initialize factory and encoder objects required by the user application This is demonstrated in the DMR API TEST build dmr context function within the supplied example Step 2 Register a command with the context In order to define which commands are valid with the diameter context the required requests and answer commands need to be registered into the context object You can also set the module ids for the application and Diameter module here too The function DMR API TEST build dmr context mentioned in step 1 also shows the commands being registered Step 3 Create and populate the session request object This step builds up a structured form of the request object which is to be encoded This uses methods from the Diameter Command Specific API The creation of a request object is shown in the DMR API TEST build dmr session open req function An example of this then be
3. and files Directory Files Detail 32 dmrapi lib The libraries contains the DMR Access API dmrCmds lib and the Diameter command specific functionality appropriate for the supported interfaces and commands It also includes the encoding support used by other parts of the library INC dmtrcmd Supplied include Include files to support building against the INC dmtrcmd r c3588 files Diameter Commands INC dmtrcmd rfc4006 etc UPD SRC DMRAPI dmr_api_tests cpp Sample code example to demonstrate use of the API UPD RUN DMRAPI system txt Simple system configuration file for use with the source code example Building and running the example code The sample API code in the file dmr_api_tests cpp provides a simple application that sends a single Diameter command request to the s7_log utility and then simulates a reply by sending a Diameter command answer to itself and displaying it The example test application can be built together with the other parts of the User Development Package by calling the makeall sh script in the UPD SRC sub directory cd opt DSI UPD SRC makeall sh To run the example application the user can make use of the supplied simple application loop back system configuration in the UPD RUN DMRAPI directory Change to the appropriate directory and start the message passing environment 29 Section 7 Example C Applications 7 3 7 3 1 30 cd opt DSI UPD RUN DMRAPI opt
4. are derived from a definition dictionary to permit extensions and modifications to be supported For the Java these are packaged in com dialogic signaling diameter lt specname gt For the C these use the namespace com dialogic signaling diameter lt specname gt For example com dialogic signaling diameter rfc3588 or com dialogic signaling diameter rfc3588 Shown in Figure 4 is a simplified overview of the class heirachy of the Diameter Command API with a single command UpdateLocationRequest shown Each specific command request or answer required for an application should be registered against the DmrContext object being used GroupedAvp IAvpList IDiametercommand AN OctetStringAvp A Utf8StringAvp ProxylnfoAvp ProxyHostAvp UpdateLocationRequest Figure 4 Diameter Command API Static Class Hierarchy IDiameterCommand This is an interface representing a Diameter Command This class includes attributes for the Diameter Command Header such as Command Code Hop by Hop Id it extends from IAvpList 10 Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 IAvpList Abstract interface which stores a list one or more AVPs IAvp Abstract class that models a single AVP object GroupedAvp Models an AVP which contains one more other AVPs OctetStringAvp Standard primitive AVP representing an array of octet data Other primitive AVP types e
5. den media The following User Documentation relates to the use of the Dialogic DSI Diameter Stack e Dialogic DSI Diameter Stack Diameter Functional API Manual e Dialogic DSI Components Software Environment Programmer s Manual e Dialogic DSI SIGTRAN Stack SCTP Programmer s Manual Section 2 Stack Overview 2 Stack Overview Figure 1 There are a number of components supplied as part of the Dialogic DSI Diameter Stack These include APIs for interfacing to the Dialogic message passing environment in general as well as APIs specific for use with the Diameter Module within the Dialogic DSI Diameter Stack The User Application will be built using the supplied Functional APIs described in this manual These APIs facilitate the generation and handling of messages sent to or received from the Diameter Module The Diameter Module DMR implements the Diameter Base Protocol offering a message based API to the User Application to control Diameter sessions and is discussed further in the DMR Programmer s Manual The Diameter Module can be configured via messages using a Management Module This Management Module may be the s7 mgt utility included within the DSI Development Package or optionally it may be replaced by a User generated module The Diameter Module interfaces to the network via the SCTPN module to send the appropriate payload messages and for control of SIGTRAN associations Application Module b Message W
6. into a GCT message The context object also contains the encoder method to format the DmrSessionRegq into a GCT message Step 6 Send the GCT Message Takes the GCT message and sends it to the DSI Diameter Module Building the session request object The diameter context object has factory methods that allow a session request object to be built The request can then have the Network Context Session Id and Primitive type values set as appropriate to the request as shown below DmrSessionReq req new DmrSessionReq req primitiveType req primitiveType OPEN req diameterCommand UpdateLocationRequestFactory buildUpdateLocationRequest dtuConfig req sessionId sessionId return req As shown above the example method UpdateLocationRequestFactory includes calls to create a new Update Location Request This object has a number of methods one to add each of the AVPs included in the request An example of this is shown below 13 Section 4 Functional API Tllustration 4 2 14 UpdateLocationRequest ulr new UpdateLocationRequest ulr addUlrFlagsAvp new UlrFlagsAvp long 0x1234 ulr addUserNameAvp new UserNameAvp UserName return ulr Handling a received Diameter Request Step 1 dmrContext new DmrContext Step 2 dmrContext registerDiameterCommand UpdateLocationRequest class dmrContext registerDiameterCommand UpdateLocationAnswer class dmrContext setDmrTaskId config DstMID dmrContext set
7. offers similar message based interfaces and management capabilities to those offered for other SS7 and SIGTRAN protocol layers DMR uses the services provided by the SCTP layer of the Dialogic DSI SIGTRAN Stack for the transfer of messages between Diameter Peers Dialogic s DMR Functional API is for use within user applications interfacing with the DMR module The messages defined by DMR as part of its user interface contain network formatted Diameter commands The functional API allows for the easy encoding and decoding of these DMR messages to support quick application development and maintenance This manual is intended for use by Application Developers who intend to write or maintain applications which use the Functional API for the Dialogic DSI Diameter Stack It provides an overview of the Functional API and other related software components Users needing to configure and maintain the Diameter Module DMR should refer to the Diameter Programmer s Manual Applicability This manual is applicable to the following software Dialogic DSI Development Package for Solaris Release 5 3 1 or later Java API only check for availability of C API Dialogic DSI Development Package for Linux Release 6 6 1 or later Related Documentation Current software and documentation supporting Dialogic DSI components is available at http www dialogic com support helpweb signaling Video tutorials are available at http www dialogic com
8. requests and answers embedded within these messages This class may be considered the top level class for your application interfacing with the Diameter module The DmrContext class is also used to set up and define settings and parameters appropriate to a Diameter user This means it can be created once and used multiple times to encode or decode Diameter Command Requests and Answers using the UserApi class it contains The DmrContext class includes a method to permit Diameter Command API classes to be registered with that context object This then permits later calls to the UserAPI encode decode methods of a DmrContet object to be made Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 DmrContext encode encode decode decode calculateLength calculateLength Figure 3 DmrContext Static Class Hierarchy 3 4 2 DMR UserApi and Message Encoders This class provides access methods for the encoders and decoder classes that perform the conversion between instances of the message classes and a well formed GCT message DMRSessionIndEncoder Provides encode decode and length calculation for DMR Session Indication GCT messages DMRSessionReqEncoder Provides encode decode and length calculation for DMR Session Indication GCT messages Section 3 Component Overview 3 5 Diameter Command API This component provides the classes to encode and decode specific Diameter commands and AVPs These
9. Dialegic Dialogic DSI Diameter Stack Diameter Functional API Manual September 2013 www dialogic com Section 1 Introduction Copyright and Legal Notice Copyright 2012 2013 Dialogic Inc All Rights Reserved You may not reproduce this document in whole or in part without permission in writing from Dialogic Inc at the address provided below All contents of this document are furnished for informational use only and are subject to change without notice and do not represent a commitment on the part of Dialogic Inc and its affiliates or subsidiaries Dialogic Reasonable effort is made to ensure the accuracy of the information contained in the document However Dialogic does not warrant the accuracy of this information and cannot accept responsibility for errors inaccuracies or omissions that may be contained in this document INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH DIALOGIC PRODUCTS NO LICENSE EXPRESS OR IMPLIED BY ESTOPPEL OR OTHERWISE TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT EXCEPT AS PROVIDED IN A SIGNED AGREEMENT BETWEEN YOU AND DIALOGIC DIALOGIC ASSUMES NO LIABILITY WHATSOEVER AND DIALOGIC DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY RELATING TO SALE AND OR USE OF DIALOGIC PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE MERCHANTABILITY OR INFRINGEMENT OF ANY INTELLECTUAL PROPERTY RIGHT OF A THIRD PARTY Dialogic products are not intend
10. SrcTaskId config SrcMID Step 3 GctMsg rxedMsg GctLib receive Config SrcMID Step 4 if rxedMsg getType dmrContext MsgType DMR MSG SESSION IND getValue DmrSessionInd decodedInd dmrContext UserApi DmrSessionIndEncoder decode gctmsg Step 5 if ind DiameterCommand getCommandCode UpdateLocationRequest StandardCommandCode UpdateLocationRequest ulr UpdateLocationRequest ind DiameterCommand try t System out println Command code matches System out println ulr getOriginHostAvp getString System out println ulr getOriginRealmAvp getString catch UnsupportedEncodingException ex System out println Failed to recover AVP ex toString Step 1 Generate a diameter context The diameter context object is used to store and initialize factory and encoder decoder objects required by the user application Step 2 Register a command with the context In order to define which commands are valid with the diameter context the required requests and answer commands need to be registered into the Context Object Step 3 Receive the GCT message This call will block until a message for the requested module ids is returned 4 3 4 3 1 4 3 2 4 3 3 Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 Step 4 Decode the Session Indication As with encoding functionality the diameter context object provides methods which will decode th
11. T INDICATION 3006 DIAMETER APPLICATION UNSUPPORTED 3007 DIAMETER INVALID HDR BITS 3008 DIAMETER INVALID AVP BITS 3009 DIAMETER UNKNOWN PEER 3010 DIAMETER AUTHENTICATION REJECTED 4001 DIAMETER OUT OF SPACE 4002 DIAMETER ELECTION LOST 4003 DIAMETER AVP UNSUPPORTED 5001 DIAMETER UNKNOWN SESSION ID 5002 DIAMETER AUTHORIZATION REJECTED 5003 DIAMETER INVALID AVP VALUE 5004 DIAMETER MISSING AVP 5005 DIAMETER RESOURCES EXCEEDED 5006 DIAMETER CONTRADICTING AVPS 5007 17 Section 4 Functional API Tllustration 4 5 4 6 18 Result Code Mnemonic Value DIAMETER AVP NOT ALLOWED 5008 DIAMETER AVP OCCURS TOO MANY TIMES 5009 DIAMETER NO COMMON APPLICATION 5010 DIAMETER UNSUPPORTED VERSION 5011 DIAMETER UNABLE TO COMPLY 5012 DIAMETER INVALID BIT IN HEADER 5013 DIAMETER INVALID AVP LENGTH 5014 DIAMETER INVALID MESSAGE LENGTH 5015 DIAMETER INVALID AVP BIT COMBO 5016 DIAMETER NO COMMON SECURITY 5017 Error Command The Diameter Command API includes the ErrorCommand class to represent Error notifications sent in response to Command Requests These are built encoded and decoded in the same way as other command objects with the exception that they do not need to be registered against the DmrContext object The addresultCodeAvp method can be used to set the result code on an Error Command to send For received Error Commands they can be checked to confirm they are really ErrorCommand obje
12. a aen 7 Figure 3 DmrContext Static Class Hi rarChy gt ur 2c c n lal nay n ayas W yay E kaya sk y Wa YA kaya ya v ak WW WA YA eW Y 9 Figure 4 Diameter Command API Static Class Hierarchy hkh N Wlkkl kk kk kaka kk ka 10 Figure 5 DMS Class generation and encOderS kk lak keka ee ka sen ee a na k je anak aa nekine 20 Figure 6 DTU DTR Message Sequence Chart Mode 0 Update Location hkAh AKC AKU Ch Cllkk kez 23 Figure 7 DTU DTR Message Sequence Chart Mode 1 Credit Control seen 24 Tables Table 1 Result Code Valles coerente xxx x exte in xx cow eR qe Mrd ED rd Pede Kar eg 17 Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 1 Introduction 1 1 1 2 The Dialogic DSI Diameter Stack is a software implementation of the IETF Diameter Base Protocol which is intended to facilitate development of user applications that interface to LTE and IMS networks for the implementation of services in the areas of Mobility Online Charging and Offline Charging The Dialogic DSI Diameter Stack includes a message based binary Diameter Module a Functional API Library and utility components and header files for use when developing a User Application Dialogic s Diameter Module DMR implements the Diameter Base Protocol offering a message based API to the User Application to control Diameter sessions DMR is a member of the family of Dialogic DSI Components and
13. a n n nan d Se k n ke a gund k Z a w mak a N AWE S SUN EEE W NEW DEKAR 3 Component Overview k kK jkkk kkkdkdkkkkkkkkkkakakaa anak axak kanan nanna nn nanna mua un nau nana uan nuna au uan 3 1 Java Development Package CoOmpOne nS kakakkskkka eka a ka k aa earn nna rna nna nan 3 2 C Development Package Components sse eene kaka kak kk aka aka ka 3 3 Message Passing Environment GCTLIB API kKK Khk KkW lk kk kk eee kaka kaka nenne 3 4 DMR Access APLI iiissassaasasisasssasa kk 844 4 84 53 84 4 ARENA RA RA 8 4 8 8 8 8 5 8 8 4 8 8 5 8 E EENE EENE 3 4 1 Dimr Context I BB gg 3 4 2 DMR UserApi and Message Encoders sssssssssseeneneneneen nene 3 5 Diameter Command API siisii tirisan alan n akna n ninan nank nda dna amid Ru Re Re Reels eiie 4 Functional API Illustration esee eese nnne anak anan anan an anunananananun suus uu ua au 4 1 Generating a Diameter Session i n re erbe et eg eov use FA K k ark kar ERKE E Ar A E WE ARA W RA 4 1 1 Building the session request ODj ecb k hAWZ ELEkEkkkkkk kk ee eee kk kaka kaka kaka kaka 4 2 Handling a received Diameter Request kMKk k AQ Q U Cskkkk teeter renee neta eee eee nennen nennen nenne 43 Zan lT TT ee eee Rad 4 3 1 Adding and Retrieving al AVP iraisser ker qnnm ki kad kay gie dim ka eyaz ka s 4 3 2 Adding an AVP St ss kis xiscinis nenanaamisadnan das
14. art Mode 1 Credit Control Syntax java jar dtu m lt modid gt dmr lt dmr modid gt dsth lt dest host gt dstr lt dest realm gt numreq lt num requests gt maxin max in flight maxssn lt max session number basessn base session id nc Network Context mode Mode traceoff Parameters m modid Set to define the module id used by DTU If not set then DTU will default to Oxid dmr lt dmr modid gt Set to define the module id used by the Diameter module DMR If not set then DTU will default to 0x74 24 Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 dsth dest host dstr dest realm Set the destination host and realm values to be used numreq lt num requests Defines the total number of requests to send maxin max in flight Set to limit the number of requests that will be outstanding at any one time maxssn max session number Set to define the maximum session number to use basessn base session number Set to define the base session number to use nc Network Context Set to define the Network Context value to use defaults to O mode Mode value Set to 0 for Update Location Request S6a example session message flow This mode is also the default mode Set to 1 for Credit Control Ro example session message flow traceoff Disable message tracing 25 Section 6 Example Java Applications 6 1 1 Command line output
15. censes required to implement any concepts or applications and does not condone or encourage any intellectual property infringement and disclaims any responsibility related thereto These intellectual property licenses may differ from country to country and it is the responsibility of those who develop the concepts or applications to be aware of and comply with different national license requirements Dialogic Dialogic Pro Dialogic Blue Veraz Brooktrout Diva BorderNet PowerMedia ControlSwitch I Gate Mobile Experience Matters Network Fuel Video is the New Voice Making Innovation Thrive Diastar Cantata TruFax SwitchKit Eiconcard NMS Communications SIPcontrol Exnet EXS Vision inCloud9 NaturalAccess and Shiva among others as well as related logos are either registered trademarks or trademarks of Dialogic Inc and its affiliates or subsidiaries Dialogic s trademarks may be used publicly only with permission from Dialogic Such permission may only be granted by Dialogic s legal department at 6700 de la Cote de Liesse Road Suite 100 Borough of Saint Laurent Montreal Quebec Canada H4T 2B5 Any authorized use of Dialogic s trademarks will be subject to full respect of the trademark guidelines published by Dialogic from time to time and any use of Dialogic s trademarks requires proper acknowledgement The names of actual companies and products mentioned herein are the trademarks of their respective owners This document discusses one
16. cts and then processed appropriately if ind diameterCommand getCommandCode ErrorCommand StandardCommandCode ErrorCommand ec ErrorCommand ind DiameterCommand Do something with the Error Command ec object e g check the Result Code Exception Handling There are two main groups of exceptions that may need to be handled by application using the API GctException Generated by the GctLib classes to indicate issues when allocating messages sending messages retrieving messages or releasing messages The class includes a getMessage method to allow further details to be returned as a String Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 EncoderException Generated by the dmrApi classes when encoding or decoding commands The class includes a getMessage method to allow further details to be returned as a String The example below shows both of these kinds of exceptions being handled for some sample Java try t DmrSessionReq dmrSsnReq DmrSessionReqFactory BuildDmrSessionReq dmrContext Config int len dmrContext userApi dmrSessionReqEncoder calculateLength dmrSsnReq gctMsg gctMsg GctLib getm len dmrContext userApi dmrSessionReqEncoder encode dmrSsnReq gctMsg if Config TraceOn DtuMsgUtil traceMsg DTU gt gt gctMsg GctLib send short Config DstMID gctMsg catch EncoderException eEx System out println Problem with E
17. diameter context the required requests and answer commands need to be registered into the Context Object This step is common with the code required for the Request generation Step 3 Receive the GCT message This uses the GCT receive call which will block until a message for the requested module ids is returned This function is from the normal C based message passing API GCTLIB shared object libgct The function DMR API TEST receive dmr sesson ind in the example code shows call to receive the next incoming messages using the same mechanism as other modules in the stack Step 4 Decode the Session Indication As with encoding functionality the diameter context object provides methods which will decode the GCT message into a structured object representing the indication This is also shown in the DMR API TEST receive dmr sesson ind function 31 Section 7 Example C Applications Step 5 Release the GCT message Once handling is complete a call to relm can be used to free the message structure As with the GCT_receive this function is from the normal C based message passing API GCTLIB shared object libgct 32
18. e GCT message into a structured object representing the indication Step 5 Decode the Command The command code of the received indication can be compared against the expected command code and used to create a command object of the correct class The various get XYZAVP methods that are supplied can then be used AVP Handling Adding and Retrieving an AVP For AVPs at the top level of a Diameter command there are a series of methods which allow AVPs to be added or retrieved In the example below a new OriginHoatAvp object is created and added to an Update Location Request object ulr addOriginHostAvp new OriginHostAvp OriginHost There is a matching getOriginHostAvp method for retrieving the values in this case returning an OriginHostAvp object Adding an AVP list AVPs which are permitted to have multiple instances within a single command request or answer can be supported by calling the appropriate AVP addXYXAvp multiple times First Subscriber Data SubscriptionDataAvp sda new SubscriptionDataAvp sda addAccessRestrictionDataAvp new AccessRestrictionDataAvp long 0x55555 ula addSubscriptionDataAvp sda Second Subscriber Data SubscriptionDataAvp sda2 new SubscriptionDataAvp sda2 addAccessRestrictionDataAvp new AccessRestrictionDataAvp long 0x44444 ula addSubscriptionDataAvp sda2 Retrieving an AVP list When retrieving an AVP which may have multiple instances it is n
19. ecessary to use an iterator AVPs which may have multiple instances have two forms of the getters one with and one without an iterator parameter The form without the iterator will return the first instance of that AVP The form with the iterator will return the first instance of the AVP the first time it is called and then the next each extra time it is called 15 Section 4 Functional API Illustration ListIterator lt IAvp gt li ulr listIterator while li hasNext ProxyInfoAvp pia ulr getProxyInfoAvp li if pia null amp amp pia getProxyHostAvp null System out println pia getProxyHostAvp getString 4 3 4 Adding an unknown AVP To add an unknown AVP a new AVP needs to be created of the appropriate AVP type The unknown AVP can then be marked as unknown with the setIsUnknown method and added using the add method on the request or answer TAvp unknownAvp new OctetStringAvp 999L OL ByteBuffer wrap new byte 1 2 3 4 ulr add unknownAvp 4 3 5 Retrieving an unknown AVP When retrieving one or more unknown AVPs it may be necessary to use an iterator There may be one or more unknown AVPs therefore there are two forms of getters one with and one without an iterator parameter The form without the iterator will return the first instance of an unknown AVP The form with the iterator will return the first instance of an unknown AVP the first time it is called and then the next each
20. ed for use in certain safety affecting situations Please see http www dialogic com company terms of use aspx for more details Due to differing national regulations and approval requirements certain Dialogic products may be suitable for use only in specific countries and thus may not function properly in other countries You are responsible for ensuring that your use of such products occurs only in the countries where such use is suitable For information on specific products contact Dialogic Inc at the address indicated below or on the web at www dialogic com It is possible that the use or implementation of any one of the concepts applications or ideas described in this document in marketing collateral produced by or on web pages maintained by Dialogic may infringe one or more patents or other intellectual property rights owned by third parties Dialogic does not provide any intellectual property licenses with the sale of Dialogic products other than a license to use such product in accordance with intellectual property owned or validly licensed by Dialogic and no such licenses are provided except pursuant to a signed agreement with Dialogic More detailed information about such intellectual property is available from Dialogic s legal department at 6700 de la Cote de Liesse Road Suite 100 Borough of Saint Laurent Montreal Quebec Canada H4T 2B5 Dialogic encourages all users of its products to procure all necessary intellectual property li
21. extra time it is called ListIterator lt IAvp gt li ulr listIterator while li hasNext TAvp ua ulr getUnknownAvp li if ua null System out println Unknown Avp ua getCode 4 3 6 Handling enum AVPs with unknown values If enumerated values are encountered that do not correspond to explicitly defined enumerated values then their value can be returned by integer value instead 16 4 4 Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 System out println Unknown enum val ulr getUl ESrvccCapabilityAvp getinteger Result Code Diameter Answers include the ResultCode AVP This AVP is an Integer value indicating the success or failure code of the Diameter Command The commands support getResultCodeAvp and addResultCodeAvp methods to allow the value to be retrieved from an Answer Indication In addition there is an enumerated type which can be used to generate standard values ResultCode DIAMETER SUCCESS getValue Values valid for this AVP are included in the table below Table 1 Result Code Values Result Code Mnemonic Value DIAMETER MULTI ROUND AUTH 1001 DIAMETER SUCCESS 2001 DIAMETER LIMITED SUCCESS 2002 DIAMETER COMMAND UNSUPPORTED 3001 DIAMETER UNABLE TO DELIVER 3002 DIAMETER REALM NOT SERVED 3003 DIAMETER TOO BUSY 3004 DIAMETER LOOP DETECTED 3005 DIAMETER REDIREC
22. ing used to build up a Provide Subscriber Location request command is covered in DMR API TEST build provide location request 7 3 2 Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 Step 4 Allocate a GCT message From the context object a method can be used to calculate the encoded length for the message allowing the GCT message structure to be allocated using the getm function from the normal C based message passing API GCTLIB shared object libgct This allocation is shown in DMR API TEST transmit dmr session req Step 5 Encode the command request into a GCT message The context object also contains the encoder method to format the DmrSessionReq into a GCT message The function referenced in Step 4 also shows and example of encoding the request Step 6 Send the GCT Message Takes the GCT message and sends it to the DSI Diameter Module using the GCT send function from the normal C based message passing API GCTLIB shared object libgct The function referenced in Step 4 also shows the GCT message being sent Handling a received Diameter Request Step 1 Generate a diameter context The diameter context object is used to store and initialize factory and encoder decoder objects required by the user application This step is common with the code required for the Request generation Step 2 Register a command with the context In order to define which commands are valid with the
23. k eka sua sese snas rna 23 6 42 Gomimand lile OUtPUE 5 occ aoa Ew na ne a nea a da RE ERR RIRIARRUNER K k Ek k k k Du KE AE Kz 26 6 1 22 CommandliRe Xamp e leer saha hede nea k diia y a a a a a a s ERR A NEAR UU E ek EAR Ax E RR RENE 27 6 2 DTR Diameter Test Responders k ed sya enne men k xl ne menn nena inan ka aa r k k yek k ka y b y ke k ba ce b k y 27 6 2 1 Command line OUtpUE i ss cnn eren nen ekak kako ck ek eka keka ekok ek k uk sk buck ba a Pes ki sek bee k keke 28 6 2 2 Commahd line example 8 A dl e dal k n x n TE elya n kaya veru xao yaya Yu Vay raa U y gu aw Tuya Van Va v Ya ad 28 7 Example C ADD CAt OD Sakl klklkkkkkkkkkkkkkkk kk kk kk kaka akan seen enhn nnn anas ua nu nau nau nak u a 29 7 1 Installation kaka ka yalla ahaa ral lal ba lak ak a nas T etaed de tirer atte eu laine meet ar eie 29 7 2 Building and running the example code 4L L hllkkk kk kk kk kk kk kk kaka kaka aka aka kaka aka kak kaka ka kk aka ka 29 7 3 Cr Exemplar Overview ec 30 7 3 1 Generating a Diameter Session irren dis dane deda dak dada kada kan akan aa ada mak bank n nda n n bad naa E 30 7 3 2 Handling a received Diameter Request mene kk aka ka kk aka ka 31 Figures Figure 1 Diameter Module and Functional APIS K KK ll kllll akla k keka yek ke eee eee eee eee eee aed 6 Figure 2 iilos pide D_o_D_o rmmm oo e e gg_ aa
24. mmand API i i i com dialogic signaling diameter dmtrCmds jar Section 3 Component Overview 3 2 3 3 3 4 3 4 1 C Development Package Components The required functionality and components for use with C are stored in the following files within the DSI Development Package API Package Namespace Library Message gctlib libgctlib so Passing Library DMR Access com dialogic signaling dmr dmrApr lib API com dialogic signaling dmr user Diameter com dialogic signaling diameter dmrApr lib Command API com dialogic signaling diameter dmtrCmds lib Message Passing Environment GCTLIB API The functional API is supplied together with Java extensions to the DSI Signaling Products Development Package to support access to the C based GCTLIB message passing library C users can make direct use of the existing GCTLIB library The message passing environment is the same environment as used by the Diameter Module and most parts of the Development Package This is shown in Figure 2 DMR Access API These are a set of classes which enable Diameter encoding decoding session handling and co ordination independent of any individual Diameter message or specific encoding rules DmrContext The focus of the DmrContext is APIs to encode and decode messages sent to and from the Diameter Module This includes messages defined within the DMR Programmer s Manual and also Diameter
25. nFlight 1 Dest Host dmr02 1ab dialogic com Dest Realm dialogic com Command line examples If host based or realm based routing is used then the host and realm options should be selected as shown below java Djava library path opt DSI 32 jar opt DSI JAVA dtu jar dsthdmr02 1ab dialogic com dstrdialogic com numreq10 An example set of command line options for Credit Control session handling Ro is as follows java Djava library path opt DSI 32 jar opt DSI JAVA dtu jar dsthdmr02 1ab dialogic com dstrdialogic com numreq10 model DTR Diameter Test Responder Description The DTR example application simulates the response to the sending of an Update Location Request Message and sends an Update Location Answer in reply Syntax java jar dtr m modid dmr dmr modid traceoff Parameters m modid Set to define the module id used by DTR If not set then DTR will default to Ox2d dmr lt dmr modid gt Set to define the module id used by the Diameter module DMR If not set then DTU will default to 0x74 traceoff Disable message tracing 27 Section 6 Example Java Applications 6 2 1 6 2 2 28 Command line output Help Screen DSI DTR Diameter Test Responder Release 1 01 Part of the Dialogic R DSI Development Package Copyright C 2012 Dialogic Inc All Rights Reserved Syntax dtr jar m dmr lt gt lossrate lt gt traceoff DTR Receives Diameter Session Reque
26. ncode Decode eEx getMessage catch GctException gctEx System out println Problem with message handling gctEx getMessage catch Exception ex System out println ex toString 19 Section 5 Command and Message Dictionaries 5 Command and Message Dictionaries 20 Figure 5 Decoded EM Message DmrContext ncode Class Message Instance GCT MSG instances The functional API provides a set of class files which are supplied to greatly simplify the generation and handling of specific Diameter commands and parameters These class files are generated from a set of Dictionary files to allow extensions and modifications to the class sets as new services interfaces or parameters are required dms DMS Class TT Diameter generation Encodable Ur Classes utility Encoder Factory DMS Class generation and encoders In the figure above the Diameter definition files are used by the DMS utility part of the Dialogic DSI Diameter Stack to generate encoder libraries for use with the Functional API This generation happens prior to compiling the application At application start time the application the Encoder Factory classes can be used to create an instance of the DmrContext class in advance of sessions needing to be handled 5 1 Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 After the initial start up phase
27. nition files make use of appropriate package names to differentiate the namespace of the classes Typically each specification will produce a package with its name derived from the specification title for example rfc3588 22 Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 6 Example Java Applications 6 1 DTU Diameter Test Utility Description The Diameter test Utility DTU is a simple example application that illustrates the use of the Funational API and can be configured to implement specific operations By default the DTU example application simulates the sending of an Update Location Request Message and waits for the corresponding Update Location Answer The utility can be used with the DTR example listed in section 6 1 2 Update Location Request Update Location Answer K Figure 6 DTU DTR Message Sequence Chart Mode 0 Update Location 23 Section 6 Example Java Applications DTU can also generate a message sequence flow for demonstration of a Credit Control message flow appropriate for the Ro Diameter interface Example Service Node Online Charging Service Credit Control Request Initial Credit Control Answer Initial Service Completed Credit Control Request Term Credit Control Answer Term p 7 ra u Na hanna ee Be Ne ie Figure 7 DTU DTR Message Sequence Ch
28. no oto anN naDnndn n Una 0N nS R D HD ZH SHAD H Ss D 4 3 3 Retrieving an AVP IISU sy sis clan xad tree b nan Dana nana aa na inana on hak an R HD RD HD RO D DO D D ARE RE 4344 JAdding an unknown AV Piress ssns sneon SEn cana e se Ge en cnim xa ek n n eyn kan ey e su W Ka nek n k ek 4 3 5 R trieving an UNKNOWN AVP riesce rona enenatis estqui nimm n xi ka WW W WW Ed KWA y 4 3 6 Handling enum AVPs with unknown values seem eee 4 4 PROS UNE COGO ceteris dtr n n n n ne ewin ene n nr e E eke dala kk k s e fe tle kya e ae Malena k 4 5 EtrorsComimantelh 2 a s4 das daya yan Ra H e ad ta b d b B b D a R l d En BAWA DADA GANA GUR UA Ee GAWA WA FA AGA EWE 4 6 Exceptiomiblandlilgs cud eue ka ea eee R WAR EKA R K n ARA DE D WE EA DAR GER san edu ala kada a daka e a da E Ga kO da Command and Message Dictionaries kkkK k kl kklklkllkkkkkkkkkkkkkkkkkkkkkk kk anak kaka nana kana an nau naa nnn 1 DMS Utility 2 Namespace ai ka al aa aa a aa a a la a a RF a a l a a a a aa ja a a E ERE V a a krd a a l a ka kla a a aa EEA Section 1 Introduction 6 Example Java Applications Xk K kkkllkdlklklkkkkkkkkkkkkkkkk kk kaka kk kaka kaka aku kaka au uan u nau uan nana nana nnn nan 23 6 1 DTU Diameter Test Utility eese nennen rnnt nine a keka k a
29. of run time the DmrContext User API methods can be used to encode Diameter request or answer objects into GCT Message The same DmrContext object can also be used to decode messages from GCT Messages into Diameter request or answer objects DMS Utility The DMS utility is a supporting component to the Dialogic DSI Diameter Stack It is used to convert the structured definitions of the Diameter commands and AVPs into class libraries for use with the Functional API Syntax java jar dms input lt path gt output lt path gt namespace lt ns gt 7 1 lt language gt ver q v h Example java jar opt DSI java dms jar output src 1 CPP Parameters input path Path to dms Diameter specification definition files Short form is i output path Path to which generated files should be written Short form is o namespace ns The root namespace for generated class files The default namespace is com dialogic signaling diameter Short form is n language lt JAVA CPP gt The required language default is CPP Short form is I quiet Suppress output and don t ask for user prompts Short form is q verbose Display verbose output Short form is verb version Display DMS version information Short form is v help Display DMS help information Short form is h 21 Section 5 Command and Message Dictionaries 5 2 Namespace The classes generated by DMS using the XML defi
30. or more open source products systems and or releases Dialogic is not responsible for your decision to use open source in connection with Dialogic products including without limitation those referred to herein nor is Dialogic responsible for any present or future effects such usage might have including without limitation effects on your products your business or your intellectual property rights Publication Date September 2013 Document Number U02DMR Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 Revision History Issue Date Description 4 20 Sep 13 Addition of C API 3 22 Feb 13 Revised Java jar definitions and minor API name changes 2 10 Jan 13 Updated to include support for Ro and Rf interfaces 1 09 Nov 12 Initial Release for use during Dialogic DSI Diameter Stack beta trial Note The current version of this guide can be found at http www dialogic com support helpweb signaling Contents D GUDDIDMNIDceRA 1 Introduction e esee eese aa ala aa a ka daa al a bka a a aa kwa a aya a aa a dala nennen nnn 1 1 APPIIGADIIEY 1 2 Related DOCUMENTALION sss sis saa siskekdk kadina sdana ka amnanan n Ea ha n k aa ni a ka n n Diana k n Hind a m m kim y 2 Stack Overview e d d
31. ous N Diameter PA Passing ea E We sd kaw ee API li A N ww M Et N A yu w Seue w g ra 3 o o E o si lt 2 i Z S npolA Kernel SCTP Diameter Module and Functional APIs Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 3 Component Overview Figure 2 3 1 This section provides an overview of the functional APIs used by an Application to interface with the Diameter Module DMR The APIs are shown below in Figure 2 The Message Passing API allows C and Java users to interface with the underlying DSI message passing mechanism by providing access to the GCTLIB library The DMR Access API provides the methods to control and manage the messages that access the functionality provided in the Diameter Module The Diameter Command API provides functionality to build Diameter Command and AVP objects to permit them to be encoded using the DMR Access API b Message Passing API J Diameter Da Command lt VAM e Eme Functional APIs Java Development Package Components The required functionality and components for use in Java are stored in the following Java Jar files within the DSI Development Package API Package Jar Message Passing com dialogic signaling gct gctApi jar Library DMR Access API com dialogic signaling dmr dmrApr jar Diameter com dialogic signaling diameter dmrApr jar Co
32. p 3 DmrSessionReq dmrSsnReq DmrSessionReqFactory buildDmrSessionReq dmrContext Config dmrSsnReq SessionId dmrSsnReq SessionId Config MaxSsnNum Step 4 int len dmrContext userApi dmrSessionRegEncoder calculateLength dmrSsnReq GctMsg gctMsg GctLib getm len Step 5 dmrContext userApi dmrSessionRegEncoder encode dmrSsnReq gctMsg Step 6 GctLib send short Config DstMID gctMsg Step 1 Generate a diameter context The diameter context object is used to store and initialize factory and encoder objects required by the user application Step 2 Register a command with the context In order to define which commands are valid with the diameter context the required requests and answer commands need to be registered into the context object You can also set the module ids for the application and Diameter module here too 4 1 1 Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 Step 3 Create and populate the session request object This step builds up a structured form of the request object which is to be encoded and is covered in further detail in section 4 1 1 Building the session request object This uses methods from the Diameter Command Specific API Step 4 Allocate a GCT message From the context object a method can be used to calculate the encoded length for the message allowing the GCT message structure to be allocated Step 5 Encode the command request
33. sts and Answers them Example java jar dtr jar m0x2d Options m DTR Module Id Sets the module id for DTR dmr DMR Module Id Sets the module id for the Diameter Module DMR delay Delay Rate If set the module will insert a 10 msec delay every 1 in n ULR received traceoff Turn Trace Off Typical Output DSI DTR Diameter Test Responder Release 1 01 Part of the Dialogic R DSI Development Package Copyright C 2012 Dialogic Inc All Rights Reserved DTR module id 0x2d DMR module id 0x74 Command line examples The example DTR system txt file included within the DSI Development Package starts the dtr example automatically with default options This is likely appropriate for most normal systems and situations The command line used is as shown below Unlike DTU it is not necessary select a specific mode to handle different session message flows java Djava library path opt DSI 32 jar opt DSI JAVA dtr jar Dialogic DSI Diameter Stack Diameter Functional API User Manual Issue 4 7 Example C Applications 7 1 7 2 The DSI Development Package includes an example application for the C Functional API This section provides further details and explanation of the example Installation The development package should be installed in the normal manner following the instructions in the Dialogic DSI Software Environment Programmer s Manual The package installs the following directories
34. xist Utf8StringAvp Pre defined primitive AVP representing an array of UTF8 data sub classed from OctetStringAvp ProxyInfoAvp An example GroupedAvp which has at least one sub AVP ProxyHostAvp An example member of the ProxyInfoAvp GroupedAvp UpdateLocationRequest An example of a concrete Diameter Command class used to encode or decode an Update Location Request Other classes exist for other commands It provides the real methods for adding the correct AVPs to the command or retrieving AVPs on decode 11 Section 4 Functional API Tllustration 4 Functional API Illustration 4 1 12 This section provides a description of the various API calls appropriate to permit development of applications making use of the Functional API Unless otherwise stated the source code examples are for Java For C Users further example code can be found in Section 7 Example C Applications Generating a Diameter Session The following code samples and description show a simplified example of building and sending a Diameter Update Location Request Exception handling and other error handling has been removed to show the core functionality more closely Step 1 dmrContext new DmrContext Step 2 dmrContext registerDiameterCommand UpdateLocationRequest class dmrContext registerDiameterCommand UpdateLocationAnswer class dmrContext setDmrTaskId config DstMID dmrContext setSrcTaskId config SrcMID Ste
Download Pdf Manuals
Related Search