/*
  Copyright 2008 Nathan Phillip Brink, Ethan Zonca, Matt Orlando

  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_H
#define DISTREN_H 1

/*
  Public API for DistRen
 */

#include <stddef.h> /* size_t */

typedef struct distren *distren_t;

typedef void* (*distren_malloc_t)(size_t);
typedef void (*distren_free_t)(void*);

typedef struct distren_job *distren_job_t;

/**
 Initialize a libdistren handle. In the spirit of respecting client programs' choices,
 this initialization function allows malloc() and free() compatible function pointers
 to be passed.
*/
int distren_init_mf(distren_t *handle, distren_malloc_t mymalloc, distren_free_t myfree);

/**
 Initializes a libdistren handle using the system malloc() and free() implementation.
*/
int distren_init(distren_t *handle);

/**
 Submits a file to distren.
 @param job must not refer to a valid job.
 @TODO create a stream-based interface
*/
int distren_submit_file(distren_t handle, distren_job_t *job, const char *filename);

/**
   Retrieve a job-ID that can be used to refer to the job after the client's process has recycled. Currently, this will be the only way to retrieve a job handle (a distren_job_t) and, consequently, the only way to retrieve a finished render.
   A job ID is representable using a character string. Hopefully, they will be kept at a reasonably small length. It should be made up of alphanumeric characters so as to be useful in most situations. 
   @param jobid This will be set to a string allocated by the specified malloc implementation
   @param job The distren_job_t from which to retrieve a jobid
*/
int distren_job_getid(distren_job_t job, char **jobid);

/**
   Retrieves a tarball of a rendering's result.
   @param outfile Filename to save the result to
 */
int distren_job_retrieve_file(distren_job_t job, const char *outfile);

/*
 TODO: extraction of a job-ID, retrieving job handle by job-ID, getting information
 for a job handle, retrieving results of a job, callbacks for progress (i.e., job_is_finished callback)
 -- threads?
*/

/**
 Destroys and frees a job handle
*/
int distren_job_free(distren_job_t job);

/**
 Destroys and frees a libdistren handle
*/
int distren_free(distren_t handle);

#endif