TRIPsystem Kernel API 8.4
Loading...
Searching...
No Matches
Session Commands

Manipulation of session state. More...

Functions

int TdbApiKeyInfo (const char *keyname, int mode, char *outstr, size_t outstrsz, int *outint)
 Get information about a named API key.
 
int TdbApiLogCheckpoint (int id)
 Sets an API log checkpoint position.
 
int TdbApiLogEnable (boolean enable)
 Enables or disables API logging for the current session.
 
int TdbApiLogRead (int checkpoint_id, long *position, char *buffer, size_t bufsize, size_t *readcount)
 Read data from the API log.
 
int TdbApiLogSetVerbosity (int level)
 Set verbosity level for the API log.
 
int TdbChangeUser (const char *user, const char *password, int mode)
 Change the currently logged on user, or temporarily logs out the current user.
 
int TdbCheckApiKey (const char *apikey)
 Check if an API key is valid.
 
int TdbCheckDate (int dateform, char *datestring, int *dateint)
 Checks that a supplied date is valid and transforms date strings to integers and vice versa.
 
int TdbCheckUser (const char *user, const char *password, char *FM, char *UM, char *SM)
 Perform a login operation to the TRIPkernel by validating both username and password.
 
int TdbCreateApiKey (const char *keyname, const char *comment, boolean replace, char **keybuf, int *keybuf_size)
 Create an API key for use with the token functions.
 
int TdbCreateTicket (char *ticket, int maxlen)
 Create a login ticket for the currently logged in user.
 
int TdbCreateTokenPair (const char *apikey, const char *user, const char *tag, char **access_token, int *access_token_length, char **refresh_token, int *refresh_token_length, time_t *access_expires_at, time_t *refresh_expires_at)
 Create an access/refresh token pair for the specified or currently logged on user.
 
int TdbDeleteTicket (const char *ticket)
 Delete login ticket(s) for the currently logged in user,.
 
int TdbEnumApiKeys (void **handle, char *keyname, size_t keyname_size, char *comment, size_t comment_size, char *creator, size_t creator_size, char *credate, size_t credate_size, char *cretime, size_t cretime_size)
 Enumerate available API keys.
 
int TdbEnumTokens (void **handle, char *user, size_t user_size, char *tag, size_t tag_size, time_t *created, time_t *access_expires_at, time_t *refresh_expires_at)
 Enumerate access/refresh token pairs for all users.
 
int TdbEnumUserTokens (const char *username, void **handle, char *tag, size_t tag_size, time_t *created, time_t *access_expires_at, time_t *refresh_expires_at)
 Enumerate access/refresh token pairs for a user.
 
int TdbGetConf (const char *symbolName, int section, char *valueBuffer, size_t bufferSize, const char *defaultValue)
 Get a configuration symbol value.
 
int TdbIsSuperUser (void)
 Check if current user has SUPERMAN privileges.
 
int TdbMessage (int messageNumber, char *message, int *length)
 Retrieve the text of a TRIP message indicated by number, or display a message.
 
int TdbPurgeTokens (int mode, time_t from_timestamp, time_t to_timestamp, int *purgedcount, FP_TdbPurgeTokensCallback callback, void *userdata)
 Purge expired access/refresh token pairs.
 
int TdbPurgeUserTokens (int mode, const char *username, time_t from_fimestamp, time_t to_timestamp, int *purgedcount, FP_TdbPurgeTokensCallback callback, void *userdata)
 Purge expired access/refresh token pairs for a user.
 
int TdbRefreshTokenPair (const char *apikey, const char *current_refresh_token, char **access_token, int *access_token_length, char **refresh_token, int *refresh_token_length, time_t *access_expires_at, time_t *refresh_expires_at, char *username, size_t username_size)
 Create an access/refresh token pair using a refresh token.
 
int TdbResolvePath (const char *symbolPath, char *resolved, size_t bufsize)
 
int TdbRetCode (void)
 Return the TRIP message number.
 
int TdbRevokeApiKey (const char *keyname)
 Revoke an API key.
 
int TdbRevokeTokens (const char *username, const char *token, const char *tag, int *revokecount, FP_TdbPurgeTokensCallback callback, void *userdata)
 Revoke a specific token or all tokens for a particular user.
 
int TdbSetConf (const char *symbolName, const char *symbolValue)
 
int TdbSetUICharset (int charset)
 Change the session character set.
 
int TdbShellDefDateform (int dateform, char *datestring)
 Get or set a TRIP date format.
 
int TdbShellModifyCcl (int language)
 Modify the CCL locale language being used.
 
int TdbShellType (char *fieldtypeName, int *fieldtypeNumber)
 Check a field type on its name or number.
 
int TdbStartTrip (char *username, char *password, int language, int mode)
 Initializes the client application for a new TRIP session.
 
int TdbStopTrip (boolean restart)
 Terminates a TRIP session started with TdbStartTrip.
 

Detailed Description

Manipulation of session state.

The session commands is a group of TRIP functions that operate on the session level. These are used to establish and tear down sessions and query and modify session-related information.

Function Documentation

◆ TdbApiKeyInfo()

int TdbApiKeyInfo ( const char *  keyname,
int  mode,
char *  outstr,
size_t  outstrsz,
int *  outint 
)

Get information about a named API key.

Parameters
keynameName of the API key to get information on
modeThe type of information to retrieve as a APIKEYINFO_* value
outstrBuffer to receive a string output (depends on mode)
outstrszThe allocated size of the outstr buffer
outintBuffer to receive an int output (depends on mode)
Returns
1 or other odd value on success, even value on error

Description

This function retrieves information on an existing API key.

The mode parameter can have the following values:

Symbolic Name Output Parameter Purpose
APIKEYINFO_COMMENT outstr The outstr parameter receives the comment assigned to the API key
APIKEYINFO_OWNER outstr The outstr parameter receives the name of the TRIP user that created the key
APIKEYINFO_CREATED outstr The outstr parameter receives the date and time for when the key was created
APIKEYINFO_CREATED_DATE outstr The outstr parameter receives the date at which the key was created
APIKEYINFO_CREATED_TIME outstr The outstr parameter receives the tme at which the key was created

If the funciton is passed a mode value of 0 (zero), it will act as an existence check only and not return any values in either the outstr or outint parameters. In this case, a successful return code indicates that the key exists.

Return Codes

This function returns 1 on success, 0 if there are no more tokens, and an even value on failure.

See also
TdbCreateApiKey()
TdbRevokeApiKey()
TdbCreateTokenPair()
TdbRefreshTokenPair()
TdbRevokeTokens()

◆ TdbApiLogCheckpoint()

int TdbApiLogCheckpoint ( int  id)

Sets an API log checkpoint position.

Parameters
idID of checkpoint to set; valid ID numbers are 1 to 8.

Description

API log checkpoints are used to set a position from which calls to the TdbApiLogRead() function will start to read the log. Use this behavior when you wish to get the API log for a specific part of your application only.

Return Codes

On success, this function returns a success value of 1, and on failure it returns 0 (zero).

See also
TdbApiLogEnable()
TdbApiLogRead()

◆ TdbApiLogEnable()

int TdbApiLogEnable ( boolean  enable)

Enables or disables API logging for the current session.

Parameters
enableTrue to enable and false to disable

Description

API logging can be useful to analyze the behavior of applications in situations where hard-to-locate errors occur.

API logs enabled this way are automatically removed when the process exits and do not show in the file system. If this log data should be retained, either call the TdbApiLogRead() function to read the log from your application, or define the TDBS_APILOG_RETAIN variable in tdbs.conf or the environment before you start the TRIP process.

Return Codes

On success, this function returns a success value of 1, and on failure it returns 0 (zero).

See also
TdbApiLogCheckpoint()
TdbApiLogRead()

◆ TdbApiLogRead()

int TdbApiLogRead ( int  checkpoint_id,
long *  position,
char *  buffer,
size_t  bufsize,
size_t *  readcount 
)

Read data from the API log.

Parameters
idID of checkpoint to read from
position[IN/OUT] Pointer to long int to hold read position; set to zero for first call.
buffer[OUT] Pointer to memory buffer to receieve API log data.
bufsize[IN] The size of the memory area that the buffer parameter points to.
readcount[OUT] Receieves the number of bytes copied to the buffer

Description

The API log is, if enabled via the TdbApiLogEnable() function, by default not visible in the file system. In order to read data from it, the application should call this function.

This function reads the API log from a position associated with a checkpoint, set by calling the TdbApiLogCheckpoint() function. A special checkpoint with value 0 (zero) can also be used in order to read data from the start of the log.

Return Codes

On success, this function returns a success value of 1, and on failure it returns 0 (zero).

◆ TdbApiLogSetVerbosity()

int TdbApiLogSetVerbosity ( int  level)

Set verbosity level for the API log.

Parameters
levelVerbosity level to set

Description

The API log verbosity can be set by calling this method. Verbosity levels control what API functions are included the log. The default level is used for most API calls, and while labeled minimal, it is sufficient for most needs. Functions whose impact on the log size is significant and/or whose inclusion are rarely required are emitted at higher verbosity levels.

levels are:

| Value | Description | | -—_ | --------— | | 0 | Minimal verbosity (default) | | 1 | Low verbosity | | 2 | Average verbosity | | 3 | High verbosity | | 4 | Max verbosity |

Return Codes

On success, this function returns a success value of 1, and on failure it returns 0 (zero).

◆ TdbChangeUser()

int TdbChangeUser ( const char *  user,
const char *  password,
int  mode 
)

Change the currently logged on user, or temporarily logs out the current user.

Parameters
userName of new user to log on as
passwordThe password for the TRIP user
modeBitmask controlling how existing session state is to be handled
Returns
1 or other odd value on success, even value on error

Description

This function is used to switch the current session from one user to another. The mode parameter controls how to handle the current session state; to clear it or to keep it. See the table below for details.

If the username and password are both specified as empty strings, the current user will be logged off. The session will then be left in an intermediary state in which the only valid operation is a call to TdbChangeUser() to log in a new user into the session, or to call TdbStopTrip() to terminate the session altogether.

If the username is empty and the password is specified as a valid login ticket, the ticket owner will be assigned the current user of the session.

The mode parameter can have the following values:

Symbol Description
CHANGEUSER_KEEPALL All state is kept. Cannot be combined with any other value.
CHANGEUSER_CLEAR_SETS Delete all search sets. This also removes all held PRINT jobs.
CHANGEUSER_CLOSE_DATABASES Close all databases.
CHANGEUSER_RESTORE_DEFAULTS Restore DEFINEs to their default values.
CHANGEUSER_CLEARALL Combines CHANGEUSER_CLEAR_SETS, CHANGEUSER_CLOSE_DATABASES and CHANGEUSER_RESTORE_DEFAULTS.

The TdbSessionInfo() function can be used to query the current state of the session. Use the SESSIONINFO_SESSION_STATUS mode parameter. If the integer output parameter contains 4 or 5, the current user has been temporarily logged out.

Since

This function was introduced in TRIP version 8.0-0.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
322 Cannot open *.SIF, disk quota exceeded or no write access.
9634 No such user as 2
9666 User id 2 is a group id.
10306 Invalid password - Please try again.
See also
TdbStartTrip()
TdbStopTrip()
TdbSessionInfo()

◆ TdbCheckApiKey()

int TdbCheckApiKey ( const char *  apikey)

Check if an API key is valid.

Parameters
apikeyThe API key to check for validity
Returns
1 or other odd value on success, or an even value on error

◆ TdbCheckDate()

int TdbCheckDate ( int  dateform,
char *  datestring,
int *  dateint 
)

Checks that a supplied date is valid and transforms date strings to integers and vice versa.

Parameters
dateformDate format
datestringDate string
dateintDatee numeric value.
Returns
1 or other odd value on success, even value on error

Description

The TdbCheckDate() function performs a number of operations upon TRIP dates depending on the value of the parameters passed to it.

If the dateform parameter value is positive (between 1 and 17), the datestring parameter is not an empty string, and the dateint parameter is 0 (zero), this function will check that the datestring parameter value is valid in that format.

If the dateform parameter value is positive (between 1 and 17), the datestring parameter is an empty string and the dateint parameter is not 0 (zero), this function transforms the value of the dateint parameter from a long representation of a date to a string form in the specified dateform.

The change to the date format lasts only for the duration of the current call to the TdbCheckDate() function. However, if the value of the dateform parameter is negative, the function performs all actions described above but will also alter the date format until the calling application terminates.

Parameter Values

The dateform parameter is passed an int value for the dateform that is to be checked or set. Valid values are:

Value Date format Example for May 1st 1988
1 YYYY-MM-DD 1988-05-01
2 YYYY-mM-dD 1988-5-1
3 yyYY-mM-dD 88-5-1
4 YYYY-mm-dD 1988-May-1
5 yyYY-mm-dD 88-May-1
6 MM-DD-YYYY 05-01-1988
7 mM-dD-YYYY 5-1-1988
8 mM-dD-yyYY 5-1-88
9 mm-dD-YYYY May-1-1988
10 mm-dD-yyYY May-1-88
11 DD-MM-YYYY 01-05-1988
12 dD-mM-YYYY 1-5-1988
13 dD-mM-yyYY 1-5-88
14 dD-mm-YYYY 1-May-1988
15 dD-mm-yyYY 1-May-88
16 YYYYMMDD 19880501
17 yyYYMMDD 880501

The datestring parameter is passed a character string as the date in string form. Whether this date string is to checked or set depends upon the value passed in the dateint parameter.

The dateint parameter is passed an integer representation of the date. As with the parameter whether this value is checked or set depends upon the dateform parameter.

Return Codes

On success, this function returns a success value of 1, and on failure it returns 0 (zero).

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 The date transformation failed.

Examples

Format a specified date according in the current date format:

char formattedDate[64] = "";
int year = 2004;
int month = 9;
int day = 29;
// Create an integer representation of the date.
int ymd = year << 9;
ymd += month << 5;
ymd += day;
// Convert to string and display.
TdbCheckDate(0,formattedDate,&ymd);
printf("%s\n",formattedDate);
int TdbCheckDate(int dateform, char *datestring, int *dateint)
Checks that a supplied date is valid and transforms date strings to integers and vice versa.

Check if a specified string is a valid date in the current date format:

int ymd = 0;
char dateString[64] = "2004-09-29";
// Check if the date string is a valid date.
if (IsError(TdbCheckDate(1,dateString,&ymd))
printf("String not recognized as a date in the current date format.\n");
else
printf("Date is ok. Integer representation of the date is %d\n",ymd);

◆ TdbCheckUser()

int TdbCheckUser ( const char *  user,
const char *  password,
char *  FM,
char *  UM,
char *  SM 
)

Perform a login operation to the TRIPkernel by validating both username and password.

Parameters
userName of user. Recieves the normalized user name on return.
passwordPassword
FMReceieves file manager privilege
UMReceieves user manager privilege
SMReceieves system manager privilege
Returns
1 or other odd value on success, even value on error

Description

The function TdbCheckUser() must be called to gain access to TRIP. All logins are validated upon the contents of the username and password parameters.

Note
A call to this function is now included in the TdbStartTrip() function except when TdbStartTrip() is called with an empty string as username and as password. In this case the application must call TdbCheckUser() afterwards.

If the user's profile record has the os_entry flag set then the password can be ignored if the operating system username is the same as the TRIP username. When the two usernames are the same the string in the password parameter can be left blank or set to a random value. Note that this only applies for the server-side version of this function.

Before calling TdbCheckUser() the calling process must have called the function TdbBeginTdbs() to initialize the TRIP kernel. Until a successful call of TdbCheckUser() the security subsystem will not allow any access to database functions.

This function can only be successfully invoked once per TRIP session; it can, however, be invoked any number of times unsuccessfully prior to that successful invocation.

On successful return, the three boolean flags FM , UM , and SM reflect the file, user and system management status of the calling process. These flags are returned in the parameters with the same names.

The SIF file for the current TRIP application session is created upon successful checking of the CONTROL file for the user/password combination.

Parameter Values

The user parameter is passed a character string as the name of the user being checked. Upon return from TdbCheckUser() the normalized form of the user name is returned in this parameter.

The password is passed a character string as the password for the user being checked.

The FM parameter is passed a char as a flag indicating whether the named user has FM rights. If the lowest bit of the char is set upon return the user has file manager privileges and the calling process may perform file management functions such as creating databases, clusters and thesauri, as well as granting existing users and groups access to those objects.

The UM parameter is passed a char as a flag indicating whether the named user has UM rights. If the lowest bit of the char is set upon return the user has user manager privileges and the calling process can perform user management functions such as creation and deletion of users, groups, and group-wide procedures.

The SM parameter is passed a char as a flag indicating whether the named user has SM rights. If the lowest bit of the char is set upon return the user is acting as the system manager, user SYSTEM and the calling process can perform system management functions such as changing other user's passwords, and transferring ownership of objects from other managers to itself.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
322 Cannot open *.SIF, disk quota exceeded or no write access.
2434 Restart file 1 not found.
2466 Password invalid for restart file.
9634 No such user as 2
9666 User id 2 is a group id.
10306 Invalid password - Please try again.
18594 Old version of restart file (SIF, PRT, RIF), aborting...
21602 Existing restart file belongs to another user - try again.
See also
TdbCreateUser()
TdbChangePassword()
TdbSetPassword()
TdbStartTrip()
TdbBeginTdbs()

◆ TdbCreateApiKey()

int TdbCreateApiKey ( const char *  keyname,
const char *  comment,
boolean  replace,
char **  keybuf,
int *  keybuf_size 
)

Create an API key for use with the token functions.

Parameters
keynameThe name of the API key to create (max 128 bytes)
commentA brief description of the API key
replaceTrue to replace an existing key with the same name
keybufReceives pointer to buffer containing the created API key
keybuf_sizeReceives the length of the data returned in 'keybuf'
Returns
1 or other odd value on success, even value on error

Descrition

A valid API key may be needed in order to create or refresh a token pair, as well as to log in using an access token. This requirement may be controlled using the tdbs.conf variable TDBS_REQUIRE_APIKEY (refer to the TRIPsystem Environment reference manual for details).

The returned key must be kept safe by the calling application. If this key is compromised, for whatever reason, it must be destroyed and a new one created in its stead.

Return Codes

This function returns 1 on success, 0 if there are no more tokens, and an even value on failure.

See also
TdbRevokeApiKey()
TdbApiKeyInfo()
TdbCreateTokenPair()
TdbRefreshTokenPair()
TdbRevokeTokens()

◆ TdbCreateTicket()

int TdbCreateTicket ( char *  ticket,
int  maxlen 
)

Create a login ticket for the currently logged in user.

Parameters
ticketBuffer to receive the login ticket
maxlenAllocated size of buffer (should be at least 64 bytes)
Returns
1 or other odd value on success, even value on error

Description

A login ticket is a temporary access token that can be used to authenticate as the user that created the ticket. Logging in using a login ticket is done using the normal APIs for login, save for that the ticket is passed as the password and the username as an empty string.

The login ticket is valid for the duration specified by the TDBS_TICKET_TIMEOUT logical name in the tdbs.conf configuration file, or until the TRIP daemon (tripd) is restarted. The ticket can also be revoked by calling TdbDeleteTicket() as the user to which the ticket applies, or as SYSTEM.

Note
Login tickets, if used, must be stored in a secure manner by the application.
Login tickets are not persistently stored. They will automatically be revoked if TRIPsystem is restarted. Use token pairs instead if you need your tokens to survive system restarts.
See also
TdbDeleteTicket()
TdbCreateTokenPair()

◆ TdbCreateTokenPair()

int TdbCreateTokenPair ( const char *  apikey,
const char *  user,
const char *  tag,
char **  access_token,
int *  access_token_length,
char **  refresh_token,
int *  refresh_token_length,
time_t *  access_expires_at,
time_t *  refresh_expires_at 
)

Create an access/refresh token pair for the specified or currently logged on user.

Parameters
apikeyA valid API key, or NULL / empty string if an API key is not required for token creation
userName of user to create token for, or NULL/empty for the current user
tagID / purpose for the token pair
access_tokenRecieves pointer to the new access token
access_token_lengthRecieves the length of the access token
refresh_tokenRecieves pointer to the new refresh token
refresh_token_lengthRecieves the length of the refresh token
access_expires_atReceives the access token expiration timestamp
refresh_expires_atReceives the refresh token expiration timestamp
Returns
1 or other odd value on success, even value on error

Description

This function creates a new access/refresh token pair for a named user or the the currently logged on user. If the named user is other than the current user, the logged on user must be its user mangager (UM) or SYSTEM with SUPERMAN privileges.

The access token can be used to authenticate as the user for whom the token was created. Logging in using this access token is done using the normal APIs for login, save for that the token is passed as the password and the username as an empty string.

The refresh token can be used to refresh the token pair, extending the validity of use. See TdbRefreshTokenPair() for more information.

The tag parameter must, if provided, be unique for the user for which the token pair is to be created. Refreshing a token (using the TdbRefreshToken() function) retains the tag value.

The pointers returned in access_token and refresh_token must be deallocated by call to the TdbDeallocate() function.

Return Codes

This function returns an odd value on success and an even value on failure.

See also
TdbCreateApiKey()
TdbRefreshTokenPair()
TdbPurgeTokens()
TdbPurgeUserTokens()
TdbRevokeTokens()
TdbEnumTokens()
TdbEnumUserTokens()
TdbDeallocate()

◆ TdbDeleteTicket()

int TdbDeleteTicket ( const char *  ticket)

Delete login ticket(s) for the currently logged in user,.

Parameters
ticketTicket to delete or an empty string for the current user's ticket
Returns
1 or other odd value on success, even value on error

Description

If the ticket parameter specifies a login ticket for another user, the currently logged on user must have SYSTEM privileges.

See also
TdbCreateTicket()

◆ TdbEnumApiKeys()

int TdbEnumApiKeys ( void **  handle,
char *  keyname,
size_t  keyname_size,
char *  comment,
size_t  comment_size,
char *  creator,
size_t  creator_size,
char *  credate,
size_t  credate_size,
char *  cretime,
size_t  cretime_size 
)

Enumerate available API keys.

Parameters
keynameBuffer to receieve the name of an API key
keyname_sizeThe allocated size of the keyname buffer
commentBuffer to receieve the comment for an API key
comment_sizeThe allocated size of the comment buffer
creatorBuffer to receieve the name of the creator of an API key
creator_sizeThe allocated size of the creator buffer
credateBuffer to receieve the creation date for an API key
credate_sizeThe allocated size of the credate buffer
cretimeBuffer to receieve the creation time for an API key
cretime_sizeThe allocated size of the cretime buffer
Returns
1 on success, 0 if there are no more keys, or a non-zero even value on error

◆ TdbEnumTokens()

int TdbEnumTokens ( void **  handle,
char *  user,
size_t  user_size,
char *  tag,
size_t  tag_size,
time_t *  created,
time_t *  access_expires_at,
time_t *  refresh_expires_at 
)

Enumerate access/refresh token pairs for all users.

Parameters
handlePointer to a void pointer that holds the enumeration state.
userBuffer that receives name of the user owning the token pair
user_sizeSize of the 'buffer' buffer
tagBuffer that receives the tag for the token pair
tag_sizeSize of the 'tag' buffer
createdReceives the date/time at which the token pair was created
access_expires_atReceives the date/time at which the access token expires
refresh_expires_atReceives the date/time at which the refres htoken expires
Returns
1 or other odd value on success, even value on error

Description

The first call to this function requires that the handle points to a void pointer set to NULL.

The function returns, for each call, information about a token pair; the owning user, the access token expiration timestamp, the refresh token expiration timestamp and the creation timestamp. The data is returned for all owned users if the user has UM (user manager) privileges, all users if the user is SYSTEM and has SUPERMAN privileges, or otherwise only for the current user if the user.

The once called, the function MUST be called until it returns zero or fails. Aborting the numeration call sequence without waiting for a zero or failure exit code will result in memory leaks.

Return Codes

This function returns 1 on success, 0 if there are no more tokens, and an even value on failure.

See also
TdbCreateTokenPair()
TdbRefreshTokenPair()
TdbPurgeTokens()
TdbPurgeUserTokens()
TdbRevokeTokens()
TdbEnumTokens()

◆ TdbEnumUserTokens()

int TdbEnumUserTokens ( const char *  username,
void **  handle,
char *  tag,
size_t  tag_size,
time_t *  created,
time_t *  access_expires_at,
time_t *  refresh_expires_at 
)

Enumerate access/refresh token pairs for a user.

Parameters
usernameThe name of the user for whom to enumerate tokens, or NULL for the current user
handlePointer to a void pointer that holds the enumeration state.
tagBuffer to receive the tag for the token pair
tag_sizeThe allocated size of the 'tag' buffer
createdReceives the date/time at which the token pair was created
access_expires_atReceives the date/time at which the access token expires
refresh_expires_atReceives the date/time at which the refresh token expires
Returns
1 or other odd value on success, even value on error

Description

The first call to this function requires that the handle points to a void pointer set to NULL. Unless the enumeration is for the currently logged on user, the first call must also specify the username parameter.

If first called without a username this function will enumerate tokens for the currently logged on user. Otherwise, the username must on first call be the name of a user owned by the currently logged on user, or the currently logged on user must have SYSTEM privileges.

The once called, the function MUST be called until it returns zero or fails. Aborting the numeration call sequence without waiting for a zero or failure exit code will result in memory leaks.

Return Codes

This function returns 1 on success, 0 if there are no more tokens, and an even value on failure.

See also
TdbCreateTokenPair()
TdbRefreshTokenPair()
TdbPurgeTokens()
TdbPurgeUserTokens()
TdbRevokeTokens()
TdbEnumTokens()
TdbEnumTokens()

◆ TdbGetConf()

int TdbGetConf ( const char *  symbolName,
int  section,
char *  valueBuffer,
size_t  bufferSize,
const char *  defaultValue 
)

Get a configuration symbol value.

Parameters
symbolNameName of configuration symbol to get
sectionId of tdbs.conf section to read value from
valueBufferBuffer that recives a copy of the value, or NULL to return the requried buffer size
bufferSizeAllocated size of the valueBuffer
defaultValueDefault value to assign if not found or NULL
Returns
1 on success, 0 if not found, or 2 if the specified bufferSize is too small

Description

Retrieves the value of a configuration symbol, as read from either the tdbs.conf file.

Valid values for the section parameter:

Symbolic Name Constant Value Purpose
CONF_PRIVILEGED 1 Look for value in the the Privileged section of tdbs.conf
CONF_GROUP 2 Look for value in the the user group specific section of tdbs.conf
CONF_NONPRIVILEGED 4 Look for value in the the NonPrivileged section of tdbs.conf
CONF_ALL 7 Look for value in any section of tdbs.conf

◆ TdbIsSuperUser()

int TdbIsSuperUser ( void  )

Check if current user has SUPERMAN privileges.

Returns
Non-zero if user is SUPERMAN, and zero otherwise

Description

The tdbs.conf privileged configuration setting TDBS_SUPERMAN will, if defined, give the SYSTEM user extended privileges such that it will be allowed to access CONTROL objects (databases, clusters, etc) owned by other users. This function returns a non-zero value if the current user is SYSTEM and has been granted SUPERMAN privileges.

◆ TdbMessage()

int TdbMessage ( int  messageNumber,
char *  message,
int *  length 
)

Retrieve the text of a TRIP message indicated by number, or display a message.

Parameters
messageNumberMessage number
messageText of message
lengthLength of message string
Returns
1 or other odd value on success, even value on error

Description

The function TdbMessage() retrieves the help or error message associated with the specified message number. The number should be a value previously returned by another TRIPapi routine. Return values smaller than the predefined constant MSG_HAS_TEXT are however not associated with a message, but simply indicate the success or failure of the routine called.

In ASE routines, TdbMessage() can be used to display a message supplied by the ASE routine itself. The message will appear on the TRIPclassic status bar when the ASE returns control to TRIPclassic. To specify the message text as an input argument, the message number must be set to MSG_SET_ERROR or MSG_SET_INFO . Note that for some types of ASEs (such as data entry ASEs) the display of the message is also dependent upon the code returned by the ASE.

Parameter Values

The messageNumber parameter is passed an int as the message number for which the associated text is to be retrieved. The acceptable values are:

Symbolic Name Constant Value Purpose
MSG_HAS_TEXT >= 32 Retrieve the text of the associated message
MSG_SET_ERROR -1 Display the message argument as a user-supplied error message in the TRIPclassic status line
MSG_SET_INFO -2 Display the message argument as a user-supplied information message in the TRIPclassic status line.

The message parameter is passed a character string as the text of the message. When messageNumber is either MSG_SET_ERROR or MSG_SET_INFO then the string passed in used otherwise the message text associated with messageNumber is returned in this string.

The length parameter is passed the length of the message string. When messageNumber is either MSG_SET_ERROR or MSG_SET_INFO then the argument is taken to be the length of the string being passed to TRIP otherwise it is returned as the length of the message text returned in the message string.

Return Codes

This function always succeeds.

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
See also
TdbRetCode()

◆ TdbPurgeTokens()

int TdbPurgeTokens ( int  mode,
time_t  from_timestamp,
time_t  to_timestamp,
int *  purgedcount,
FP_TdbPurgeTokensCallback  callback,
void *  userdata 
)

Purge expired access/refresh token pairs.

Parameters
modeOne of the TOKEN_PURGE_* values (see table below)
from_timestampDate/time from which to purge (depending on mode)
to_timestampDate/time until which to purge (depending on mode)
purgedcountRecieves pointer the number of purged token pairs
callbackOptional callback function to receive verbose purge information
userdataPointer to user data to pass along to the callback funciton
Returns
1 or other odd value on success, even value on error

Description

This function removes expires tokens (depending in the mode parameter) from either the current user (if logged on without UM or SM privileges), from the owned users (if logged on as UM), or from all users (if logged as SYSTEM with SUPERMAN privileges).

The number of tokens purged is output in the purgedcount parameter. For more verbose information on the purged tokens (creation time and expiration timestamps), a callback function can be provided, which gets called for each token matching the purge condition given by the mode parameter. Note that this verbose output can be emitted in part even if the function ultimately fails.

The valid values of mode are:

Symbolic Name Constant Value Description
TOKEN_PURGE_ALL 0 Purge all token pairs, expired or not
TOKEN_PURGE_REFRESH 1 Purge all token pairs whose refresh token has expired
TOKEN_PURGE_ACCESS 2 Purge all token pairs whose access token has expired
TOKEN_PURGE_REFRESH_BY_TIMERANGE 129 Purge all token pairs whose refresh token has expired within the time range specified by fromTimestamp and toTimestamp
TOKEN_PURGE_ACCESS_BY_TIMERANGE 130 Purge all token pairs whose access token has expired within the time range specified by fromTimestamp and toTimestamp
TOKEN_PURGE_CREATED_BY_TIMERANGE 132 Purge all token pairs created within the time range specified by fromTimestamp and toTimestamp (regardless of if the tokens have expired or not)

Return Codes

This function returns an odd value on success and an even value on failure.

See also
TdbCreateTokenPair()
TdbRefreshTokenPair()
TdbRevokeTokens()
TdbEnumTokens()
TdbEnumUserTokens()
TdbPurgeUserTokens

◆ TdbPurgeUserTokens()

int TdbPurgeUserTokens ( int  mode,
const char *  username,
time_t  from_fimestamp,
time_t  to_timestamp,
int *  purgedcount,
FP_TdbPurgeTokensCallback  callback,
void *  userdata 
)

Purge expired access/refresh token pairs for a user.

Parameters
modeOne of the TOKEN_PURGE_* values (see table below)
usernameThe name of the user for whom to purge tokens, or NULL for the current user
from_timestampDate/time from which to purge (depending on mode)
to_timestampDate/time until which to purge (depending on mode)
purgedcountRecieves pointer the number of purged token pairs
callbackOptional callback function to receive verbose purge information
userdataPointer to user data to pass along to the callback funciton
Returns
1 or other odd value on success, even value on error

Description

If called without a username this function will purge tokens from the currently logged on user. Otherwise, the username must be the name of a user owned by the currently logged on user, or the currently logged on user must have SYSTEM privileges.

The number of tokens purged is output in the purgedcount parameter. For more verbose information on the purged tokens (creation time and expiration timestamps), a callback function can be provided, which gets called for each token matching the purge condition given by the mode parameter. Note that this verbose output can be emitted even if the function ultimately fails.

The valid values of mode are:

Symbolic Name Constant Value Description
TOKEN_PURGE_ALL 0 Purge all token pairs, expired or not
TOKEN_PURGE_REFRESH 1 Purge all token pairs whose refresh token has expired
TOKEN_PURGE_ACCESS 2 Purge all token pairs whose access token has expired
TOKEN_PURGE_REFRESH_BY_TIMERANGE 129 Purge all token pairs whose refresh token has expired within the time range specified by fromTimestamp and toTimestamp
TOKEN_PURGE_ACCESS_BY_TIMERANGE 130 Purge all token pairs whose access token has expired within the time range specified by fromTimestamp and toTimestamp
TOKEN_PURGE_CREATED_BY_TIMERANGE 132 Purge all token pairs created within the time range specified by fromTimestamp and toTimestamp (regardless of if the tokens have expired or not)

Return Codes

This function returns an odd value on success and an even value on failure.

See also
TdbCreateTokenPair()
TdbRefreshTokenPair()
TdbRevokeTokens()
TdbEnumTokens()
TdbEnumUserTokens()
TdbPurgeTokens()

◆ TdbRefreshTokenPair()

int TdbRefreshTokenPair ( const char *  apikey,
const char *  current_refresh_token,
char **  access_token,
int *  access_token_length,
char **  refresh_token,
int *  refresh_token_length,
time_t *  access_expires_at,
time_t *  refresh_expires_at,
char *  username,
size_t  username_size 
)

Create an access/refresh token pair using a refresh token.

Parameters
apikeyA valid API key, or NULL / empty string if an API key is not required for token refresh
current_refresh_tokenValid one-time use refresh token
access_tokenRecieves pointer to the new access token
access_token_lengthRecieves the length of the access token
refresh_tokenRecieves pointer to the new refresh token
refresh_token_lengthRecieves the length of the refresh token
access_expires_atReceives the access token expiration timestamp
refresh_expires_atReceives the refresh token expiration timestamp
usernameReceives the name of the user to whom the token belongs
username_sizeThe size of the username buffer
Returns
1 or other odd value on success, even value on error

Description

If supplied with a valid, existing one-time use refresh token, this function creates a new access/refresh token pair to replace the token pair to which the current_refresh_token belongs.

This function can be used by anyone if the session is initialized but no user is logged on. If a user is logged on, the provided refresh token must either belong to the logged on user, or the logged on user must have user manager (UM) privileges.

If successful, a new access/refresh token pair is created and returned. The access token can be used to authenticate as the user for whom the token was created. Logging in using this access token is done using the normal APIs for login, save for that the token is passed as the password and the username as an empty string.

The pointers returned in access_token and refresh_token must be deallocated by call to the TdbDeallocate() function.

Return Codes

This function returns an odd value on success and an even value on failure.

See also
TdbCreateApiKey()
TdbCreateTokenPair()
TdbPurgeTokens()
TdbPurgeUserTokens()
TdbRevokeTokens()
TdbEnumTokens()
TdbEnumUserTokens()
TdbDeallocate()

◆ TdbResolvePath()

int TdbResolvePath ( const char *  symbolPath,
char *  resolved,
size_t  bufsize 
)

Resolve database file name containing logical names from tdbs.conf into a file systenm path.

Parameters
symbolPathDatabase (BAF, BIF, VIF) file name as specified in the DB design
resolvedBuffer to receieve the resolved path
bufsizeThe allocated size of the resolved buffer
Returns
1 on successs and 0 if path could not be resolved.

The successful resolution of the symbol path does not guarantee that the path actually exists on the local file system. If resolution fails, the resolved buffer is left unmodified.

◆ TdbRetCode()

int TdbRetCode ( void  )

Return the TRIP message number.

Returns
The return value returned by the previous TRIP function call.

Description

The function TdbRetCode() returns the current TRIP message number set by TRIP upon completion of other function calls.

Return Codes

This function can return any TRIPsystem code.

See also
TdbMessage()

◆ TdbRevokeApiKey()

int TdbRevokeApiKey ( const char *  keyname)

Revoke an API key.

Parameters
keynameThe name of the API key to revoke
Returns
1 or other odd value on success, even value on error

Description

This function deletes an existing API key. All token based access using the API key will immediately cease to work.

Return Codes

This function returns 1 on success, 0 if there are no more tokens, and an even value on failure.

See also
TdbCreateApiKey()
TdbApiKeyInfo()
TdbCreateTokenPair()
TdbRefreshTokenPair()
TdbRevokeTokens()

◆ TdbRevokeTokens()

int TdbRevokeTokens ( const char *  username,
const char *  token,
const char *  tag,
int *  revokecount,
FP_TdbPurgeTokensCallback  callback,
void *  userdata 
)

Revoke a specific token or all tokens for a particular user.

Parameters
usernameThe name of the user for whom to revoke token(s)
tokenAccess or refresh token for the token pair to revoke
tagTag of token pair to revoke. Used instead of token but requires username
revokecountRecieves pointer the number of revoked token pairs
callbackOptional callback function to receive verbose revocation information
userdataPointer to user data to pass along to the callback funciton
Returns
1 or other odd value on success, even value on error

Description

If called without either token or tag this function will revoke all tokens from the named user. If called with a tag and a username the user's tokens with identical tags will be revoked. If called both a token and a username the token must belong to the named user. If the named user is not the currently logged on user, the currently logged on user must be its owner or have SYSTEM privileges.

The number of revoked tokens is returned in the callback parameter. For more verbose information on the revoked tokens (creation time and expiration timestamps), a callback function can be provided, which gets called for each revoked token. Note that this verbose output can be emitted even if the function ultimately fails.

Return Codes

This function returns an odd value on success and an even value on failure.

See also
TdbCreateTokenPair()
TdbRefreshTokenPair()
TdbEnumTokens()
TdbEnumUserTokens()
TdbPurgeTokens()
TdbPurgeUserTokens()

◆ TdbSetConf()

int TdbSetConf ( const char *  symbolName,
const char *  symbolValue 
)

Assign a configuration value to use for the remainder of the current TRIP session.

Parameters
symbolNameName of configuration symbol to assign
symbolValueValue of the configuration symbol
Returns
1 or other odd value on success, even value on error

◆ TdbSetUICharset()

int TdbSetUICharset ( int  charset)

Change the session character set.

Parameters
charsetCharacter set to use
Returns
1 or other odd value on success, even value on error

Description

The valid values for the charset parameter for this function are:

Symbolic Name Constant Value Purpose
CHSET_NONE 0 Default character set.
CHSET_LA1 1 Latin 1
CHSET_UTF8 16 Unicode

If charset is set to CHSET_NONE, the value will be taken from the TDBS_CHARS logical name in tdbs.conf. Regardless of how the charset is specified (explicitly or implicitly via CHSET_NONE/TDBS_CHARS), the only valid values for the new character set are LATIN-1 and UTF-8.

Since

This function was introduced in TRIP version 8.2-0.

◆ TdbShellDefDateform()

int TdbShellDefDateform ( int  dateform,
char *  datestring 
)

Get or set a TRIP date format.

Parameters
dateformDate form number
datestringdate format delimiter characters on inut, and an example formatted date on output.
Returns
1 or other odd value on success, even value on error

Description

The function TdbShellDefDateForm() sets the date format to one of the 17 date formats supported by TRIP.

Parameter Values

The dateform parameter is passed an integer representing the format of the date. Pass the number as a positive value to retrieve an example date formatted in the specified format. Pass the number as a negative value to also change the current session's date format to the specified one. Acceptable values are:

Value Date format Example for May 1st 1988
1 YYYY-MM-DD 1988-05-01
2 YYYY-mM-dD 1988-5-1
3 yyYY-mM-dD 88-5-1
4 YYYY-mm-dD 1988-May-1
5 yyYY-mm-dD 88-May-1
6 MM-DD-YYYY 05-01-1988
7 mM-dD-YYYY 5-1-1988
8 mM-dD-yyYY 5-1-88
9 mm-dD-YYYY May-1-1988
10 mm-dD-yyYY May-1-88
11 DD-MM-YYYY 01-05-1988
12 dD-mM-YYYY 1-5-1988
13 dD-mM-yyYY 1-5-88
14 dD-mm-YYYY 1-May-1988
15 dD-mm-yyYY 1-May-88
16 YYYYMMDD 19880501
17 yyYYMMDD 880501

The datestring parameter is passed a two-character string with the delimiter characters to use in the date string, e.g. "--" for the examples above. It receives an example of a date formatted in the specified form, which is why the buffer that datestring refers to must be large enough to accommodate the formatted example date.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 Could not set the date form.
See also
TdbCheckDate()
TdbShellModifyCcl()

◆ TdbShellModifyCcl()

int TdbShellModifyCcl ( int  language)

Modify the CCL locale language being used.

Parameters
languageCCL locale language to use
Returns
1 or other odd value on success, even value on error

Description

The function TdbShellModifyCcl() can be used to change the CCL language that is being used in the normal TRIP search mode.

Parameter Values

The language parameter is passed an int as the indicator for the CCL locale language to use. Valid values are:

Symbolic Name Constant Value Purpose
LANGUAGE_DEFAULT 1 Use the system default language
LANGUAGE_ENGLISH 9 Use English dialect
LANGUAGE_SWEDISH 10 Use Swedish dialect
LANGUAGE_CHINESE 11 Use Chinese dialect
LANGUAGE_GERMAN 12 Use German dialect
LANGUAGE_FRENCH 13 Use French dialect
LANGUAGE_FINNISH 14 Use Finnish dialect
LANGUAGE_NORWEGIAN 15 Use Norwegian dialect

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
See also
TdbStartTrip()
TdbShellDefDateForm()
TdbCheckDate()

◆ TdbShellType()

int TdbShellType ( char *  fieldtypeName,
int *  fieldtypeNumber 
)

Check a field type on its name or number.

Parameters
fieldtypeNameName of field type
fieldtypeNumberField type number
Returns
1 or other odd value on success, even value on error

Description

The function TdbShellType() returns information about a field type. If the field type is specified by a number, the routine will return the name in the user's current CCL dialect. The type number can also be set to zero, in which case the field type name (or the first part of the name) must be specified in order to obtain the number of the type.

Parameter Values

The fieldtypeName parameter is passed a character string as the name of the field type. The string has to be at least 16 characters long. If the type name is only partially specified, the name will be expanded on return.

The fieldtypeNumber parameter is passed a pointer to an integer to receive the field type number. Acceptable values are:

Symbolic Name Constant Value Purpose
0 The type number can also be set to zero, in which case the field type name (or the first part of the name) must be specified in order to obtain the number of the type.
FIELD_TEXT 1 TExt type field
FIELD_PHRASE 3 PHRase type field
FIELD_INTEGER 9 INteger type field
FIELD_NUMBER 10 NUMber type field
FIELD_DATE 11 DAte type field
FIELD_TIME 12 TIme type field
FIELD_STRING 14 STring type field

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 Field check failed.
See also
TdbCheckField()

◆ TdbStartTrip()

int TdbStartTrip ( char *  username,
char *  password,
int  language,
int  mode 
)

Initializes the client application for a new TRIP session.

Parameters
usernameName of user or empty string.
passwordPassword of user or empty string
languageCCL locale language
modeTRIP initialization options. Pass 0 if not used.
Returns
1 or other odd value on success, even value on error

Description

The TdbStartTrip() function initializes TRIP for use by the calling process. It performs consistency checks upon the operating system environment, TRIPsystem installation, licence conditions, and initialises essential status variables and reporting mechanisms in TRIP. If the site running the application is controlled by a concurrent user license, the TRIPdaemon service is consulted to gain a session token, if possible. It checks for the existence and accessibility of the data dictionary (the CONTROL database) and of the error message store (the TDBSERR database) that the kernel needs during execution. If the site running the application is controlled by a concurrent user license, TRIPdaemon is consulted to gain a session token, if possible.

The TdbStartTrip() function is the first function that should be called by an application program. Upon return, and assuming a success return code, the session will have been initialised. However, this function should never be called by an application software exit (ASE) as all required initialisation will have been successfully completed prior to the ASE being activated.

The TdbStartTrip() function replaces TdbBeginTdbs(), TdbShellInit() and optionally TdbCheckUser() .

If login tickets are enabled and ticket based login is desired, the password parameter is passed a string with the login ticket, and the username parameter left as an empty string. If the username (parameter is left empty (and also password if login tickets are enabled), TdbStartTrip() will work as specified, except that it does not call TdbCheckUser(), which instead must be called afterwards by the application.

Parameter Values

The username parameter is passed a character string as the name of the user being checked or an empty string.

The password parameter is passed a character string as the password for the user being checked or an empty string.

The language parameter is passed an integer that indicates the CCL locale language to use. Valid values are:

Symbolic Name Constant Value Purpose
LANGUAGE_DEFAULT 1 Use the system default language
LANGUAGE_ENGLISH 9 Use English dialect
LANGUAGE_SWEDISH 10 Use Swedish dialect
LANGUAGE_CHINESE 11 Use Chinese dialect
LANGUAGE_GERMAN 12 Use German dialect
LANGUAGE_FRENCH 13 Use French dialect
LANGUAGE_FINNISH 14 Use Finnish dialect
LANGUAGE_NORWEGIAN 15 Use Norwegian dialect

The mode parameter is passed an integer that indicates the TRIP initialization options to use. The mode parameter is a bit mask. This means that the various option values can be easily combined, e.g. "16 | CHARSET_MODE(CHSET_UTF)". However, only one character set option may be assigned.

The mode parameter can also be used to indicate which character set to use for the session. This overrides the TDBS_CHARS value as specified in the TRIPrcs file. This is also the only way by which unicode (in the UTF-8 encoding) can be chosen as character set.

Valid character set values for the mode parameter:

Symbolic Name Constant Value Purpose
CHARSET_MODE(CHSET_NONE) 0 Default character set.
CHARSET_MODE(CHSET_LA1) 256 Latin 1
CHARSET_MODE(CHSET_LA2) 512 Latin 2
CHARSET_MODE(CHSET_LA3) 768 Latin 3
CHARSET_MODE(CHSET_UTF8) 4096 Unicode
CHARSET_MODE(CHSET_CHI) 4352 Chinese
CHARSET_MODE(CHSET_GBK) 4608 Chinese GBK
CHARSET_MODE(CHSET_EUC) 4864 EUC
CHARSET_MODE(CHSET_SJIS) 5120 Shift-JIS

Note that the character set value to pass to the mode parameter is shifted 8 bits in order to be able to fit into this bit mask. This shifting is done using the CHARSET_MODE macro, as illustrated in the table above. Using one of the character set contstants (e.g. CHSET_UTF8) directly will not work.

Miscellaneous other options for the mode parameter:

Constant Value Purpose
16 Restart a former session.

Since

This function was introduced in TRIP version 3.4-0.

Return Codes

Note
If the TdbStartTrip() function fails and haven't previously been successfully called with a blank username and password, the error message cannot be fetched by calling TdbMessage() since no session will yet exist.
 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
9634 No such user as username The supplied user name could not be identified as a TRIP user.
9666 User id username is a group id The supplied user name was identified as the name of a TRIP group.
10306 Invalid password - Please try again. The supplied password was not valid for the specified user.
15840 Concurrent user quota (N) exceeded The maximum number of licenced concurrent TRIP users has been reached. When this error code is returned the accompanying error text will include the maximum number of concurrent users licenced for the machine.
16512 Invalid TRIPdaemon process name TRIPsystem cannot locate the process for the TRIP daemon.
See also
TdbStopTrip()
TdbSessionInfo()
TdbChangeUser()
TdbShellDefDateForm()

◆ TdbStopTrip()

int TdbStopTrip ( boolean  restart)

Terminates a TRIP session started with TdbStartTrip.

Parameters
restartMode of session reinitialization. Use value 1 to restart session from saved SIF file, and 0 (zero) to reinitialize a new session. When using the client version of this API, only pass 0 (zero).
Returns
1 or other odd value on success, even value on error

Description

The TdbStopTrip() function will end a TRIP session that has been started with TdbStartTrip .

The TdbStopTrip() function replaces TdbEndTdbs().

When a server-side TRIP application exits, an option exists to save the current SIF file for future use. The restart parameter is given value 1 to save the SIF file, and 0 (zero) to delete it.

This function must be the last TRIP toolkit routine called by the application. The server-side version must be called only once per image activation.

Since

This function was introduced in TRIP version 3.4-0.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
10434 Background printing still in progress. This may occur when a PRINT command is still executing on the server.
See also
TdbStartTrip()