trktool.h

hl2 source code. Do not use it illegal.

//			...
//
// These two functions may be called before login.  However, the
// interpretation of the arguments differs depending on which mode
// of operation is used:
//
// If called before login, TrkInitProjectList reads all of its
// input arguments, where they will be interpreted exactly as in
// TrkProjectLogin.  This mode of operation may be useful, for
// example, in preparing a login dialog.
//
// If called after a successful login, the values for all
// arguments, other than trkHandle, are ignored.

TRKAPI TrkInitProjectList(
	TRK_HANDLE					trkHandle,				// Input
	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 TrkGetNextProject(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						projectName);			// Output

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

// Provide an enumeration of all DBMS Types known to Tracker.
//
// May be called before login.

TRKAPI TrkInitDBMSTypeList(
	TRK_HANDLE					trkHandle);				// Input

TRKAPI TrkGetNextDBMSType(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						DBMSType);				// Output

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

// Provide access to current login information

TRKAPI TrkGetLoginUserName(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						userName);				// Output

TRKAPI TrkGetLoginProjectName(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						projectName);			// Output

TRKAPI TrkGetLoginDBMSType(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						DBMSType);				// Output

TRKAPI TrkGetLoginDBMSName(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						DBMSName);				// Output

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

// Provide an enumeration of all Record Types (SCR, Time)
// defined for the current project.

TRKAPI TrkInitRecordTypeList(
	TRK_HANDLE					trkHandle);				// Input

TRKAPI TrkGetNextRecordType(
	TRK_HANDLE					trkHandle,				// Input
	TRK_RECORD_TYPE FAR*		pRecordType);			// Output

TRKAPI TrkGetRecordTypeName(
	TRK_HANDLE					trkHandle,				// Input
	TRK_RECORD_TYPE				recordType,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						recordTypeName);		// Output

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

// Provide an enumeration of all Fields defined in the
// current project.

enum _TrkFieldType {
	TRK_FIELD_TYPE_NONE			= 0,
	TRK_FIELD_TYPE_CHOICE		= 1,
	TRK_FIELD_TYPE_STRING		= 2,
	TRK_FIELD_TYPE_NUMBER		= 3,
	TRK_FIELD_TYPE_DATE			= 4,
	TRK_FIELD_TYPE_SUBMITTER	= 5,
	TRK_FIELD_TYPE_OWNER		= 6,
	TRK_FIELD_TYPE_USER			= 7,
	TRK_FIELD_TYPE_ELAPSED_TIME = 8 };

TRKAPI TrkInitFieldList(
	TRK_HANDLE					trkHandle,				// Input
	TRK_RECORD_TYPE				recordType);			// Input

TRKAPI TrkGetNextField(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						fieldName,				// Output
	TRK_FIELD_TYPE FAR*			pFieldType);			// Output (optional)

// Provide general information about Fields.

TRKAPI TrkGetFieldType(
	TRK_HANDLE					trkHandle,				// Input
	TRK_CSTR					fieldName,				// Input
	TRK_RECORD_TYPE				recordType,				// Input
	TRK_FIELD_TYPE FAR*			pFieldType);			// Output

TRKAPI TrkGetFieldMaxDataLength(
	TRK_HANDLE					trkHandle,				// Input
	TRK_CSTR					fieldName,				// Input
	TRK_RECORD_TYPE				recordType,				// Input
	TRK_UINT FAR*				pMaxDataLength);		// Output

TRKAPI TrkGetFieldDefaultStringValue(
	TRK_HANDLE					trkHandle,				// Input
	TRK_CSTR					fieldName,				// Input
	TRK_RECORD_TYPE				recordType,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						defaultValue);			// Output

TRKAPI TrkGetFieldDefaultNumericValue(
	TRK_HANDLE					trkHandle,				// Input
	TRK_CSTR					fieldName,				// Input
	TRK_RECORD_TYPE				recordType,				// Input
	TRK_UINT FAR*				pDefaultValue);			// Output

TRKAPI TrkGetFieldRange(
	TRK_HANDLE					trkHandle,				// Input
	TRK_CSTR					fieldName,				// Input
	TRK_RECORD_TYPE				recordType,				// Input
	TRK_UINT FAR*				pMinValue,				// Output
	TRK_UINT FAR*				pMaxValue);				// Output

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

// Provide an enumeration of all stored Queries defined in the
// current project.

TRKAPI TrkInitQueryNameList(
	TRK_HANDLE					trkHandle);				// Input

TRKAPI TrkGetNextQueryName(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						queryName,				// Output
	TRK_RECORD_TYPE FAR*		pRecordType);			// Output (optional)

TRKAPI TrkGetQueryRecordType(
	TRK_HANDLE					trkHandle,				// Input
	TRK_CSTR					queryName,				// Input
	TRK_RECORD_TYPE FAR*		pRecordType);			// Output

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

// Provide an enumeration of all Users defined in the
// current project.

TRKAPI TrkInitUserList(
	TRK_HANDLE					trkHandle);				// Input

TRKAPI TrkGetNextUser(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						userName);				// Output

// Provide general information about Users.

TRKAPI TrkGetUserFullName(
	TRK_HANDLE					trkHandle,				// Input
	TRK_CSTR					userName,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						fullName);				// Output

TRKAPI TrkGetUserEmail(
	TRK_HANDLE					trkHandle,				// Input
	TRK_CSTR					userName,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						emailAddress);			// Output

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

// Provide an enumeration of all values for the specified
// Choice Field.

TRKAPI TrkInitChoiceList(
	TRK_HANDLE					trkHandle,				// Input
	TRK_CSTR					fieldName,				// Input
	TRK_RECORD_TYPE				recordType);			// Input

TRKAPI TrkGetNextChoice(
	TRK_HANDLE					trkHandle,				// Input
	TRK_UINT					bufferSize,				// Input
	TRK_STR						choiceName);			// Output

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

// Provide a Transaction ID representing the most recent
// change to the current project.
//
// A Transaction ID represents the exact date and time when
// a change is made in a DB.  TrkGetProjectTransactionID
// provides a Transaction ID which represents the most
// recent update to any record of the specified type in
// the DB.  Note that separate Transaction ID domains exist
// for each record type.

TRKAPI TrkGetProjectTransactionID(
	TRK_HANDLE					trkHandle,				// Input
	TRK_RECORD_TYPE				recordType,				// Input
	TRK_TRANSACTION_ID FAR*		pTransactionID);		// Output

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

// Tracker Record Handles are used in place of Tracker API
// Handles in those functions below which operate on Record
// data.  TrkRecordHandleAlloc must be called first to create
// a record handle.  TrkRecordHandleFree releases all memory
// associated with that handle.
//
// If desired, multiple Record Handles may be used concurrently.

TRKAPI TrkRecordHandleAlloc(
	TRK_HANDLE					trkHandle,				// Input
	TRK_RECORD_HANDLE FAR*		pTrkRecordHandle);		// Output

TRKAPI TrkRecordHandleFree(
	TRK_RECORD_HANDLE FAR*		pTrkRecordHandle);		// Input/Output

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

// Provide access to sets of records from the DB.  Two functions
// TrkQueryInitRecordList and TrkInTrayInitRecordList create
// in-memory sets of records, which are accessed sequentially
// using TrkGetNextRecord.  TrkGetNextRecord can be thought of
// as making a record 'current' in that subsequent calls to the
// various record access functions will operate on data for that
// particular record.
//
// TrkQueryInitRecordList and TrkInTrayInitRecordList each take
// an optional input Transaction ID.  If provided, only records
// which were modified after the time of the specified
// Transaction ID will be included in the output set.  In
// addition, a Transaction ID is returned, which represents the
// time of the most recent update to the DB.

TRKAPI TrkQueryInitRecordList(
	TRK_RECORD_HANDLE			trkRecordHandle,		// Input
	TRK_CSTR					queryName,				// Input
	TRK_TRANSACTION_ID			transactionID,			// Input (optional)
	TRK_TRANSACTION_ID FAR*		pNewTransactionID);		// Output (optional)

TRKAPI TrkInTrayInitRecordList(
	TRK_RECORD_HANDLE			trkRecordHandle,		// Input
	TRK_RECORD_TYPE				recordType,				// (currently unused)
	TRK_TRANSACTION_ID			transactionID,			// Input (optional)
	TRK_TRANSACTION_ID FAR*		pNewTransactionID);		// Output (optional)

TRKAPI TrkGetNextRecord(
	TRK_RECORD_HANDLE			trkRecordHandle);		// Input

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

// TrkQueryGetSingleRecord provides access to an individual
// Record given its ID number and Type.  The record will be
// made 'current' in the same sense as TrkGetNextRecord.

TRKAPI TrkGetSingleRecord(
	TRK_RECORD_HANDLE			trkRecordHandle,		// Input
	TRK_UINT					recordId,				// Input
	TRK_RECORD_TYPE				recordType);			// Input

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

// Submit a new record to the DB.  TrkNewRecordBegin should
// be called first to clear the current in-memory record,
// i.e. to set all data to their default values.
//
// After all fields, etc. have been set to their desired
// values, TrkNewRecordCommit is called to actually add the
// record to the DB.  The transaction may be cancelled any
// time before the commit with TrkRecordCancelTransaction.

TRKAPI TrkNewRecordBegin(
	TRK_RECORD_HANDLE			trkRecordHandle,		// Input
	TRK_RECORD_TYPE				recordType);			// Input

TRKAPI TrkNewRecordCommit(
	TRK_RECORD_HANDLE			trkRecordHandle,		// Input
	TRK_TRANSACTION_ID FAR*		pNewTransactionID);		// Output

TRKAPI TrkRecordCancelTransaction(
	TRK_RECORD_HANDLE			trkRecordHandle);		// Input

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

// Update a record in the DB.  TrkUpdateRecordBegin populates
// all fields of the current Record with data from the DB.
// TrkUpdateRecordBegin also locks the record in the DB to
// prevent concurrent access.
//
// After the desired changes to fields, etc. have been made,
// TrkUpdateRecordCommit is called to update the record in the
// DB.  The transaction may be cancelled any time before the
// commit with TrkRecordCancelTransaction.

TRKAPI TrkUpdateRecordBegin(
	TRK_RECORD_HANDLE			trkRecordHandle);		// Input

TRKAPI TrkUpdateRecordCommit(
	TRK_RECORD_HANDLE			trkRecordHandle,		// Input
	TRK_TRANSACTION_ID FAR*		pNewTransactionID);		// Output

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

// Remove a record from the DB.

TRKAPI TrkDeleteRecord(
	TRK_RECORD_HANDLE			trkRecordHandle);		// Input

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

// Provide miscellaneous information on the current Record.

TRKAPI TrkGetRecordTransactionID(
	TRK_RECORD_HANDLE			trkRecordHandle,		// Input
	TRK_TRANSACTION_ID FAR*		pSubmitTransactionID,	// Output (optional)
	TRK_TRANSACTION_ID FAR*		pUpdateTransactionID);	// Output (optional)

TRKAPI TrkGetRecordRecordType(
	TRK_RECORD_HANDLE			trkRecordHandle,		// Input
	TRK_RECORD_TYPE FAR*		pRecordType);			// Output

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

// Get or set data fields in a record.
//
// "Set" functions only modify the in-memory copy of the data.

TRKAPI TrkGetNumericFieldValue(
	TRK_RECORD_HANDLE			trkRecordHandle,		// Input