embeddedgmetric.h

/**
 * This is the MIT LICENSE
 * http://www.opensource.org/licenses/mit-license.php
 *
 * Copyright (c) 2007 Nick Galbreath
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use, copy,
 * modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/** \file embbededmetric.h
 *
 * A very simple "gmetric" UDP interface
 *
 * more doco here.
 *
 * basic useage might be:
 * \code
 * gmetric g;
 * gmetric_message msg;
 * gmetric_create(&g);
 * if (!gmetric_open(g, "localhost", 8649)) {
 *    exit(1);
 * }
 * foreach metric {
 *    msg.type = GMETRIC_VALUE_STRING;
 *    msg.name = "foo";
 *    msg.value.v_string = "bar";
 *    msg.unit = "no units";
 *    msg.slope = GMETRIC_SLOPE_BOTH;
 *    msg.tmax = 120;
 *    msg.dmax = 0;
 *    gmetric_send(&g, &msg);
 * }
 * gmetric_close(g);
 * \endcode
 *
 */

#ifndef COM_MODP_EMBEDDED_GMETRIC_H
#define COM_MODP_EMBEDDED_GMETRIC_H

#include <stdint.h>
#include <arpa/inet.h>
#include <netinet/in.h>
#include <sys/types.h>
#include <sys/socket.h>

namespace allyes {
namespace gmetric {

#define GMETRIC_MAX_MESSAGE_LEN (512)

enum gmetric_value_t {
    GMETRIC_VALUE_UNKNOWN = 0,
    GMETRIC_VALUE_STRING,
    GMETRIC_VALUE_UNSIGNED_SHORT,
    GMETRIC_VALUE_SHORT,
    GMETRIC_VALUE_UNSIGNED_INT,
    GMETRIC_VALUE_INT,
    GMETRIC_VALUE_FLOAT,
    GMETRIC_VALUE_DOUBLE,
    GMETRIC_VALUE_MAX
};

enum gmetric_slope_t {
    GMETRIC_SLOPE_ZERO = 0,
    GMETRIC_SLOPE_POSITIVE,
    GMETRIC_SLOPE_NEGATIVE,
    GMETRIC_SLOPE_BOTH,
    GMETRIC_SLOPE_UNSPECIFIED,
    GMETRIC_SLOPE_MAX
};

/**
 * Control structure and shared buffers
 */
struct gmetric_t {
    struct sockaddr_in sa;
    int s;
};

/**
 * message structure
 */
struct gmetric_message_t {
	gmetric_value_t type;
    const char* name;
    const char* units;
    const char* typestr;
    gmetric_slope_t slope;
    uint32_t tmax;
    uint32_t dmax;
	union {
		const char*    v_string;
		unsigned short v_ushort;
		short          v_short;
		unsigned int   v_uint;
		int            v_int;
		float          v_float;
		double         v_double;
	} value;
};

/** \brief "constructor"
 *
 */
void gmetric_create(gmetric_t* g);

/** \brief open a UDP socket
 *
 * open up a socket.  Needs to be done before calling gmetric_send.
 *
 * THIS MAY BE THREAD UNSAFE since it calls gethostbyname.
 *
 * \param[in] addr the hostname to connect to, e.g. "mygmond.com" or "127.0.0.1"
 * \param[in] port the port to connect to, in HOST order
 * \return 1 if ok, 0 if false (boolean)
 */
int gmetric_open(gmetric_t* g, const char* addr, int port);


/** \brief Raw interface to open a gmetric socket that skips gethostbyname_X
 *
 * \param[in] ip the ip address IN NETWORK ORDER
 * \param[in] port IN HOST order (e.g. "8649")
 * \return 1 if ok, 0 if false (boolean)
 */
int gmetric_open_raw(gmetric_t* g, uint32_t ip, int port);

/** \brief send a metric to the socket
 *
 * Must have called gmetric_create, gmetric_open first!
 *
 * This just wraps a call around gmetric_message_create_xdr and
 * gmetric_send_xdr.
 *
 * \param[in] g the socket to use
 * \param[in] msg the message to send
 * \return -1 on error, number of bytes sent on success
 *
 */
int gmetric_send(gmetric_t* g, const gmetric_message_t* msg);

/** \brief Send a raw XDR buffer to gmond
 *
 * "normally" you shouldn't have to use this but it may aid in making
 * optimized batch calls where one can recycle a buffer.
 *
 * \param[in] g the gmetric socket to use
 * \param[in] buf the xdr buffer
 * \param[in] len the length of data
 * \return -1 on error, number of bytes sent on success.
 */
int gmetric_send_xdr(gmetric_t* g, const char* buf, int len);

/** \brief "destructor"
 *
 * \param[in] g the gmetric to close
 */
void gmetric_close(gmetric_t* g);

/** \brief struct to XDR message
 *
 * Internal function but you may find it useful
 * for testing and experimenting
 *
 * \param[out] buffer
 * \param[in]  len length of buffer
 * \param[in] msg the gmetric_message to convert
 * \return -1 on error, length of message on success
 */
int gmetric_message_create_xdr(char* buffer, uint len,
                               const gmetric_message_t* msg);


/** \brief clear out a gmetric_message to know defaults
 *
 */
void gmetric_message_clear(gmetric_message_t* msg);

/** \brief validate a gmetric message
 *
 * \return 1 if ok, 0 if bad
 */
int gmetric_message_validate(const gmetric_message_t* msg);

} /* namespace gmetric */
} /* namespace allyes */

#endif