res_pjsip: AMI commands and events.

Created the following AMI commands and corresponding events for res_pjsip:

PJSIPShowEndpoints - Provides a listing of all pjsip endpoints and a few
                     select attributes on each.
  Events:
    EndpointList - for each endpoint a few attributes.
    EndpointlistComplete - after all endpoints have been listed.

PJSIPShowEndpoint - Provides a detail list of attributes for a specified
                    endpoint.
  Events:
    EndpointDetail - attributes on an endpoint.
    AorDetail - raised for each AOR on an endpoint.
    AuthDetail - raised for each associated inbound and outbound auth
    TransportDetail - transport attributes.
    IdentifyDetail - attributes for the identify object associated with
                     the endpoint.
    EndpointDetailComplete - last event raised after all detail events.

PJSIPShowRegistrationsInbound - Provides a detail listing of all inbound
                                registrations.
  Events:
    InboundRegistrationDetail - inbound registration attributes for each
                                registration.
    InboundRegistrationDetailComplete - raised after all detail records have
                                been listed.

PJSIPShowRegistrationsOutbound  - Provides a detail listing of all outbound
                                  registrations.
  Events:
    OutboundRegistrationDetail - outbound registration attributes for each
                                 registration.
    OutboundRegistrationDetailComplete - raised after all detail records
                                 have been listed.

PJSIPShowSubscriptionsInbound - A detail listing of all inbound subscriptions
                                and their attributes.
  Events:
    SubscriptionDetail - on each subscription detailed attributes
    SubscriptionDetailComplete - raised after all detail records have
                                 been listed.

PJSIPShowSubscriptionsOutbound - A detail listing of all outboundbound
                                subscriptions and their attributes.
  Events:
    SubscriptionDetail - on each subscription detailed attributes
    SubscriptionDetailComplete - raised after all detail records have
                                 been listed.

(issue ASTERISK-22609)
Reported by: Matt Jordan
Review: https://reviewboard.asterisk.org/r/2959/
........

Merged revisions 403131 from http://svn.asterisk.org/svn/asterisk/branches/12


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@403133 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/acl.h

@@ -134,6 +134,13 @@ void ast_copy_ha(const struct ast_ha *from, struct ast_ha *to);
  */
 struct ast_ha *ast_append_ha(const char *sense, const char *stuff, struct ast_ha *path, int *error);
 
+/*!
+ * \brief Convert HAs to a comma separated string value
+ * \param ha the starting ha head
+ * \param buf string buffer to convert data to
+ */
+void ast_ha_join(const struct ast_ha *ha, struct ast_str **buf);
+
 /*!
  * \brief Add a rule to an ACL struct
  *

include/asterisk/res_pjsip.h

@@ -1559,5 +1559,154 @@ void *ast_sip_dict_set(pj_pool_t* pool, void *ht,
 #define ast_sip_mod_data_set(pool, mod_data, id, key, val)		\
 	mod_data[id] = ast_sip_dict_set(pool, mod_data[id], key, val)
 
+/*!
+ * \brief Function pointer for contact callbacks.
+ */
+typedef int (*on_contact_t)(const struct ast_sip_aor *aor,
+			    const struct ast_sip_contact *contact,
+			    int last, void *arg);
+
+/*!
+ * \brief For every contact on an AOR call the given 'on_contact' handler.
+ *
+ * \param aor the aor containing a list of contacts to iterate
+ * \param on_contact callback on each contact on an AOR
+ * \param arg user data passed to handler
+ * \retval 0 Success, non-zero on failure
+ */
+int ast_sip_for_each_contact(const struct ast_sip_aor *aor,
+			     on_contact_t on_contact, void *arg);
+
+/*!
+ * \brief Handler used to convert a contact to a string.
+ *
+ * \param aor the aor containing a list of contacts to iterate
+ * \param contact the contact to convert
+ * \param last is this the last contact
+ * \param arg user data passed to handler
+ * \retval 0 Success, non-zero on failure
+ */
+int ast_sip_contact_to_str(const struct ast_sip_aor *aor,
+			   const struct ast_sip_contact *contact,
+			   int last, void *arg);
+
+/*!
+ * \brief For every aor in the comma separated aors string call the
+ *        given 'on_aor' handler.
+ *
+ * \param aors a comma separated list of aors
+ * \param on_aor callback for each aor
+ * \param arg user data passed to handler
+ * \retval 0 Success, non-zero on failure
+ */
+int ast_sip_for_each_aor(const char *aors, ao2_callback_fn on_aor, void *arg);
+
+/*!
+ * \brief For every auth in the array call the given 'on_auth' handler.
+ *
+ * \param array an array of auths
+ * \param on_auth callback for each auth
+ * \param arg user data passed to handler
+ * \retval 0 Success, non-zero on failure
+ */
+int ast_sip_for_each_auth(const struct ast_sip_auth_array *array,
+			  ao2_callback_fn on_auth, void *arg);
+
+/*!
+ * \brief Converts the given auth type to a string
+ *
+ * \param type the auth type to convert
+ * \retval a string representative of the auth type
+ */
+const char *ast_sip_auth_type_to_str(enum ast_sip_auth_type type);
+
+/*!
+ * \brief Converts an auths array to a string of comma separated values
+ *
+ * \param auths an auth array
+ * \param buf the string buffer to write the object data
+ * \retval 0 Success, non-zero on failure
+ */
+int ast_sip_auths_to_str(const struct ast_sip_auth_array *auths, char **buf);
+
+/*
+ * \brief AMI variable container
+ */
+struct ast_sip_ami {
+	/*! Manager session */
+	struct mansession *s;
+	/*! Manager message */
+	const struct message *m;
+	/*! user specified argument data */
+	void *arg;
+};
+
+/*!
+ * \brief Creates a string to store AMI event data in.
+ *
+ * \param event the event to set
+ * \param ami AMI session and message container
+ * \retval an initialized ast_str or NULL on error.
+ */
+struct ast_str *ast_sip_create_ami_event(const char *event,
+					 struct ast_sip_ami *ami);
+
+/*!
+ * \brief An entity responsible formatting endpoint information.
+ */
+struct ast_sip_endpoint_formatter {
+	/*!
+	 * \brief Callback used to format endpoint information over AMI.
+	 */
+	int (*format_ami)(const struct ast_sip_endpoint *endpoint,
+			  struct ast_sip_ami *ami);
+	AST_RWLIST_ENTRY(ast_sip_endpoint_formatter) next;
+};
+
+/*!
+ * \brief Register an endpoint formatter.
+ *
+ * \param obj the formatter to register
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+int ast_sip_register_endpoint_formatter(struct ast_sip_endpoint_formatter *obj);
+
+/*!
+ * \brief Unregister an endpoint formatter.
+ *
+ * \param obj the formatter to unregister
+ */
+void ast_sip_unregister_endpoint_formatter(struct ast_sip_endpoint_formatter *obj);
+
+/*!
+ * \brief Converts a sorcery object to a string of object properties.
+ *
+ * \param obj the sorcery object to convert
+ * \param str the string buffer to write the object data
+ * \retval 0 Success, non-zero on failure
+ */
+int ast_sip_sorcery_object_to_ami(const void *obj, struct ast_str **buf);
+
+/*!
+ * \brief Formats the endpoint and sends over AMI.
+ *
+ * \param endpoint the endpoint to format and send
+ * \param endpoint ami AMI variable container
+ * \param count the number of formatters operated on
+ * \retval 0 Success, otherwise non-zero on error
+ */
+int ast_sip_format_endpoint_ami(struct ast_sip_endpoint *endpoint,
+				struct ast_sip_ami *ami, int *count);
+
+/*!
+ * \brief Format auth details for AMI.
+ *
+ * \param auths an auth array
+ * \param ami ami variable container
+ * \retval 0 Success, non-zero on failure
+ */
+int ast_sip_format_auths_ami(const struct ast_sip_auth_array *auths,
+			     struct ast_sip_ami *ami);
 
 #endif /* _RES_PJSIP_H */

include/asterisk/res_pjsip_pubsub.h

@@ -252,7 +252,7 @@ struct ast_sip_subscription_handler {
 	 * during this callback. The handler MUST, however, begin the destruction
 	 * process for the subscription during this callback.
 	 */
-   void (*subscription_shutdown)(struct ast_sip_subscription *subscription);
+	void (*subscription_shutdown)(struct ast_sip_subscription *subscription);
 
 	/*!
 	 * \brief Called when a SUBSCRIBE arrives in order to create a new subscription
@@ -366,6 +366,16 @@ struct ast_sip_subscription_handler {
 	 * \retval non-zero Failure
 	 */
 	int (*refresh_subscription)(struct ast_sip_subscription *sub);
+
+	/*!
+	 * \brief Converts the subscriber to AMI
+	 *
+	 * This is a subscriber callback.
+	 *
+	 * \param sub The subscription
+	 * \param buf The string to write AMI data
+	 */
+	void (*to_ami)(struct ast_sip_subscription *sub, struct ast_str **buf);
 	AST_LIST_ENTRY(ast_sip_subscription_handler) next;
 };
 

include/asterisk/sorcery.h

@@ -102,6 +102,9 @@ extern "C" {
 /*! \brief Maximum size of an object type */
 #define MAX_OBJECT_TYPE 64
 
+/*! \brief Maximum length of an object field name */
+#define MAX_OBJECT_FIELD 128
+
 /*!
  * \brief Retrieval flags
  */

include/asterisk/strings.h

@@ -332,7 +332,23 @@ int attribute_pure ast_true(const char *val);
 int attribute_pure ast_false(const char *val);
 
 /*
- *  \brief Join an array of strings into a single string.
+ * \brief Join an array of strings into a single string.
+ * \param s the resulting string buffer
+ * \param len the length of the result buffer, s
+ * \param w an array of strings to join.
+ * \param size the number of elements to join
+ * \param delim delimiter between elements
+ *
+ * This function will join all of the strings in the array 'w' into a single
+ * string.  It will also place 'delim' in the result buffer in between each
+ * string from 'w'.
+ * \since 12
+*/
+void ast_join_delim(char *s, size_t len, const char * const w[],
+		    unsigned int size, char delim);
+
+/*
+ * \brief Join an array of strings into a single string.
  * \param s the resulting string buffer
  * \param len the length of the result buffer, s
  * \param w an array of strings to join.
@@ -341,7 +357,33 @@ int attribute_pure ast_false(const char *val);
  * string.  It will also place a space in the result buffer in between each
  * string from 'w'.
 */
-void ast_join(char *s, size_t len, const char * const w[]);
+#define ast_join(s, len, w) ast_join_delim(s, len, w, -1, ' ')
+
+/*
+ * \brief Attempts to convert the given string to camel case using
+ *        the specified delimiter.
+ *
+ * note - returned string needs to be freed
+ *
+ * \param s the string to convert
+ * \param delim delimiter to parse out
+ *
+ * \retval The string converted to "CamelCase"
+ * \since 12
+*/
+char *ast_to_camel_case_delim(const char *s, const char *delim);
+
+/*
+ * \brief Attempts to convert the given string to camel case using
+ *        an underscore as the specified delimiter.
+ *
+ * note - returned string needs to be freed
+ *
+ * \param s the string to convert
+ *
+ * \retval The string converted to "CamelCase"
+*/
+#define ast_to_camel_case(s) ast_to_camel_case_delim(s, "_")
 
 /*
   \brief Parse a time (integer) string.

include/asterisk/utils.h

@@ -755,6 +755,24 @@ int ast_safe_mkdir(const char *base_path, const char *path, int mode);
 
 #define ARRAY_LEN(a) (size_t) (sizeof(a) / sizeof(0[a]))
 
+/*!
+ * \brief Checks to see if value is within the given bounds
+ *
+ * \param v the value to check
+ * \param min minimum lower bound (inclusive)
+ * \param max maximum upper bound (inclusive)
+ * \return 0 if value out of bounds, otherwise true (non-zero)
+ */
+#define IN_BOUNDS(v, min, max) ((v) >= (min)) && ((v) <= (max))
+
+/*!
+ * \brief Checks to see if value is within the bounds of the given array
+ *
+ * \param v the value to check
+ * \param a the array to bound check
+ * \return 0 if value out of bounds, otherwise true (non-zero)
+ */
+#define ARRAY_IN_BOUNDS(v, a) IN_BOUNDS(v, 0, ARRAY_LEN(a) - 1)
 
 /* Definition for Digest authorization */
 struct ast_http_digest {