/*
 * Copyright 2010 Nathan Phillip Brink
 *
 * This file is a part of DistRen.
 *
 * DistRen is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * DistRen is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with DistRen.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef _DISTREN_TABLETENNIS_H
#define _DISTREN_TABLETENNIS_H

/**
 * @file For managing the PINGs and PONGs of our present life.
 *
 * Do not call ping pong ping pong! Any professional ping-ponger will
 * be immediately offended. Use tabletennis instead and prosper.
 */

#include "distrend.h"

#include <queue.h>
#include <time.h>

struct tabletennis;
typedef struct tabletennis *tabletennis_t;

/**
 * this struct should be embedded into struct distrend_client
 */
struct tabletennis_client
{
  /*
   * the time that the client should be processed from the
   * clients_to_ping or clients_need_pong queues.
   */
  time_t time_next_check;

  enum tabletennis_client_state
    {
      /* in clients_to_ping */
      TABLETENNIS_NEED_PING,
      /* in clients_need_pong */
      TABLETENNIS_NEED_PONG,
      TABLETENNIS_HAS_PONG,
      /* not in any queue */
      TABLETENNIS_DELINQUENT,
    } state;
};

/**
 * Initializes the context data for tabletennis.
 *
 * @param listens to register tabletennis's PING and PONG handlers
 * @param ping_interval The number of seconds to wait before sending a client a PING packet.
 * @param pong_time The number of seconds to wait before checking if a client sent a PONG packet.
 */
tabletennis_t tabletennis_new(struct distrend_listens *listens, unsigned int ping_interval, unsigned int pong_time);

/**
 * Add a client to the tabletennis game.
 *
 * @param tabletennis the tabletennis context.
 * @param client the client
 */
int tabletennis_add_client(tabletennis_t tabletennis, struct distrend_client *client);

/**
 * Sends PING packets to clients that need them and checks that
 * clients have sent PONG packets on time.
 *
 * @param clients_to_ping a queue initialized
 */
int tabletennis_serve(tabletennis_t tabletennis);

/**
 * Remove a client to the tabletennis game.
 *
 * @param tabletennis the tabletennis context.
 * @param client the client
 */
int tabletennis_del_client(tabletennis_t tabletennis, struct distrend_client *client);

/**
 * Deallocates and frees the tabletennis context data.
 *
 * Does not free the distren_client structs
 *
 * @param tabletennis the tabletennis context.
 */
void tabletennis_free(tabletennis_t tabletennis);

#endif