smdi.h

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2005-2008, Digium, Inc.
 *
 * Matthew A. Nicholson <mnicholson@digium.com>
 * Russell Bryant <russell@digium.com>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */
 
/*!
 * \file
 * \brief SMDI support for Asterisk.
 * \author Matthew A. Nicholson <mnicholson@digium.com>
 * \author Russell Bryant <russell@digium.com>
 */
 
#ifndef ASTERISK_SMDI_H
#define ASTERISK_SMDI_H
 
#include <termios.h>
#include <time.h>
 
#include "asterisk/config.h"
#include "asterisk/module.h"
#include "asterisk/optional_api.h"
 
#define SMDI_MESG_NAME_LEN 80
#define SMDI_MESG_DESK_NUM_LEN 3
#define SMDI_MESG_DESK_TERM_LEN 4
#define SMDI_MWI_FAIL_CAUSE_LEN 3
#define SMDI_MAX_STATION_NUM_LEN 10
#define SMDI_MAX_FILENAME_LEN 256
 
/*!
 * \brief An SMDI message waiting indicator message.
 *
 * The ast_smdi_mwi_message structure contains the parsed out parts of an smdi
 * message.  Each ast_smdi_interface structure has a message queue consisting
 * ast_smdi_mwi_message structures.
 */
struct ast_smdi_mwi_message {
    char name[SMDI_MESG_NAME_LEN];
    char fwd_st[SMDI_MAX_STATION_NUM_LEN + 1];      /* forwarding station number */
    char cause[SMDI_MWI_FAIL_CAUSE_LEN + 1];        /* the type of failure */
    struct timeval timestamp;               /* a timestamp for the message */
};
 
/*!
 * \brief An SMDI message desk message.
 *
 * The ast_smdi_md_message structure contains the parsed out parts of an smdi
 * message.  Each ast_smdi_interface structure has a message queue consisting
 * ast_smdi_md_message structures.
 */
struct ast_smdi_md_message {
    char name[SMDI_MESG_NAME_LEN];
    char mesg_desk_num[SMDI_MESG_DESK_NUM_LEN + 1];     /* message desk number */
    char mesg_desk_term[SMDI_MESG_DESK_TERM_LEN + 1];   /* message desk terminal */
    char fwd_st[SMDI_MAX_STATION_NUM_LEN + 1];      /* forwarding station number */
    char calling_st[SMDI_MAX_STATION_NUM_LEN + 1];      /* calling station number */
    char type;                      /* the type of the call */
    struct timeval timestamp;               /* a timestamp for the message */
};
 
/*!
 * \brief SMDI interface structure.
 *
 * The ast_smdi_interface structure holds information on a serial port that
 * should be monitored for SMDI activity.  The structure contains a message
 * queue of messages that have been received on the interface.
 */
struct ast_smdi_interface;
 
/*!
 * \brief Get the next SMDI message from the queue.
 * \param iface a pointer to the interface to use.
 *
 * This function pulls the first unexpired message from the SMDI message queue
 * on the specified interface.  It will purge all expired SMDI messages before
 * returning.
 *
 * \return the next SMDI message, or NULL if there were no pending messages.
 */
AST_OPTIONAL_API(struct ast_smdi_md_message *, ast_smdi_md_message_pop,
         (struct ast_smdi_interface *iface),
         { return NULL; });
 
/*!
 * \brief Get the next SMDI message from the queue.
 * \param iface a pointer to the interface to use.
 * \param timeout the time to wait before returning in milliseconds.
 *
 * This function pulls a message from the SMDI message queue on the specified
 * interface.  If no message is available this function will wait the specified
 * amount of time before returning.
 *
 * \return the next SMDI message, or NULL if there were no pending messages and
 * the timeout has expired.
 */
AST_OPTIONAL_API(struct ast_smdi_md_message *, ast_smdi_md_message_wait,
         (struct ast_smdi_interface *iface, int timeout),
         { return NULL; });
 
/*!
 * \brief Get the next SMDI message from the queue.
 * \param iface a pointer to the interface to use.
 *
 * This function pulls the first unexpired message from the SMDI message queue
 * on the specified interface.  It will purge all expired SMDI messages before
 * returning.
 *
 * \return the next SMDI message, or NULL if there were no pending messages.
 */
AST_OPTIONAL_API(struct ast_smdi_mwi_message *, ast_smdi_mwi_message_pop,
         (struct ast_smdi_interface *iface),
         { return NULL; });
 
/*!
 * \brief Get the next SMDI message from the queue.
 * \param iface a pointer to the interface to use.
 * \param timeout the time to wait before returning in milliseconds.
 *
 * This function pulls a message from the SMDI message queue on the specified
 * interface.  If no message is available this function will wait the specified
 * amount of time before returning.
 *
 * \return the next SMDI message, or NULL if there were no pending messages and
 * the timeout has expired.
 */
AST_OPTIONAL_API(struct ast_smdi_mwi_message *, ast_smdi_mwi_message_wait,
         (struct ast_smdi_interface *iface, int timeout),
         { return NULL; });
 
AST_OPTIONAL_API(struct ast_smdi_mwi_message *, ast_smdi_mwi_message_wait_station,
         (struct ast_smdi_interface *iface, int timeout, const char *station),
         { return NULL; });
 
/*!
 * \brief Find an SMDI interface with the specified name.
 * \param iface_name the name/port of the interface to search for.
 *
 * \return an ao2 reference to the interface located or NULL if none was found.
 */
AST_OPTIONAL_API(struct ast_smdi_interface *, ast_smdi_interface_find,
         (const char *iface_name),
         { return NULL; });
 
/*!
 * \brief Set the MWI indicator for a mailbox.
 * \param iface the interface to use.
 * \param mailbox the mailbox to use.
 */
AST_OPTIONAL_API(int, ast_smdi_mwi_set,
         (struct ast_smdi_interface *iface, const char *mailbox),
         { return -1; });
 
/*!
 * \brief Unset the MWI indicator for a mailbox.
 * \param iface the interface to use.
 * \param mailbox the mailbox to use.
 */
AST_OPTIONAL_API(int, ast_smdi_mwi_unset,
         (struct ast_smdi_interface *iface, const char *mailbox),
         { return -1; });
 
#endif /* !ASTERISK_SMDI_H */