Thu Apr 16 06:44:31 2015

Asterisk developer's documentation


aoc.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2010, Digium, Inc.
00005  *
00006  * David Vossel <dvossel@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*!
00020  * \file
00021  * \brief Generic Advice of Charge encode and decode routines
00022  *
00023  * \author David Vossel <dvossel@digium.com>
00024  */
00025 
00026 #ifndef _AST_AOC_H_
00027 #define _AST_AOC_H_
00028 
00029 #include "asterisk/channel.h"
00030 
00031 #define AOC_CURRENCY_NAME_SIZE (10 + 1)
00032 
00033 /*! \brief Defines the currency multiplier for an aoc message. */
00034 enum ast_aoc_currency_multiplier {
00035    AST_AOC_MULT_ONETHOUSANDTH = 1,
00036    AST_AOC_MULT_ONEHUNDREDTH,
00037    AST_AOC_MULT_ONETENTH,
00038    AST_AOC_MULT_ONE,
00039    AST_AOC_MULT_TEN,
00040    AST_AOC_MULT_HUNDRED,
00041    AST_AOC_MULT_THOUSAND,
00042    AST_AOC_MULT_NUM_ENTRIES, /* must remain the last item in enum, this is not a valid type */
00043 };
00044 
00045 /*!
00046  * \brief Defines the billing id options for an aoc message.
00047  * \note  AOC-D is limited to NORMAL, REVERSE_CHARGE, and CREDIT_CARD.
00048  */
00049 enum ast_aoc_billing_id {
00050    AST_AOC_BILLING_NA = 0,
00051    AST_AOC_BILLING_NORMAL,
00052    AST_AOC_BILLING_REVERSE_CHARGE,
00053    AST_AOC_BILLING_CREDIT_CARD,
00054    AST_AOC_BILLING_CALL_FWD_UNCONDITIONAL,
00055    AST_AOC_BILLING_CALL_FWD_BUSY,
00056    AST_AOC_BILLING_CALL_FWD_NO_REPLY,
00057    AST_AOC_BILLING_CALL_DEFLECTION,
00058    AST_AOC_BILLING_CALL_TRANSFER,
00059    AST_AOC_BILLING_NUM_ENTRIES /* must remain the last item in enum, not a valid billing id */
00060 };
00061 
00062 enum ast_aoc_type {
00063    AST_AOC_REQUEST = 0,
00064    AST_AOC_S,
00065    AST_AOC_D,
00066    AST_AOC_E, /* aoc-e must remain the last item in this enum */
00067 };
00068 
00069 enum ast_aoc_charge_type {
00070    AST_AOC_CHARGE_NA = 0,
00071    AST_AOC_CHARGE_FREE,
00072    AST_AOC_CHARGE_CURRENCY,
00073    AST_AOC_CHARGE_UNIT, /* unit must remain the last item in enum */
00074 };
00075 
00076 enum ast_aoc_request {
00077    AST_AOC_REQUEST_S = (1 << 0),
00078    AST_AOC_REQUEST_D = (1 << 1),
00079    AST_AOC_REQUEST_E = (1 << 2),
00080 };
00081 
00082 enum ast_aoc_total_type {
00083    AST_AOC_TOTAL = 0,
00084    AST_AOC_SUBTOTAL = 1,
00085 };
00086 
00087 enum ast_aoc_time_scale {
00088    AST_AOC_TIME_SCALE_HUNDREDTH_SECOND,
00089    AST_AOC_TIME_SCALE_TENTH_SECOND,
00090    AST_AOC_TIME_SCALE_SECOND,
00091    AST_AOC_TIME_SCALE_TEN_SECOND,
00092    AST_AOC_TIME_SCALE_MINUTE,
00093    AST_AOC_TIME_SCALE_HOUR,
00094    AST_AOC_TIME_SCALE_DAY,
00095 };
00096 
00097 struct ast_aoc_time {
00098    /*! LengthOfTimeUnit (Not valid if length is zero.) */
00099    uint32_t length;
00100    uint16_t scale;
00101 };
00102 
00103 struct ast_aoc_duration_rate {
00104    uint32_t amount;
00105    uint32_t time;
00106    /*! Not present if the granularity time is zero. */
00107    uint32_t granularity_time;
00108 
00109    uint16_t multiplier;
00110    uint16_t time_scale;
00111    uint16_t granularity_time_scale;
00112 
00113    /*! Name of currency involved.  Null terminated. */
00114    char currency_name[AOC_CURRENCY_NAME_SIZE];
00115 
00116    /*!
00117     * \brief Charging interval type
00118     * \details
00119     * continuousCharging(0),
00120     * stepFunction(1)
00121     */
00122    uint8_t charging_type;
00123 };
00124 
00125 enum ast_aoc_volume_unit {
00126    AST_AOC_VOLUME_UNIT_OCTET,
00127    AST_AOC_VOLUME_UNIT_SEGMENT,
00128    AST_AOC_VOLUME_UNIT_MESSAGE,
00129 };
00130 
00131 struct ast_aoc_volume_rate {
00132    uint32_t amount;
00133    uint16_t multiplier;
00134    uint16_t volume_unit;
00135    char currency_name[AOC_CURRENCY_NAME_SIZE];
00136 };
00137 
00138 struct ast_aoc_flat_rate {
00139    uint32_t amount;
00140    uint16_t multiplier;
00141    /*! Name of currency involved.  Null terminated. */
00142    char currency_name[AOC_CURRENCY_NAME_SIZE];
00143 };
00144 
00145 enum ast_aoc_s_charged_item {
00146    AST_AOC_CHARGED_ITEM_NA,
00147    AST_AOC_CHARGED_ITEM_SPECIAL_ARRANGEMENT,
00148    AST_AOC_CHARGED_ITEM_BASIC_COMMUNICATION,
00149    AST_AOC_CHARGED_ITEM_CALL_ATTEMPT,
00150    AST_AOC_CHARGED_ITEM_CALL_SETUP,
00151    AST_AOC_CHARGED_ITEM_USER_USER_INFO,
00152    AST_AOC_CHARGED_ITEM_SUPPLEMENTARY_SERVICE,
00153 };
00154 
00155 enum ast_aoc_s_rate_type {
00156    AST_AOC_RATE_TYPE_NA,
00157    AST_AOC_RATE_TYPE_FREE,
00158    AST_AOC_RATE_TYPE_FREE_FROM_BEGINNING,
00159    AST_AOC_RATE_TYPE_DURATION,
00160    AST_AOC_RATE_TYPE_FLAT,
00161    AST_AOC_RATE_TYPE_VOLUME,
00162    AST_AOC_RATE_TYPE_SPECIAL_CODE,
00163 };
00164 
00165 struct ast_aoc_s_entry {
00166    uint16_t charged_item;
00167    uint16_t rate_type;
00168 
00169    /*! \brief Charge rate being applied. */
00170    union {
00171       struct ast_aoc_duration_rate duration;
00172       struct ast_aoc_flat_rate flat;
00173       struct ast_aoc_volume_rate volume;
00174       uint16_t special_code; /* 1...10 */
00175    } rate;
00176 } __attribute__((packed));
00177 
00178 struct ast_aoc_unit_entry {
00179    char valid_amount;
00180    unsigned int amount;
00181    char valid_type;
00182    unsigned int type; /* 1 - 16 by ETSI standard */
00183 };
00184 
00185 enum AST_AOC_CHARGING_ASSOCIATION {
00186    AST_AOC_CHARGING_ASSOCIATION_NA,
00187    AST_AOC_CHARGING_ASSOCIATION_NUMBER,
00188    AST_AOC_CHARGING_ASSOCIATION_ID,
00189 };
00190 struct ast_aoc_charging_association_number {
00191    uint8_t plan;
00192    char number[32];
00193 } __attribute__((packed));
00194 struct ast_aoc_charging_association {
00195    union {
00196       int32_t id;
00197       struct ast_aoc_charging_association_number number;
00198    } charge;
00199    /*! \see enum AST_AOC_CHARGING_ASSOCIATION */
00200    uint8_t charging_type;
00201 } __attribute__((packed));
00202 
00203 /*! \brief AOC Payload Header. Holds all the encoded AOC data to pass on the wire */
00204 struct ast_aoc_encoded;
00205 
00206 /*! \brief Decoded AOC data. This value is used to set all the values in an AOC message before encoding.*/
00207 struct ast_aoc_decoded;
00208 
00209 /*!
00210  * \brief creates a ast_aoc_decode object of a specific message type
00211  * \since 1.8
00212  *
00213  * \param msg_type AOC-D, AOC-E, or AOC Request
00214  * \param charge_type this is ignored if message type is not AOC-D or AOC-E.
00215  * \param requests flags.  This defines the types of AOC requested. This
00216  *        field should only be set when the message type is AOC Request,
00217  *        the value is ignored otherwise.
00218  *
00219  * \retval heap allocated ast_aoc_decoded object ptr on success
00220  * \retval NULL failure
00221  */
00222 struct ast_aoc_decoded *ast_aoc_create(const enum ast_aoc_type msg_type,
00223       const enum ast_aoc_charge_type charge_type,
00224       const enum ast_aoc_request requests);
00225 
00226 
00227 /*! \brief free an ast_aoc_decoded object */
00228 void *ast_aoc_destroy_decoded(struct ast_aoc_decoded *decoded);
00229 
00230 /*! \brief free an ast_aoc_encoded object */
00231 void *ast_aoc_destroy_encoded(struct ast_aoc_encoded *encoded);
00232 
00233 /*!
00234  * \brief decodes an encoded aoc payload.
00235  * \since 1.8
00236  *
00237  * \param encoded the encoded payload to decode.
00238  * \param size total size of encoded payload
00239  * \param chan ast channel, Optional for DEBUG output purposes
00240  *
00241  * \retval heap allocated ast_aoc_decoded object ptr on success
00242  * \retval NULL failure
00243  */
00244 struct ast_aoc_decoded *ast_aoc_decode(struct ast_aoc_encoded *encoded, size_t size, struct ast_channel *chan);
00245 
00246 /*!
00247  * \brief encodes a decoded aoc structure so it can be passed on the wire
00248  * \since 1.8
00249  *
00250  * \param decoded the decoded struct to be encoded
00251  * \param out_size output parameter representing size of encoded data
00252  * \param chan ast channel, Optional for DEBUG output purposes
00253  *
00254  * \retval pointer to encoded data
00255  * \retval NULL failure
00256  */
00257 struct ast_aoc_encoded *ast_aoc_encode(struct ast_aoc_decoded *decoded, size_t *out_size, struct ast_channel *chan);
00258 
00259 /*!
00260  * \brief Sets the type of total for a AOC-D message
00261  * \since 1.8
00262  *
00263  * \param decoded ast_aoc_decoded struct to set values on
00264  * \param type total type: TOTAL or SUBTOTAL
00265  *
00266  * \note If this value is not set, the default for the message is TOTAL
00267  *
00268  * \retval 0 success
00269  */
00270 int ast_aoc_set_total_type(struct ast_aoc_decoded *decoded, const enum ast_aoc_total_type type);
00271 
00272 /*!
00273  * \brief Sets the currency values for a AOC-D or AOC-E message
00274  * \since 1.8
00275  *
00276  * \param decoded ast_aoc_decoded struct to set values on
00277  * \param amount currency amount REQUIRED
00278  * \param multiplier currency multiplier REQUIRED, 0 or undefined value defaults to AST_AOC_MULT_ONE.
00279  * \param name currency name OPTIONAL
00280  *
00281  * \retval 0 success
00282  */
00283 int ast_aoc_set_currency_info(struct ast_aoc_decoded *decoded,
00284       const unsigned int amount,
00285       const enum ast_aoc_currency_multiplier multiplier,
00286       const char *name);
00287 
00288 /*!
00289  * \brief Adds a unit entry into the list of units
00290  * \since 1.8
00291  *
00292  * \param decoded ast_aoc_decoded struct to set values on
00293  * \param amount_is_present set this if the number of units is actually present.
00294  * \param amount number of units
00295  * \param type_is_present set this if the type value is present
00296  * \param type unit type
00297  *
00298  * \note If neither the amount nor the type is present, the entry will
00299  * not be added.
00300  *
00301  * \retval 0 success
00302  */
00303 int ast_aoc_add_unit_entry(struct ast_aoc_decoded *decoded,
00304       const unsigned int amount_is_present,
00305       const unsigned int amount,
00306       const unsigned int type_is_present,
00307       const unsigned int type);
00308 
00309 /*!
00310  * \brief set the billing id for a AOC-D or AST_AOC_E message
00311  * \since 1.8
00312  *
00313  * \param decoded ast_aoc_decoded struct to set values on
00314  * \param id billing id
00315  *
00316  * \retval 0 success
00317  */
00318 int ast_aoc_set_billing_id(struct ast_aoc_decoded *decoded, const enum ast_aoc_billing_id id);
00319 
00320 /*!
00321  * \brief set the charging association id for an AST_AOC_E message
00322  * \since 1.8
00323  *
00324  * \param decoded ast_aoc_decoded struct to set values on
00325  * \param id charging association identifier
00326  *
00327  * \note If the association number was set, this will override that value. Only the id OR the
00328  *       number can be set at a time, not both.
00329  *
00330  * \retval 0 success
00331  */
00332 int ast_aoc_set_association_id(struct ast_aoc_decoded *decoded, const int id);
00333 
00334 /*!
00335  * \brief set the charging accociation number for an AOC-E message
00336  * \since 1.8
00337  *
00338  * \param decoded ast_aoc_decoded struct to set values on
00339  * \param num charging association number
00340  * \param plan charging association number plan and type-of-number fields
00341  *
00342  * \note If the association id was set, this will override that value. Only the id OR the
00343  *       number can be set at a time, not both.
00344  *
00345  * \retval 0 success
00346  */
00347 int ast_aoc_set_association_number(struct ast_aoc_decoded *decoded, const char *num, uint8_t plan);
00348 
00349 /*!
00350  * \brief Mark the AST_AOC_REQUEST message as a termination request.
00351  * \since 1.8
00352  *
00353  * \param decoded ast_aoc_decoded struct to set values on
00354  *
00355  * \note A termination request indicates that the call has terminated,
00356  * but that the other side is waiting for a short period of time before
00357  * hanging up so it can get the final AOC-E message.
00358  *
00359  * \retval 0 success
00360  * \retval -1 failure
00361  */
00362 int ast_aoc_set_termination_request(struct ast_aoc_decoded *decoded);
00363 
00364 /*!
00365  * \brief Add AOC-S duration rate entry
00366  * \since 1.8
00367  *
00368  * \param decoded aoc decoded object to add entry to
00369  * \param charged_item ast_aoc_s_charged_item
00370  * \param amount currency amount
00371  * \param multiplier currency multiplier
00372  * \param currency_name truncated after 10 characters
00373  * \param time
00374  * \param time_scale from ast_aoc_time_scale enum
00375  * \param granularity_time (optional, set to 0 if not present);
00376  * \param granularity_time_scale (optional, set to 0 if not present);
00377  * \param step_function  set to 1 if this is to use a step function, 0 if continuious
00378  *
00379  * \retval 0 success
00380  * \retval -1 failure
00381  */
00382 int ast_aoc_s_add_rate_duration(struct ast_aoc_decoded *decoded,
00383    enum ast_aoc_s_charged_item charged_item,
00384    unsigned int amount,
00385    enum ast_aoc_currency_multiplier multiplier,
00386    const char *currency_name,
00387    unsigned long time,
00388    enum ast_aoc_time_scale time_scale,
00389    unsigned long granularity_time,
00390    enum ast_aoc_time_scale granularity_time_scale,
00391    int step_function);
00392 
00393 /*!
00394  * \brief Add AOC-S flat rate entry
00395  * \since 1.8
00396  *
00397  * \param decoded aoc decoded object to add entry to
00398  * \param charged_item ast_aoc_s_charged_item
00399  * \param amount currency amount
00400  * \param multiplier currency multiplier
00401  * \param currency_name truncated after 10 characters
00402  *
00403  * \retval 0 success
00404  * \retval -1 failure
00405  */
00406 int ast_aoc_s_add_rate_flat(struct ast_aoc_decoded *decoded,
00407    enum ast_aoc_s_charged_item charged_item,
00408    unsigned int amount,
00409    enum ast_aoc_currency_multiplier multiplier,
00410    const char *currency_name);
00411 
00412 /*!
00413  * \brief Add AOC-S volume rate entry
00414  * \since 1.8
00415  *
00416  * \param decoded aoc decoded object to add entry to
00417  * \param charged_item ast_aoc_s_charged_item
00418  * \param volume_unit from ast_aoc_volume_unit enum
00419  * \param amount currency amount
00420  * \param multiplier currency multiplier
00421  * \param currency_name truncated after 10 characters
00422  *
00423  * \retval 0 success
00424  * \retval -1 failure
00425  */
00426 int ast_aoc_s_add_rate_volume(struct ast_aoc_decoded *decoded,
00427    enum ast_aoc_s_charged_item charged_item,
00428    enum ast_aoc_volume_unit volume_unit,
00429    unsigned int amount,
00430    enum ast_aoc_currency_multiplier multiplier,
00431    const char *currency_name);
00432 
00433 /*!
00434  * \brief Add AOC-S special rate entry
00435  * \since 1.8
00436  *
00437  * \param decoded aoc decoded object to add entry to
00438  * \param charged_item ast_aoc_s_charged_item
00439  * \param code special charging code
00440  *
00441  * \retval 0 success
00442  * \retval -1 failure
00443  */
00444 int ast_aoc_s_add_rate_special_charge_code(struct ast_aoc_decoded *decoded,
00445    enum ast_aoc_s_charged_item charged_item,
00446    unsigned int code);
00447 
00448 /*!
00449  * \brief Add AOC-S indicating charge item is free
00450  * \since 1.8
00451  *
00452  * \param decoded aoc decoded object to add entry to
00453  * \param charged_item ast_aoc_s_charged_item
00454  * \param from_beginning TRUE if the rate is free from beginning.
00455  *
00456  * \retval 0 success
00457  * \retval -1 failure
00458  */
00459 int ast_aoc_s_add_rate_free(struct ast_aoc_decoded *decoded,
00460    enum ast_aoc_s_charged_item charged_item, int from_beginning);
00461 
00462 /*!
00463  * \brief Add AOC-S entry indicating charge item is not available
00464  * \since 1.8
00465  *
00466  * \param decoded aoc decoded object to add entry to
00467  * \param charged_item ast_aoc_s_charged_item
00468  *
00469  * \retval 0 success
00470  * \retval -1 failure
00471  */
00472 int ast_aoc_s_add_rate_na(struct ast_aoc_decoded *decoded,
00473    enum ast_aoc_s_charged_item charged_item);
00474 
00475 /*!
00476  * \brief Add AOC-S special arrangement entry
00477  * \since 1.8
00478  *
00479  * \param decoded aoc decoded object to add entry to
00480  * \param code special arrangement code
00481  *
00482  * \retval 0 success
00483  * \retval -1 failure
00484  */
00485 int ast_aoc_s_add_special_arrangement(struct ast_aoc_decoded *decoded,
00486    unsigned int code);
00487 
00488 /*!
00489  * \brief Convert decoded aoc msg to string representation
00490  * \since 1.8
00491  *
00492  * \param decoded ast_aoc_decoded struct to convert to string
00493  * \param msg dynamic heap allocated ast_str object to store string representation in
00494  *
00495  * \retval 0 success
00496  * \retval -1 failure
00497  */
00498 int ast_aoc_decoded2str(const struct ast_aoc_decoded *decoded, struct ast_str **msg);
00499 
00500 /*! \brief generate AOC manager event for an AOC-S, AOC-D, or AOC-E msg */
00501 int ast_aoc_manager_event(const struct ast_aoc_decoded *decoded, struct ast_channel *chan);
00502 
00503 /*! \brief get the message type, AOC-D, AOC-E, or AOC Request */
00504 enum ast_aoc_type ast_aoc_get_msg_type(struct ast_aoc_decoded *decoded);
00505 
00506 /*! \brief get the charging type for an AOC-D or AOC-E message */
00507 enum ast_aoc_charge_type ast_aoc_get_charge_type(struct ast_aoc_decoded *decoded);
00508 
00509 /*! \brief get the types of AOC requested for when message type is AOC Request */
00510 enum ast_aoc_request ast_aoc_get_request(struct ast_aoc_decoded *decoded);
00511 
00512 /*! \brief get the type of total for a AOC-D message */
00513 enum ast_aoc_total_type ast_aoc_get_total_type(struct ast_aoc_decoded *decoded);
00514 
00515 /*! \brief get the currency amount for AOC-D and AOC-E messages*/
00516 unsigned int ast_aoc_get_currency_amount(struct ast_aoc_decoded *decoded);
00517 
00518 /*! \brief get the number rates associated with an AOC-S message */
00519 unsigned int ast_aoc_s_get_count(struct ast_aoc_decoded *decoded);
00520 
00521 /*!
00522  * \brief get a specific AOC-S rate entry.
00523  * \since 1.8
00524  *
00525  * \note This can be used in conjunction with ast_aoc_s_get_count to create
00526  *       a unit entry iterator.
00527  */
00528 const struct ast_aoc_s_entry *ast_aoc_s_get_rate_info(struct ast_aoc_decoded *decoded, unsigned int entry_number);
00529 
00530 /*! \brief get the number of unit entries for AOC-D and AOC-E messages*/
00531 unsigned int ast_aoc_get_unit_count(struct ast_aoc_decoded *decoded);
00532 
00533 /*!
00534  * \brief get a specific unit entry.
00535  * \since 1.8
00536  *
00537  * \note This can be used in conjunction with ast_aoc_get_unit_count to create
00538  *       a unit entry iterator.
00539  */
00540 const struct ast_aoc_unit_entry *ast_aoc_get_unit_info(struct ast_aoc_decoded *decoded, unsigned int entry_number);
00541 
00542 /*! \brief get the currency multiplier for AOC-D and AOC-E messages */
00543 enum ast_aoc_currency_multiplier ast_aoc_get_currency_multiplier(struct ast_aoc_decoded *decoded);
00544 
00545 /*! \brief get the currency multiplier for AOC-D and AOC-E messages in decimal format */
00546 const char *ast_aoc_get_currency_multiplier_decimal(struct ast_aoc_decoded *decoded);
00547 
00548 /*! \brief get the currency name for AOC-D and AOC-E messages*/
00549 const char *ast_aoc_get_currency_name(struct ast_aoc_decoded *decoded);
00550 
00551 /*! \brief get the billing id for AOC-D and AOC-E messages*/
00552 enum ast_aoc_billing_id ast_aoc_get_billing_id(struct ast_aoc_decoded *decoded);
00553 
00554 /*! \brief get the charging association info for AOC-E messages*/
00555 const struct ast_aoc_charging_association *ast_aoc_get_association_info(struct ast_aoc_decoded *decoded);
00556 
00557 /*!
00558  * \brief get whether or not the AST_AOC_REQUEST message as a termination request.
00559  * \since 1.8
00560  *
00561  * \note a termination request indicates that the call has terminated,
00562  *       but that the other side is waiting for a short period of time
00563  *       before hanging up so it can get the final AOC-E message.
00564  *
00565  * \param decoded ast_aoc_decoded struct to get values on
00566  *
00567  * \retval 0 not a termination request
00568  * \retval 1 is a termination request
00569  */
00570 int ast_aoc_get_termination_request(struct ast_aoc_decoded *decoded);
00571 
00572 /*!
00573  * \brief test aoc encode decode routines.
00574  * \since 1.8
00575  *
00576  * \note  This function verifies that a decoded message matches itself after
00577  *        the encode decode routine.
00578  */
00579 int ast_aoc_test_encode_decode_match(struct ast_aoc_decoded *decoded);
00580 
00581 /*! \brief enable aoc cli options */
00582 int ast_aoc_cli_init(void);
00583 
00584 #endif   /* _AST_AOC_H_ */

Generated on Thu Apr 16 06:44:31 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6