trktool.h

hl2 source code. Do not use it illegal.

// $Header:   Y:/archives/dv/Tracker/trkar/trktool.h_v   1.73   27 May 1999 13:13:44   michaelg  $
//
// Copyright 1992-1999 Merant, Inc.  All rights reserved.
//
// PVCS Tracker Toolkit API
//
// $Tabs:5 9$
// *******************************************************************

#ifndef _TRKTOOL_H_
#define _TRKTOOL_H_ 1

// *********************************************************
// Data Types and Defines
// *********************************************************

// Define an interface version code which is used to detect
// out of date DLLs.  (see TrkHandleAlloc)
//
#define TRK_VERSION_ID	400005

// Define values specific to 32 bit or 16 bit target environments.
//
#if defined(WIN32)	// Windows NT or Windows 95 (32-bit)

#ifndef FAR
#define FAR
#endif

#ifndef TRK_DECL
#define TRK_DECL		__stdcall
#endif

#ifndef EXPORT32
#define	EXPORT32		__declspec(dllexport)
#endif

#ifndef LOADDS
#define	LOADDS
#endif

#else				// Windows 3.1 (16-bit)

#ifndef FAR
#define FAR				_far
#endif

#ifndef TRK_DECL
#define TRK_DECL		_pascal
#endif

#ifndef EXPORT32
#define	EXPORT32
#endif

#ifndef LOADDS
#define	LOADDS			_loadds
#endif

#endif //!WIN32

// Define the type used to declare all API functions.
//
#ifndef TRKAPI_DEFINED
#define TRKAPI_DEFINED
#define TRKAPI			EXPORT32 unsigned long FAR TRK_DECL
#endif

// Define the primitive data types.
//
typedef char FAR*		TRK_STR;
typedef const char FAR*	TRK_CSTR;
typedef unsigned long	TRK_UINT;
typedef TRK_UINT		TRK_BOOL;
typedef TRK_UINT		TRK_CHAR;
typedef TRK_UINT		TRK_VERSION_ID_TYPE;
typedef TRK_UINT		TRK_DBMS_LOGIN_MODE;
typedef TRK_UINT		TRK_RECORD_TYPE;
typedef TRK_UINT		TRK_FIELD_TYPE;
typedef TRK_UINT		TRK_TRANSACTION_ID;
typedef TRK_UINT		TRK_TIME;
typedef TRK_UINT		TRK_ACCESS_MODE;
typedef TRK_UINT		TRK_FILE_STORAGE_MODE;
typedef TRK_UINT		TRK_LIST_LINK_ORDER;

#define DECLARE_TRK_HANDLE(h)	struct _##h { int unused; };\
								typedef const struct _##h FAR* h

#ifndef TRK_HANDLE_DEFINED
#define TRK_HANDLE_DEFINED
DECLARE_TRK_HANDLE(TRK_HANDLE);
#endif

#ifndef TRK_RECORD_HANDLE_DEFINED
#define TRK_RECORD_HANDLE_DEFINED
DECLARE_TRK_HANDLE(TRK_RECORD_HANDLE);
#endif

#ifndef TRK_NOTE_HANDLE_DEFINED
#define TRK_NOTE_HANDLE_DEFINED
DECLARE_TRK_HANDLE(TRK_NOTE_HANDLE);
#endif

#ifndef TRK_ATTFILE_HANDLE_DEFINED
#define TRK_ATTFILE_HANDLE_DEFINED
DECLARE_TRK_HANDLE(TRK_ATTFILE_HANDLE);
#endif

#ifndef TRK_ASSOC_HANDLE_DEFINED
#define TRK_ASSOC_HANDLE_DEFINED
DECLARE_TRK_HANDLE(TRK_ASSOC_HANDLE);
#endif

#ifndef TRK_EXPORT_HANDLE_DEFINED
#define TRK_EXPORT_HANDLE_DEFINED
DECLARE_TRK_HANDLE(TRK_EXPORT_HANDLE);
#endif

#ifndef TRK_IMPORT_HANDLE_DEFINED
#define TRK_IMPORT_HANDLE_DEFINED
DECLARE_TRK_HANDLE(TRK_IMPORT_HANDLE);
#endif

// Define the upper limit on the size of string fields.
//
#define TRK_MAX_STRING	(255)

// *********************************************************
// Error Codes
// *********************************************************

enum _TrkError {
	TRK_SUCCESS						=  0,
	TRK_E_VERSION_MISMATCH			=  1,
	TRK_E_OUT_OF_MEMORY				=  2,
	TRK_E_BAD_HANDLE				=  3,
	TRK_E_BAD_INPUT_POINTER			=  4,
	TRK_E_BAD_INPUT_VALUE			=  5,
	TRK_E_DATA_TRUNCATED			=  6,
	TRK_E_NO_MORE_DATA				=  7,
	TRK_E_LIST_NOT_INITIALIZED		=  8,
	TRK_E_END_OF_LIST				=  9,
	TRK_E_NOT_LOGGED_IN				= 10,
	TRK_E_SERVER_NOT_PREPARED		= 11,
	TRK_E_BAD_DATABASE_VERSION		= 12,
	TRK_E_UNABLE_TO_CONNECT			= 13,
	TRK_E_UNABLE_TO_DISCONNECT		= 14,
	TRK_E_UNABLE_TO_START_TIMER		= 15,
	TRK_E_NO_DATA_SOURCES			= 16,
	TRK_E_NO_PROJECTS				= 17,
	TRK_E_WRITE_FAILED				= 18,
	TRK_E_PERMISSION_DENIED			= 19,
	TRK_E_SET_FIELD_DENIED			= 20,
	TRK_E_ITEM_NOT_FOUND			= 21,
	TRK_E_CANNOT_ACCESS_DATABASE	= 22,
	TRK_E_CANNOT_ACCESS_QUERY		= 23,
	TRK_E_CANNOT_ACCESS_INTRAY		= 24,
	TRK_E_CANNOT_OPEN_FILE			= 25,
	TRK_E_INVALID_DBMS_TYPE			= 26,
	TRK_E_INVALID_RECORD_TYPE		= 27,
	TRK_E_INVALID_FIELD				= 28,
	TRK_E_INVALID_CHOICE			= 29,
	TRK_E_INVALID_USER				= 30,
	TRK_E_INVALID_SUBMITTER			= 31,
	TRK_E_INVALID_OWNER				= 32,
	TRK_E_INVALID_DATE				= 33,
	TRK_E_INVALID_STORED_QUERY		= 34,
	TRK_E_INVALID_MODE				= 35,
	TRK_E_INVALID_MESSAGE			= 36,
	TRK_E_VALUE_OUT_OF_RANGE		= 37,
	TRK_E_WRONG_FIELD_TYPE			= 38,
	TRK_E_NO_CURRENT_RECORD			= 39,
	TRK_E_NO_CURRENT_NOTE			= 40,
	TRK_E_NO_CURRENT_ATTACHED_FILE	= 41,
	TRK_E_NO_CURRENT_ASSOCIATION	= 42,
	TRK_E_NO_RECORD_BEGIN			= 43,
	TRK_E_NO_MODULE					= 44,
	TRK_E_USER_CANCELLED			= 45,
	TRK_E_SEMAPHORE_TIMEOUT			= 46,
	TRK_E_SEMAPHORE_ERROR			= 47,
	TRK_E_INVALID_SERVER_NAME		= 48,
	TRK_E_NOT_LICENSED				= 49,
	TRK_NUMBER_OF_ERROR_CODES = TRK_E_NOT_LICENSED,
	//
	// Export/Import error codes follow:
	TRKEXP_ERROR_CODE_BASE = 10000,
	TRKEXP_E_EXPORT_WRONG_VERSION = TRKEXP_ERROR_CODE_BASE,
	TRKEXP_E_EXPORTSET_NOT_INIT		= 10001,
	TRKEXP_E_NO_EXPSET_NAME			= 10002,
	TRKEXP_E_BAD_EXPSET_NAME		= 10003,
	TRKEXP_E_EXPSET_FAIL_CREATE		= 10004,
	TRKEXP_E_IMPORTMAP_NOT_INIT		= 10005,
	TRKEXP_E_NO_IMPMAP_NAME			= 10006,
	TRKEXP_E_BAD_IMPMAP_NAME		= 10007,
	TRKEXP_E_IMPMAP_FAIL_CREATE		= 10008,
	TRKEXP_E_IMP_VALIDATE_FAIL		= 10009,
	TRKEXP_E_USER_NOEXIST			= 10010,
	TRKEXP_E_USER_ADD				= 10011,
	TRKEXP_E_IMPORT_NOT_INIT		= 10012,
	TRKEXP_E_BAD_EMBEDDED_QUOTE_ARG	= 10013,
	TRKEXP_E_BAD_DATEFORMAT_ARG		= 10014,
	TRKEXP_E_BAD_TIMEFORMAT_ARG		= 10015,
	TRKEXP_E_BAD_CHOICE_OPTION_ARG	= 10016,
	TRKEXP_E_BAD_USER_OPTION_ARG	= 10017,
	TRKEXP_E_BAD_NUMBER_OPTION_ARG	= 10018,
	TRKEXP_E_BAD_DATE_OPTION_ARG	= 10019,
	TRKEXP_E_ALL_NOTES_SELECTED		= 10020,
	TRKEXP_E_READ_EXPORTHDR			= 10021,
	TRKEXP_E_WRITE_EXPORTHDR		= 10022,
	TRKEXP_E_READ_RECORDHDR			= 10023,
	TRKEXP_E_WRITE_RECORDHDR		= 10024,
	TRKEXP_E_WRITE_FIELD			= 10025,
	TRKEXP_E_OPEN_FILE				= 10026,
	TRKEXP_E_READ_FIELD				= 10027,
	TRKEXP_E_READ_FIELD_WRONG_TYPE	= 10028,
	TRKEXP_E_BAD_ITEM_TYPE			= 10029,
	TRKEXP_E_READ_FROM_DB			= 10030,
	TRKEXP_E_WRITE_TO_DB			= 10031,
	TRKEXP_E_BAD_DATE				= 10032,
	TRKEXP_E_BAD_CHOICE				= 10033,
	TRKEXP_E_BAD_NUMBER				= 10034,
	TRKEXP_E_OPEN_ERRORLOG			= 10035,
	TRKEXP_E_BAD_ERRORLOG_PATH		= 10036,
	TRKEXP_E_LOGGING_ERROR			= 10037,
	TRKEXP_E_IMPORT_PERMISSION		= 10038,
	TRKEXP_E_EXPORT_PERMISSION		= 10039,
	TRKEXP_E_NEW_USER_PERMISSION	= 10040,
	TRKEXP_E_CLOSE_ERRORLOG			= 10041,
	TRKEXP_E_NEWCHOICE_SYSFLD		= 10042,
	TRKEXP_E_EXTRA_FIELDS			= 10043,
	TRKEXP_E_USER_ALREADY_IN_GROUP	= 10044,
	TRKEXP_NUMBER_OF_ERROR_CODES = TRKEXP_E_EXTRA_FIELDS,
	//
	// Internal error codes follow:
	// (Clients of the DLL should never see these.)
	TRK_INTERNAL_ERROR_CODE_BASE = 20000,
	TRK_E_INTERNAL_ERROR = TRK_INTERNAL_ERROR_CODE_BASE };

// *********************************************************
// Tracker Toolkit API prototypes
// *********************************************************

#ifndef TRK_DEBUG
#ifdef __cplusplus
extern "C" {
#endif
#endif

// TrkHandleAlloc must be called before all other Tracker API
// functions.  TrkHandleFree closes files and releases all
// associated memory.  Pass the defined constant TRK_VERSION_ID
// for the version ID.

TRKAPI TrkHandleAlloc(
	TRK_VERSION_ID_TYPE			trkVersionID,			// Input
	TRK_HANDLE FAR*				pTrkHandle);			// Output

TRKAPI TrkHandleFree(
	TRK_HANDLE FAR*				pTrkHandle);			// Input/Output

// *********************************************************

// TrkProjectLogin requires a valid trkHandle, obtained using
// TrkHandleAlloc.  DBMSLoginMode should be set to one of the three
// values listed below.  All other arguments may optionally be NULL,
// indicating that the value should be read from the current .INI
// file (see also TrkSetIniFile).  Updated values will be written
// to the current .INI file upon successful login.
//
// Successful login is prerequisite to all Tracker API functions
// except where noted otherwise.

enum _TrkDBMSLoginMode {
	TRK_USE_INI_FILE_DBMS_LOGIN		= 0,
	TRK_USE_SPECIFIED_DBMS_LOGIN	= 1,
	TRK_USE_DEFAULT_DBMS_LOGIN		= 2 };

TRKAPI TrkProjectLogin(
	TRK_HANDLE					trkHandle,				// Input
	TRK_CSTR					userName,				// Input (see above)
	TRK_CSTR					password,				// Input (see above)
	TRK_CSTR					projectName,			// Input (see above)
	TRK_CSTR					DBMSType,				// Input (see above)
	TRK_CSTR					DBMSName,				// Input (see above)
	TRK_CSTR					DBMSUserName,			// Input (see above)
	TRK_CSTR					DBMSPassword,			// Input (see above)
	TRK_DBMS_LOGIN_MODE			DBMSLoginMode);			// Input (see above)

TRKAPI TrkProjectLogout(
	TRK_HANDLE					trkHandle);				// Input

// *********************************************************

// A default .INI file will be used if not otherwise specified.
//
// Either of these two functions may be called before login.

TRKAPI TrkSetIniFile(
	TRK_HANDLE					trkHandle,				// Input
	TRK_CSTR					filename);				// Input

TRKAPI TrkGetIniFile(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						filename);				// Output

// *********************************************************

// Provide a general mechanism for storing (ID,value) pairs.
// Attributes with ID values of less than 1000 are used by
// Tracker.  Attributes with ID values of 1000 and greater
// may be set and retrieved by clients for any purpose.
//
// Either of these two functions may be called before login.

enum _TrkAttributeId {
	TRK_TRKTOOL_ATTRIBUTE_ID_BASE = 0,
	TRK_CANCEL_INTRAY			= 1,
	TRK_CANCEL_QUERY			= 2,
	TRK_CANCEL_IMPORT			= 3,
	TRK_NO_KEEP_ALIVE			= 4,
	TRK_NO_TIMER				= 5,
	TRK_NO_RECORD_CACHE			= 6,
	TRK_CONCURRENT_DB_TIMEOUT	= 7,
	//
	// (Clients of the DLL are free to use values at or
	// above this threshhold.)
	TRK_USER_ATTRIBUTE_ID_BASE = 1000 };

TRKAPI TrkSetNumericAttribute(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					attributeId,			// Input
	TRK_UINT					value);					// Input

TRKAPI TrkGetNumericAttribute(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					attributeId,			// Input
	TRK_UINT FAR*				pValue);				// Output

// *********************************************************

// Provide an enumeration of all Projects in the current DB.
// TrkInitProjectList initializes an in-memory list of
// project names, which are accessed sequentially using
// TrkGetNextProject.
//
// Example:
//		...
//		rc = TrkInitProjectList(h, NULL, NULL, NULL, NULL);
//		while (TrkGetNextProject(h, sizeof(buf), buf) == TRK_SUCCESS)