/*
 * $Id: webapi.h,v 5.9 2002/05/29 03:40:52 martin Exp $
 *
 * BuildProfessional Web-API Client Library Interface.
 *
 * DLL export declarations for Windows DLL-users.
 *
 * Copyright (C) 2001-2002 TODAY Systems, Inc.
 *
 */
#ifndef __WEBAPI_DLL_H
#define __WEBAPI_DLL_H


#ifndef _WIN32
#error "The Web-API Client Library DLL is only available on Windows platforms."
#endif

/*
 * Module loading and configuration interface:
 *  int WINAPI webApiStartup(void);
 *  int WINAPI webApiCleanup(void);
 *  int WINAPI webApiSetRequestPath(const char* path);
 *  int WINAPI webApiSetFileDump(int dump);
 *  int WINAPI webApiSetLogFile(const char* path);
 *  int WINAPI webApiSetLogLevel(int level);
 *
 * Request interface:
 *  int WINAPI webApiStatusRequest(const char* host, int timeout);
 *  int WINAPI webApiMemRequest(const char* req, int timeout);
 *  int WINAPI webApiMemRequestRaw(const char* req, int timeout);
 *  int WINAPI webApiFileRequest(const char* path, int timeout);
 *  int WINAPI webApiFileRequestReply(const char* reqpath,
 *                                    const char* reppath,
 *                                    int         timeout);
 *  int WINAPI webApiFileRequestRaw(const char* path, int timeout);
 *  int WINAPI webApiFileRequestReplyRaw(const char* reqpath,
 *                                       const char* reppath,
 *                                       int         timeout);
 *  int WINAPI webApiWriteLastReply(const char* path);
 *
 * Error handling interface:
 *  int WINAPI webApiWriteLastFault(const char* path);
 *
 */


/* Error codes */

/*
 * Bad argument.
 * The system detected an invalid argument when calling one of the functions.
 */
#define WEBAPIEFAULT 10014

/*
 * Web-API subsystem is down.
 * A Web-API operation encountered a dead network or similar serious failure.
 */
#define WEBAPIDOWN 10050

/*
 * Request timed out.
 * The client-side timeout expired before receiving a reply from the manager.
 * (Server-side will still complete the request according to it's own timeout.)
 */
#define WEBAPITIMEDOUT 10060

/*
 * Web-API manager unavailable.
 * No connection could be made to the Web-API manager because the connection
 * was refused by the target machine. Either the manager is not started,
 * it is listening on a different port numer, or there is a network problem
 * (e.g. a firewall is blocking the Web-API port).
 */
#define WEBAPICONNREFUSED 10061

/* Web-API subsystem unavailable.
 * Could not initialise the networking subsystem, probably because TCP/IP is
 * not properly configured on the client machine. Check for system log errors.
 */
#define WEBAPISYSNOTREADY 10091

/* Successful Web-API startup not yet performed.
 * Either the application has not called webApiStartup, webApiStartup failed,
 * or the appplication has called webApiCleanup too many times.
 */
#define WEBAPINOTINITIALISED 10093

/* Server error.
 * Use webApiWriteLastFault to determine the cause of failure.
 */
#define WEBAPITRY_AGAIN 11002


/* Exported functions */

#ifdef __cplusplus
extern "C" {  // only need to export C interface if
              // used by C++ source code
#endif

#ifndef WEBAPI_LINKAGE
# define WEBAPI_LINKAGE dllimport
#endif

/*
 * webApiStartup - initialise the Web-API request subsystem.
 *
 * Parameters:
 *  none
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Post conditions:
 *  After calling this function the following default settings are loaded:
 *   RequestPath	(none)
 *   FileDump		off
 *   LogFile		(none)
 *   LogLevel		0
 *   Timeout        90
 *   ManagerHost    localhost
 *   ManagerPort    3380
 */
__declspec(WEBAPI_LINKAGE) int WINAPI webApiStartup(void);

/*
 * webApiCleanup - shut down the Web-API request subsystem and relase memory.
 *
 * Parameters:
 *  none
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI webApiCleanup(void);

/*
 * webApiSetRequestPath - set the file dump path.
 *
 * Parameters:
 *  const char* path - full path where request/response files will be saved.
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Post conditions:
 *  Calling this function will overwrite any previous setting.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI webApiSetRequestPath(const char* path);

/*
 * webApiSetFileDump - set the file dump flag.
 *
 * Parameters:
 *  int - filedump enable flag, 0 to disable.
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Post conditions:
 *  Calling this function will overwrite any previous setting.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI webApiSetFileDump(int dump);

/*
 * webApiSetLogFile - set the log file.
 *
 * Parameters:
 *  const char* path - full path to the logfile.
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Post conditions:
 *  Calling this function will overwrite any previous setting.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI webApiSetLogFile(const char* path);

/*
 * webApiSetLogLevel - set the log level.
 *
 * Parameters:
 *  int - log level (see the Web-API User's Manual for valid levels).
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Post conditions:
 *  Calling this function will overwrite any previous setting.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI webApiSetLogLevel(int level);

/*
 * webApiStatusRequest - generate a status request and send to the Manager.
 *
 * Parameters:
 *  const char* host - manager host as "hostname_or_ip:port",
 *                     or NULL to use current default (i.e. "localhost:3380").
 *  int timeout      - timeout in seconds.
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Pre conditions:
 *  Any old replydata must be retrieved with webApiWriteLastReply, otherwise
 *  it will be overwritten by this request.
 *
 * Post conditions:
 *  Use webApiWriteLastReply or webApiWriteLastFault to retrieve bpxml data.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI webApiStatusRequest(const char* host,
														  int         timeout);

/*
 * webApiMemRequest - send the specified request to the Manager.
 *
 * Parameters:
 *  const char* req - bpxml data for this request.
 *  int timeout     - timeout in seconds.
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Pre conditions:
 *  Any old reply data must be retrieved with webApiWriteLastReply, otherwise
 *  it will be overwritten by this request.
 *
 * Post conditions:
 *  Use webApiWriteLastReply or webApiWriteLastFault to retrieve bpxml data.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI webApiMemRequest(const char* req,
													   int         timeout);

/*
 * webApiMemRequestRaw - send specified request and save unpacked replydata.
 *
 * Parameters:
 *  const char* req - bpxml data for this request.
 *  int timeout     - timeout in seconds.
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Pre conditions:
 *  Any old reply data must be retrieved with webApiWriteLastReply, otherwise
 *  it will be overwritten by this request.
 *
 * Post conditions:
 *  Use webApiWriteLastReply or webApiWriteLastFault to retrieve replydata.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI webApiMemRequestRaw(const char* req,
														  int         timeout);

/*
 * webApiFileRequest - read the specified file and send request to the Manager.
 *
 * Parameters:
 *  const char* path - path to file with bpxml data for this request.
 *  int timeout      - timeout in seconds.
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Pre conditions:
 *  Any old reply data must be retrieved with webApiWriteLastReply, otherwise
 *  it will be overwritten by this request.
 *
 * Post conditions:
 *  Use webApiWriteLastReply or webApiWriteLastFault to retrieve bpxml data.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI webApiFileRequest(const char* path,
														int         timeout);

/*
 * webApiFileRequestReply
 *  - read the specified request file, send it to the Manager, and write reply.
 *
 * Parameters:
 *  const char* reqpath - path to file with bpxml data for this request.
 *  const char* reppath - path to file which will recieve the bpxml reply.
 *  int timeout         - timeout in seconds.
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Pre conditions:
 *  Any old reply data must be retrieved with webApiWriteLastReply, otherwise
 *  it will be overwritten by this request.
 *
 * Post conditions:
 *  The last reply or fault will be written to the specified reply files,
 *  as well as made available through the webApiWriteLastReply or
 *  webApiWriteLastFault functions.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI
webApiFileRequestReply(const char* reqpath,
					   const char* reppath,
					   int         timeout);

/*
 * webApiFileRequestRaw - read file request and save unpacked replydata.
 *
 * Parameters:
 *  const char* path - path to file with bpxml data for this request.
 *  int timeout      - timeout in seconds.
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Pre conditions:
 *  Any old reply data must be retrieved with webApiWriteLastReply, otherwise
 *  it will be overwritten by this request.
 *
 * Post conditions:
 *  Use webApiWriteLastReply or webApiWriteLastFault to retrieve replydata.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI
webApiFileRequestRaw(const char* path,
					 int         timeout);

/*
 * webApiFileRequestReplyRaw
 *  - read the request file, send it to the Manager, and write replydata.
 *
 * Parameters:
 *  const char* reqpath - path to file with bpxml data for this request.
 *  const char* reppath - path to file which will recieve unpacked replydata.
 *  int timeout         - timeout in seconds.
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Pre conditions:
 *  Any old reply data must be retrieved with webApiWriteLastReply, otherwise
 *  it will be overwritten by this request.
 *
 * Post conditions:
 *  The last reply or fault will be written to the specified reply files,
 *  as well as made available through the webApiWriteLastReply or
 *  webApiWriteLastFault functions.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI
webApiFileRequestReplyRaw(const char* reqpath,
						  const char* reppath,
						  int         timeout);

/*
 * webApiWriteLastReply - write the bpxml data from last request.
 *
 * Parameters:
 *  const char* path - full path to the reply file.
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Post conditions:
 *  Calling this function will reset the reply data.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI webApiWriteLastReply(const char* path);

/*
 * webApiWriteLastFault - write the bpxml data from last fault.
 *
 * Parameters:
 *  const char* path - full path to the reply file.
 *
 * Returns:
 *  int - 0 if OK, otherwise any of the Web-API error constants.
 *
 * Post conditions:
 *  Calling this function will reset the error status.
 */
__declspec(WEBAPI_LINKAGE) int WINAPI webApiWriteLastFault(const char* path);

#ifdef __cplusplus
}
#endif


#endif /* __WEBAPI_DLL_H */