Openmama-dev@lists.openmama.org | [PATCH 3/5] [MAMAC] Doxygen updates

Home Messages Hashtags Subgroups

Date Date 1 - 1 of 1

[PATCH 3/5] [MAMAC] Doxygen updates

Ian Bell <IBell@...> #1255 Build and check MAMA C reference docs From fe1b3020c1196a56deaefc425f5633ad25c9875b Mon Sep 17 00:00:00 2001 Message-Id: <fe1b3020c1196a56deaefc425f5633ad25c9875b.1403606177.git.ibell@...> In-Reply-To: <0e8aa6503fa2861fa4a03fc84888408d09b65127.1403606176.git.ibell@...> References: <0e8aa6503fa2861fa4a03fc84888408d09b65127.1403606176.git.ibell@...> From: unknown <ibell@...> Date: Tue, 24 Jun 2014 11:15:22 +0100 Subject: [PATCH 3/5] [MAMAC] Doxygen updates Updated / reformatted Doxygen comments in some header files Signed-off-by: Ian Bell <ibell@...> --- mama/c_cpp/src/c/mama/ft.h \| 197 +++++++++++++++++--- mama/c_cpp/src/c/mama/io.h \| 75 +++++--- mama/c_cpp/src/c/mama/log.h \| 349 ++++++++++++++++++++++++++++------- mama/c_cpp/src/c/mama/price.h \| 4 + mama/c_cpp/src/c/mama/subscmsgtype.h \| 23 ++- 5 files changed, 519 insertions(+), 129 deletions(-) diff --git a/mama/c_cpp/src/c/mama/ft.h b/mama/c_cpp/src/c/mama/ft.h index 89403cd..9421aac 100644 --- a/mama/c_cpp/src/c/mama/ft.h +++ b/mama/c_cpp/src/c/mama/ft.h @@ -28,25 +28,50 @@ extern "C" { #endif +/** + * The enumeration of fault tolerant states + / typedef enum mamaFtState_ { - MAMA_FT_STATE_STANDBY = 0, - MAMA_FT_STATE_ACTIVE = 1, - MAMA_FT_STATE_UNKNOWN = 99 + MAMA_FT_STATE_STANDBY = 0, /< The mamaFtMember is currently not + the highest weighted member in the + group / + MAMA_FT_STATE_ACTIVE = 1, /*< The mamaFtMember is currently the + highest weighted member in the + group / + MAMA_FT_STATE_UNKNOWN = 99 /*< The mamaFtMember has yet to + establish its state / } mamaFtState; +/** + * The enumeration of fault tolerant types + / typedef enum mamaFtType_ { - MAMA_FT_TYPE_MULTICAST = 1, - MAMA_FT_TYPE_BRIDGE = 2, - MAMA_FT_TYPE_MAX = 3 + MAMA_FT_TYPE_MULTICAST = 1, /< MAMA creates sockets directly for + sending and receiving heartbeats. + The middleware is not used / + MAMA_FT_TYPE_BRIDGE = 2, /*< Use the middleware and MAMA + subscriptions for sending and + receiving heartbeats / + MAMA_FT_TYPE_MAX = 3 /*< Used internally / } mamaFtType; typedef void* mamaFtMember; /** - * Callback function type for MAMA fault tolerance events. + * @brief Callback function type for MAMA fault tolerant state change + * events. + * + * @param[in] ftMember The mamaFtMember to which the callback event + * applies + * @param[in] groupName The group name of the mamaFtMember for which the + * fault tolerant event applies + * @param[in] mamaFtState The new fault tolerant state for the group + * member + * @param[in] closure The closure passed to the mamaFtMember when + * mamaFtMember_setup() is called / typedef void ( MAMACALLTYPE @@ -56,9 +81,17 @@ MAMACALLTYPE void closure); /** - * Allocate a MAMA fault tolerance group member. This function is + * @brief Allocate a MAMA fault tolerance group member. This function is * typically followed by mamaFtMember_setup() and * mamaFtMember_activate(). + * + * @param[out] member A pointer to a mamaFtMember. When the function is + * called successfully the ftMember will be a pointer + * to a block of allocated memory. + * + * @return mama_status return code can be one of: + * MAMA_STATUS_NOMEM + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status @@ -66,9 +99,30 @@ mamaFtMember_create ( mamaFtMember member); /** - * Set up a MAMA fault tolerance group member. This is only an + * @brief Set up a MAMA fault tolerance group member. This is only an * initialization function. In order to actually start the fault * tolerance monitoring, use mamaFtMember_activate(). + * + * @param[in] member The mamaFtMember to be initialized + * @param[in] fttype The type of fault tolerance to be used for the + * member + * @param[in] eventQueue The queue on which the mamaFtMember sends and + * receives heartbeats + * @param[in] transport The mamaTransport used for sending and receiving * heartbeats + * @param[in] groupName The group name for the mamaFtMember + * @param[in] weight The initial weight of the mamaFtMember + * @param[in] heartbeatInterval The time in seconds between sending + * heartbeats + * @param[in] timeoutInterval The time in seconds that a mamaFtMember in + * state MAMA_FT_STATE_STANBY or MAMA_FT_STATE_UNKNOWN will + * wait to receive a heartbeat before changing state to + * MAMA_FT_STATE_ACTIVE + * @param[in] closure The closure will be passed to subsequent callback + * invocations for thie mamaFtMember + * + * @return mama_status MAMA_STATUS_OK will be returned on success, + * otherwise a mama_status code indicating failure will be + * returned / MAMAExpDLL extern mama_status @@ -85,7 +139,14 @@ mamaFtMember_setup ( void closure); /** - * Create a MAMA fault tolerance group member. + * @brief Destroy a MAMA fault tolerance group member. + * + * @param[in] member The mamaFtMember. When the function returns, memory * previously allocated for the member will have been + * freed + * + * @return mama_status return code can be one of: + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status @@ -93,7 +154,15 @@ mamaFtMember_destroy ( mamaFtMember member); /* - * Activate the MAMA fault tolerance group member. + * @brief Activate the MAMA fault tolerance group member. The member + * will begin to send and receive heartbeats. If the member is + * already active, this function call will deactivate it + * + * @param[in] member The mamaFtMember + * + * @return mama_status MAMA_STATUS_OK will be returned on success, + * otherwuse a mama_status code indicating failure will be + * returned / MAMAExpDLL extern mama_status @@ -101,7 +170,14 @@ mamaFtMember_activate ( mamaFtMember member); /* - * Deactivate the MAMA fault tolerance group member. + * @brief Deactivate the MAMA fault tolerance group member. The member + * will stop sending and listening for heartbeats. + * + * @param[in] member the mamaFtMember + * + * @return mama_status return code can be one of: + * MAMA_STATUS_INVALID_ARG + * MAAM_STATUS_OK / MAMAExpDLL extern mama_status @@ -109,9 +185,17 @@ mamaFtMember_deactivate ( mamaFtMember member); /* - * Get whether the MAMA fault tolerance member is actively running + * @brief Get whether the MAMA fault tolerance member is actively running * (not related to its state). Use mamaFtMember_getState() to * determine the actual state of the member. + * + * @param[in] member The mamaFtMember + * @param[out] result This will be set to 1 if the member is currently + * active, 0 if it is not + * + * @return mama_status return code can be one of: + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status @@ -120,7 +204,15 @@ mamaFtMember_isActive ( int result); /** - * Get the group name to which this MAMA FT member belongs. + * @brief Get the name of the group to which this MAMA FT member belongs. + * + * @param[in] member The mamaFtMember + * @param[out] result When the function is called successfully, this + * will point to the member's group name + * + * @result mama_status return code can be on of: + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status @@ -129,7 +221,15 @@ mamaFtMember_getGroupName ( const char* result); /** - * Get the fault tolerance weight of the MAMA FT member. + * @brief Get the fault tolerance weight of the MAMA FT member. + * + * @param[in] member The mamaFtMember + * @param[out] result When the function is called successfully, this + * will store the value of the member's weight + * + * @result mama_status return code can be one of: + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status @@ -138,7 +238,14 @@ mamaFtMember_getWeight ( mama_u32_t result); /** - * Get the fault tolerance heartbeat interval of the MAMA FT member. + * @brief Get the fault tolerance heartbeat interval of the MAMA FT + * member. + * @param[in] member The mamaFtMember + * @param[out] result When the function is called successfully, this will * store the value of the member's heartbeat interval + * + * @return mama_status return code can be one of: + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status @@ -147,7 +254,15 @@ mamaFtMember_getHeartbeatInterval ( mama_f64_t result); /** - * Get the fault tolerance timeout interval of the MAMA FT member. + * @brief Get the fault tolerance timeout interval of the MAMA FT member. + * + * @param[in] member The mamaFtMember + * @param[out] result When the function is called successfully, this will + * store the value of the member's timeout interval + * + * @return mama_status return code can be one of: + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status @@ -165,8 +280,15 @@ mamaFtMember_getHeartbeatTick ( mama_u32_t result); /** - * Get the closure argument (provided in the mamaFtMember_create() + * @brief Get the closure argument (provided in the mamaFtMember_setup() * function) of the MAMA FT member. + * + * @param[in] member The mamaFtMember + * @param[out] result When the function is called successfully, this will * point to member's closure + * + * @return mama_status return code can be one of: + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status @@ -175,9 +297,16 @@ mamaFtMember_getClosure ( void* result); /** - * Set the fault tolerance weight of the MAMA FT member. The FT + * @brief Set the fault tolerance weight of the MAMA FT member. The FT * weight can be changed dynamically, if desired. The member with the * highest weight will become the active member. + * + * @param[in] member The mamaFtMember + * @param[in] value The new fault tolerance weight + * + * @return mama_status return code can be one of: + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status @@ -186,16 +315,24 @@ mamaFtMember_setWeight ( mama_u32_t value); /* - * Set the instance ID of the MAMA FT member. The instance ID is used - * to uniquely identify members of a fault tolerant group. Most - * applications should allow the MAMA API to automatically set the - * instance ID and this function would not be called. If not set - * explicitly before activation, then the instance ID is automatically - * set according to the following format: + * @brief Set the instance ID of the MAMA FT member. The instance ID + * is used to uniquely identify members of a fault tolerant group. * + * @details Most applications should allow the MAMA API to automatically + * set the instance ID and this function would not be called. If * not set explicitly before activation, then the instance ID is + * automatically set according to the following format: * {group-name}.{hex-ip-addr}.{hex-pid}. * For example, if the group name is "FOO", the IP address is - * 192.168.187.9, and the PId is 10777, the default instance ID would be: + * 192.168.187.9, and the PId is 10777, the default instance ID + * would be: * FOO.c0a8bb9.2a19 + * + * @param[in] member The mamaFtMember + * @param[in] The new instance ID. This string is copied by the function + * + * @return mama_status return code can be one of: + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_NOMEM + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status @@ -204,9 +341,13 @@ mamaFtMember_setInstanceId ( const char id); /** - * Convert a fault tolerant state to a string. + * @brief Convert a fault tolerant state to a string. + * + * @param[in] state The state to convert. * - * @param state The state to convert. + * @return const char* A string representation of the state. This will + * be either "standby", "active", "unknown", or "error" in the + * case where the current state is unrecognised / MAMAExpDLL extern const char diff --git a/mama/c_cpp/src/c/mama/io.h b/mama/c_cpp/src/c/mama/io.h index 7c5a5cf..ff5453b 100644 --- a/mama/c_cpp/src/c/mama/io.h +++ b/mama/c_cpp/src/c/mama/io.h @@ -31,52 +31,52 @@ extern "C" #endif /** - * IO Types. Not all implementation support all mamaIoTypes. + * @brief IO Types. * - * MAMA_IO_READ: the socket is readable. - * MAMA_IO_WRITE: the socket is writable. - * MAMA_IO_CONNECT: the socket is connected - * MAMA_IO_ACCEPT: the socket accepted a connection - * MAMA_IO_CLOSE: the socket was closed - * MAMA_IO_ERROR: an error occurred - * MAMA_IO_EXCEPT: An exceptional event like out of band data occurred. + * @details Note not all implementations support all mamaIoTypes. / typedef enum { - MAMA_IO_READ, - MAMA_IO_WRITE, - MAMA_IO_CONNECT, - MAMA_IO_ACCEPT, - MAMA_IO_CLOSE, - MAMA_IO_ERROR, - MAMA_IO_EXCEPT + MAMA_IO_READ, /< the socket is readable / + MAMA_IO_WRITE, /*< the socket is writable / + MAMA_IO_CONNECT, /*< the socket is connected / + MAMA_IO_ACCEPT, /*< the socket accepted a connection / + MAMA_IO_CLOSE, /*< the socket was closed / + MAMA_IO_ERROR, /*< an error occurred / + MAMA_IO_EXCEPT /*< An exceptional event like out of band data occurred / } mamaIoType; /** - * Prototype for callback invoked by IO handler. + * @brief Prototype for callback invoked by IO handler. * - * @param io The mamaIo handle. - * @param ioType The mamaIoType for the event. - * @param closure Caller supplied closure. + * @param[in] io The mamaIo handle. + * @param[in] ioType The mamaIoType for the event. + * @param[in] closure Caller supplied closure. / typedef void (MAMACALLTYPE mamaIoCb) (mamaIo io, mamaIoType ioType, void* closure); /** - * Create a IO handler. + * @brief Create a IO handler. * - * If the underlying infrastructure does not support the requested mamaIoType, + * @details If the underlying infrastructure does not support the requested mamaIoType, * mamaIo_create returns MAMA_STATUS_UNSUPPORTED_IO_TYPE. For example RV only * supports READ, WRITE, and EXCEPT. LBM supports all types except ERROR. * - * @param result A pointer to the io handle. - * @param queue The event queue for the io events. NULL specifies the Mama + * @param[in] result A pointer to the io handle. + * @param[in] queue The event queue for the io events. NULL specifies the Mama * default queue. - * @param action The callback to be invoked when an event occurs. - * @param descriptor Wait for IO on this descriptor. - * @param ioType Wait for occurrences of this type. - * @param closure The closure that is passed to the callback. + * @param[in] action The callback to be invoked when an event occurs. + * @param[in] descriptor Wait for IO on this descriptor. + * @param[in] ioType Wait for occurrences of this type. + * @param[in] closure The closure that is passed to the callback. + * + * @return mama_status return code can be one of: + * MAMA_STATUS_NULL_ARG + * MAMA_STATUS_INVALID_QUEUE + * MAMA_STATUS_NO_BRIDGE_IMPL + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status mamaIo_create (mamaIo result, @@ -87,13 +87,30 @@ mama_status mamaIo_create (mamaIo* result, void* closure); /** - * Get the descriptor. + * @brief Get the IO descriptor. + * + * @param[in] io The mamaIo handle. + * + * @param[out] d The associated descriptor for the mamaIO handle. + * + * @return mama_status return code can be one of: + * MAMA_STATUS_NULL_ARG + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_NO_BRIDGE_IMPL / MAMAExpDLL extern mama_status mamaIo_getDescriptor (mamaIo io, uint32_t d); /** - * Destroy the IO. + * @brief Destroy the IO. + * + * @param[in] io The mamaIo handle to be destroyed. + * + * @return mama_status return code can be one of: + * MAMA_STATUS_NULL_ARG + * MAMA_STATUS_NO_BRIDGE_IMPL + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status mamaIo_destroy (mamaIo io); diff --git a/mama/c_cpp/src/c/mama/log.h b/mama/c_cpp/src/c/mama/log.h index b988a6c..c9e52fe 100644 --- a/mama/c_cpp/src/c/mama/log.h +++ b/mama/c_cpp/src/c/mama/log.h @@ -32,262 +32,469 @@ extern "C" #include "mama/status.h" -/* The level of detail when logging is enabled within the API / +/* + * @brief MAMA Log Level + * + * @details The level of detail when logging is enabled within the API + / typedef enum { - MAMA_LOG_LEVEL_OFF = 0, - MAMA_LOG_LEVEL_SEVERE = 1, - MAMA_LOG_LEVEL_ERROR = 2, - MAMA_LOG_LEVEL_WARN = 3, - MAMA_LOG_LEVEL_NORMAL = 4, - MAMA_LOG_LEVEL_FINE = 5, - MAMA_LOG_LEVEL_FINER = 6, - MAMA_LOG_LEVEL_FINEST = 7 + MAMA_LOG_LEVEL_OFF = 0, /< No logging / + MAMA_LOG_LEVEL_SEVERE = 1, /*< Severe logging level / + MAMA_LOG_LEVEL_ERROR = 2, /*< Error logging level / + MAMA_LOG_LEVEL_WARN = 3, /*< Warning logging level / + MAMA_LOG_LEVEL_NORMAL = 4, /*< Normal log level / + MAMA_LOG_LEVEL_FINE = 5, /*< Start/Shutdown logging level / + MAMA_LOG_LEVEL_FINER = 6, /*< Object creation logging level / + MAMA_LOG_LEVEL_FINEST = 7 /*< Message logging level / } MamaLogLevel; -/** The policy to control log file size / +/* + * @brief MAMA Log Policy + * + * @details The policy to control log file size + / typedef enum { - LOGFILE_UNBOUNDED = 1, - LOGFILE_ROLL = 2, - LOGFILE_OVERWRITE = 3, - LOGFILE_USER = 4 + LOGFILE_UNBOUNDED = 1, /< Default - No restrictions / + LOGFILE_ROLL = 2, /*< Logfile will roll / + LOGFILE_OVERWRITE = 3, /*< Logfile will overwrite / + LOGFILE_USER = 4 /*< User defined callback / } mamaLogFilePolicy; -/** The prototype of the MAMA logging functions / +/* + * @brief Definition of a callback + / typedef void (MAMACALLTYPE mamaLogCb) (MamaLogLevel level, const char format, va_list ap); + +/* + * @brief Definition of a callback + / typedef void (MAMACALLTYPE mamaLogCb2) (MamaLogLevel level, const char message); + +/* + * @brief Definition of a callback + / typedef void (logSizeCbType) (void); -/** The default logging within the API unless otherwise specified / +/* + * @brief The default logging within the API unless otherwise specified + * + * @param[in] level The log level. + * @param[in] format The format of log message. + * @param[in] ap Variable argument list. + / MAMAExpDLL extern void MAMACALLTYPE mama_logDefault (MamaLogLevel level, const char format, va_list ap); /** - * This second logging function takes only a message and not a format string with + * @brief Second Log Function + * + * @details This second logging function takes only a message and not a format string with * a variable argument list. It is required for interoperability with all platforms * that do not support C variable argument list, (e.g. .Net). * Other than that it performs in exactly the same way as the first. * - * @param level (in) The log level. - * @param message (in) The message to log. + * @param[in] level The log level. + * @param[in] message The message to log. / MAMAExpDLL extern void MAMACALLTYPE mama_logDefault2 (MamaLogLevel level, const char message); +/** + * @brief Log to Standard Output + * + * @param[in] level The log level. + * @param[in] format The format of log message. + * @param[in] ... Variable argument list. + / MAMAExpDLL extern void mama_logStdout (MamaLogLevel level, const char format, ...); -/** The default function used within the API for the mama_forceLog function - * pointer +/** + * @brief Forced Log Function + * + * @details The default function used within the API for the mama_forceLog function + * pointer. If no logfile is available logging it to stderr. + * + * @param[in] level The log level. + * @param[in] format The format of log message. + * @param[in] ap Variable argument list. / MAMAExpDLL extern void MAMACALLTYPE mama_forceLogDefault (MamaLogLevel level, const char format, va_list ap); -/** The current log level within the API/ + +/* + * The current log level within the API + * deprecated - The helper functions should be used instead of this + / MAMAExpDLL extern MamaLogLevel gMamaLogLevel; -/* The file to which all logging will be written by default/ +/* + * The file to which all logging will be written by default + * deprecated - The helper functions should be used instead of this + / MAMAExpDLL extern FILE gMamaLogFile; /** - * Enable logging. No per-message or per-tick messages appear at + * @brief Enable Logging. + * + * @details No per-message or per-tick messages appear at * <code>WOMBAT_LOG_LEVEL_FINE</code>. <code>WOMBAT_LOG_LEVEL_FINER</code> and * <code>WOMBAT_LOG_LEVEL_FINEST</code> provide successively more detailed * logging. * - * @param file File to write to. - * @param level Output level. - * @see Level + * @param[in] file File to write to. + * @param[in] level Output level. + * + * @return mama_status return code can be one of: + * MAMA_STATUS_PLATFORM + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status mama_enableLogging (FILE file, MamaLogLevel level); /** - * Behaves as mama_enableLogging() but accepts a string representing the file + * @brief Behaves as mama_enableLogging() but accepts a string representing the file * location. * - * @param file The path to the file. Can be relative, absolute or on + * @param[in] file The path to the file. Can be relative, absolute or on * $WOMBAT_PATH. - * @param level The level at which the API should log messages. + * @param[in] level The level at which the API should log messages. + * + * @return mama_status return code can be one of: + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_PLATFORM + * MAMA_STATUS_IO_ERROR + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status mama_logToFile (const char file, MamaLogLevel level); -/** Disable logging. / +/* + * @brief Disable logging + * + * @return mama_status return code can be one of: + * MAMA_STATUS_INVALID_ARG + * MAMA_STATUS_OK + / MAMAExpDLL extern mama_status mama_disableLogging(void); -/* Used for the majority of logging within the API/ +/* + * @brief Used for the majority of logging within the API + * + * @param[in] level The log level. + * @param[in] format The format of log message. + * @param[in] ... Variable argument list. + / MAMAExpDLL extern void mama_log (MamaLogLevel level, const char format, ...); +/** + * @brief Second Log Function + * + * @param[in] level The log level. + * @param[in] message The message it log. + / MAMAExpDLL extern void MAMACALLTYPE mama_log2 (MamaLogLevel level, const char message); +/** + * @brief Used for of logging within the API + * + * @param[in] level The log level. + * @param[in] format The format of log message. + * @param[in] args Variable argument list. + / MAMAExpDLL extern void mama_logVa (MamaLogLevel level, const char format, va_list args); -/** Used for the force logging using variable argument parameters/ +/* + * @brief Used the force logging using variable argument parameters + * + * @param[in] format The format of log message. + * @param[in] args Variable argument list. + / MAMAExpDLL extern void mama_forceLogVa(const char format, va_list args); + +/** Used to add a custom prefix to the start of the line being loggedf / +MAMAExpDLL +extern void +mama_forceLogVaWithPrefix (const char level, + const char* format, + va_list args); + + +/** + * @brief Used for of logging within the API + * + * @param[in] level The log level. + * @param[in] format The format of log message. + * @param[in] ... Variable argument list. + / MAMAExpDLL extern void mama_forceLog (MamaLogLevel level, const char format, ...); /** - * Set the callback to be used for mama_log calls. If not set then - * mama_logDefault will be used + * @brief Set the callback to be used for mama_log calls. If not set then + * mama_logDefault will be used. + * + * @param[in] callback The callback to be set + * + * @return mama_status return code can be one of: + * MAMA_STATUS_NULL_ARG + * MAMA_STATUS_PLATFORM + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status mama_setLogCallback (mamaLogCb callback); /* - * Set the callback to be used for mama_log calls. This function + * @brief Second set callback function + * + * @details Set the callback to be used for mama_log calls. This function * will set a log callback that receives a formatted string and not * a variable argument list. This function is used mainly to support * managed clients. * - * @param callback (in) The callback to be used. Pass NULL to restore + * @param[in] callback The callback to be used. Pass NULL to restore * the mama_logDefault function. - * @return MAMA_STATUS_OK + * + * @return mama_status return code can be one of: + * MAMA_STATUS_PLATFORM + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status mama_setLogCallback2 (mamaLogCb2 callback); /* - * Set the callback to be used for mama logging. If not set then - * mama_ForceLogDefault will be used + * @brief Set the callback to be used for mama logging. If not set then + * mama_ForceLogDefault will be used. + * + * @param[in] callback Callback to be set. + * + * @return mama_status return code can be one of: + * MAMA_STATUS_NULL_ARG + * MAMA_STATUS_PLATFORM + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status mama_setForceLogCallback (mamaLogCb callback); -/* Sets the log level for Mama / +/* + * @brief Sets the log level for Mama. + * + * @param[in] level The log level to be set. + * + * @return mama_status return code can be one of: + * MAMA_STATUS_NULL_ARG + * MAMA_STATUS_PLATFORM + * MAMA_STATUS_OK + / MAMAExpDLL extern mama_status mama_setLogLevel (MamaLogLevel level); -/* Returns the current log level for Mama. / +/* + * @brief Returns the current log level for Mama. + * + * @return MamaLogLevel. + / MAMAExpDLL extern MamaLogLevel mama_getLogLevel (void); /* - * Set the maxmum size of the log file (bytes). When this size is reached the - * logsize callback is called, or if no callback is set then the default action - * is to overwrite file from the start. + * @brief Set the maxmum size of the log file (bytes). + * + * @details When this size is reached the logsize callback is called, or + * if no callback is set then the default action is to overwrite file + * from the start. * Default max size is 500 Mb + * + * @param[in] size The max size of a logfile + * + * @return mama_status return code can be one of: + * MAMA_STATUS_PLATFORM + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status mama_setLogSize (unsigned long size); /* - * Set the number of rolled logfiles to keep before overwriting. - * Default is 10 + * @brief Set the number of rolled logfiles to keep before overwriting. + * + * @details Default is 10. + * + * @param[in] numFiles The number of files to keep + * + * @return mama_status return code can be one of: + * MAMA_STATUS_PLATFORM + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status mama_setNumLogFiles(int numFiles); /* - * Set the policy regarding how to handle files when Max file size is reached. - * Default is LOGFILE_UNBOUNDED + * @brief Set the policy regarding how to handle files when Max file size is reached. + * + * @details Default is LOGFILE_UNBOUNDED. + * + * @param[in] policy The MAMA logfile policy to use. + * + * @return mama_status return code can be one of: + * MAMA_STATUS_PLATFORM + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status mama_setLogFilePolicy(mamaLogFilePolicy policy); -/* Set append to existing log file / +/* + * @brief Set append to existing log file + * + * @param[in] append Boolean value indicating whether to append to the logfile. + * + * @return mama_status return code can be one of: + * MAMA_STATUS_PLATFORM + * MAMA_STATUS_OK + / MAMAExpDLL extern mama_status mama_setAppendToLogFile(int append); -/* Return status of loggingToFile / +/* + * @brief Return status of loggingToFile. + * + * @return Boolean value indication whether logginToFile is set. + / MAMAExpDLL extern int mama_loggingToFile(void); /* - * Set a callback for when the max log size is reached. This can be used to - * override the default action which is to wrap the file and continue logging at - * the beginning + * @brief Set a callback for when the max log size is reached. + * + * @details This can be used to override the default action which is to + * wrap the file and continue logging at the beginning + * + * @param[in] logCallbacks The log size calback to be set + * + * @return mama_status return code can be one of: + * MAMA_STATUS_NULL_ARG + * MAMA_STATUS_PLATFORM + * MAMA_STATUS_OK / MAMAExpDLL extern mama_status mama_setLogSizeCb(logSizeCbType logCallbacks); -/* Return string version of log level / +/* + * @brief Return string version of log level. + * + * @param[in] level The level to return as a string value. + / MAMAExpDLL extern const char mama_logLevelToString(MamaLogLevel level); /** - * Try to convert string to log level - * Return non-zero for success, zero for failure - * The string comparison is case insensitive + * @brief Try to convert string to log level. + * + * @details Return non-zero for success, zero for failure. + * The string comparison is case insensitive. + * + * @param[in] s The string representation of a log level. + * + * @param[out] level The MAMA log level equivalent. / MAMAExpDLL extern int mama_tryStringToLogLevel(const char s, MamaLogLevel* level); -/** Return string version of log policy / +/* + * @brief Return string version of log policy. + * + * @param[in] level The MAMA logfile policy to convert into its string equi +valent. + / MAMAExpDLL extern const char mama_logPolicyToString(mamaLogFilePolicy level); /** - * Try to convert string to log policy. - * Return non-zero for success, zero for failure. + * @brief Try to convert string to log policy. + * + * @details Return non-zero for success, zero for failure. * The string comparison is case insensitive. + * + * @param[in] s The string representation of a MAMA logfile policy. + * + * @param[out] policy The MAMA logfile policy string equivalent. / MAMAExpDLL extern int mama_tryStringToLogPolicy(const char s, mamaLogFilePolicy* policy); /** - * Increase by one log level the verbosity of a MamaLogLevel variable. - * If the level is already at the maximum verbosity it will be unchanged + * @brief Increase by one log level the verbosity of a MamaLogLevel variable. + * + * @details If the level is already at the maximum verbosity it will be unchanged * after calling the function, otherwise the level will be incremented. * Returns zero if level is not changed, or non-zero if it is changed * If an unrecognized level is passed, the function will return * non-zero and the variable will be set to the minimum verbosity + * + * @param[in] level The MAMA Log level to increment. + * + * @return boolean value, 1 it the log level was incremented successfully. / MAMAExpDLL extern int mama_logIncrementVerbosity(MamaLogLevel level); /** - * Decrease by one log level the verbosity of a MamaLogLevel variable. - * If the level is already at the minimum verbosity it will be unchanged + * @brief Decrease by one log level the verbosity of a MamaLogLevel variable. + * + * @details If the level is already at the minimum verbosity it will be unchanged * after calling the function, otherwise the level will be decremented. * Returns zero if level is not changed, or non-zero if it is changed * If an unrecognized level is passed, the function will return * non-zero and the variable will be set to the maximum verbosity + * + * @param[in] level The MAMA Log level to increment. + * + * @return boolean value, 1 it the log level was decremented successfully. / MAMAExpDLL extern int mama_logDecrementVerbosity(MamaLogLevel level); /** - * Force rolling the log file. + * @brief Force rolling the log file. * * @return The status of the operation. / @@ -295,10 +502,18 @@ MAMAExpDLL extern mama_status mama_logForceRollLogFiles(void); -/* Destroy memory held by the logging / +/* + * @brief Destroy memory held by the logging. + / void mama_logDestroy(void); +/* + * @brief Setup MAMA Logging. + * + * @details This will setup all the default values from the mama.properties + file + / void mama_loginit (void); diff --git a/mama/c_cpp/src/c/mama/price.h b/mama/c_cpp/src/c/mama/price.h index b134f7e..95b3717 100644 --- a/mama/c_cpp/src/c/mama/price.h +++ b/mama/c_cpp/src/c/mama/price.h @@ -287,6 +287,10 @@ mamaPrice_getIsValidPrice (const mamaPrice price, * @param price The price to get. * @param hints The price hints. + * @return Indicates whether the function succeeded or failed and could be one of: + * - MAMA_STATUS_INVALID_ARG + * - MAMA_STATUS_OK + * @note This function is intended for internal use only. / MAMAExpDLL extern mama_status diff --git a/mama/c_cpp/src/c/mama/subscmsgtype.h b/mama/c_cpp/src/c/mama/subscmsgtype.h index f18bf40..aaba61b 100644 --- a/mama/c_cpp/src/c/mama/subscmsgtype.h +++ b/mama/c_cpp/src/c/mama/subscmsgtype.h @@ -30,6 +30,9 @@ extern "C" { #endif +/* This enumeration describes the type of subscription messsage. + / + typedef enum mamaSubscMsgType { MAMA_SUBSC_SUBSCRIBE = 0, @@ -39,14 +42,24 @@ typedef enum mamaSubscMsgType MAMA_SUBSC_REFRESH = 4, MAMA_SUBSC_DDICT_SNAPSHOT = 5, MAMA_SUBSC_WORLDVIEW_RQST = 6, - MAMA_SUBSC_DQ_SUBSCRIBER = 7, / Subscriber knows it lost data itself / - MAMA_SUBSC_DQ_PUBLISHER = 8, / Subscriber knows publisher lost data / - MAMA_SUBSC_DQ_NETWORK = 9, / Subscriber knows network lost data / - MAMA_SUBSC_DQ_UNKNOWN = 10, / Subscriber lost data but not know why / + MAMA_SUBSC_DQ_SUBSCRIBER = 7, /< Subscriber knows it lost data itself / + MAMA_SUBSC_DQ_PUBLISHER = 8, /*< Subscriber knows publisher lost data / + MAMA_SUBSC_DQ_NETWORK = 9, /*< Subscriber knows network lost data / + MAMA_SUBSC_DQ_UNKNOWN = 10, /*< Subscriber lost data but not know why / MAMA_SUBSC_FEATURE_SET_RQST = 11, - MAMA_SUBSC_DQ_GROUP_SUBSCRIBER = 12 /* Subscriber knows it lost data itself / + MAMA_SUBSC_DQ_GROUP_SUBSCRIBER = 12 /< Subscriber knows it lost data itself / } mamaSubscMsgType; +/** +* @brief Return a string representation for a subscribe message type +* +* @param[in] mamaSubscMsgType The MAMA subscribe message type +* +* @return The returned string showing the message type. +* +*/ + + MAMAExpDLL extern const char MamaSubscMsgTypeStr (mamaSubscMsgType msgType); -- 1.8.4.msysgit.0 This message may contain confidential information and is intended for specific recipients unless explicitly noted otherwise. If you have reason to believe you are not an intended recipient of this message, please delete it and notify the sender. This message may not represent the opinion of IntercontinentalExchange Group, Inc. (ICE), NYSE Euronext or any of their subsidiaries or affiliates, and does not constitute a contract or guarantee. Unencrypted electronic mail is not secure and the recipient of this message is expected to provide safeguards from viruses and pursue alternate means of communication where privacy or a binding message is desired.
More

1 - 1 of 1

1

Previous Topic Next Topic

Home Hashtags Subgroups Terms