This header declares functions for accessing the MessageTrans SWIs. It declares MessageTrans_ functions, which are veneers to some of the module SWIs, and MsgTrans_ functions which provide a higher level interface in a way likely to be of use in a desktop application.
To use the higher level interface, call MsgTrans_LoadFile to open and load your message file, MsgTrans_Lookup to look up the value of tokens and, finally, MsgTrans_LoseFile to close the file when you're finished.
The message file format consists of a series of lines of the form "Token:Text message with parameters %0 to %3". You can specify more than one token for a message by separating the alternative tokens with '/' or LF, eg. "Token1/Token2:Message". You can put '?' in a token, and it will then match any character when you look up the message. eg. "gr?y:The colour grey" would be found by the tokens "grey", "gray", and a good many more.
Lines beginning with '#' are comments. If you wish to use a percent sign in your message you should use "%%" because the percent symbol is used to mark parameter substitutions.
This gets information about a Messages file prior to opening it. You pass a pointer to the filename, and it returns the size of buffer required to hold the file and sets bit 1 of 'flags' if the file is held in memory. This means that if you require read-only access you need not use a buffer to access it.
It returns NULL if successful, an error block otherwise.
This opens a messages file ready for reading. You pass a pointer to a file descriptor block, the file path name of the file you wish to open and a pointer to the buffer to hold the file.
If 'buffer' is NULL, then both the file descriptor block and the filename should be stored in RMA, and the module will allocate space in the RMA as needed to hold the file. Otherwise, the buffer should be at least the size returned by MessageTrans_FileInfo to be large enough to hold the file.
It returns NULL if sucessful, or an error block. One error you might get is "Message file already open" if the descriptor is in use.
This looks up the given token in the given open messages file, and returns the string in the buffer pointed to by 'buffer' (unless 'buffer' is NULL in which case the string isn't copied), whose size is given by 'size'. You can pass up to four strings to be substituted in place of %0, %1, etc. in the looked up message, or NULL if there is no substitution.
It updates 'buffer' to point to the result string, and 'size' to give the size of the resulting string (not including the terminator). If you didn't pass in a buffer, no substitution can be done in the message, and you get a *read-only* pointer to the message in question.
If you give zero as the 'filedesc', the message will be looked up in the global messages (held in Resources:$.Resources.Global.Messages).
You can supply a token in the form "Token:Default string" and if the token isn't found in the file the default string is used instead.
This function returns NULL if there are no errors.
This closes a message file opened with MessageTrans_OpenFile, you simply pass it the file descriptor block you received from that function.
This function returns NULL if there are no errors.
This function allocates space (using malloc) for the given message file and loads it. If fills 'filedesc' with a pointer to a MessageTrans file descriptor block if no errors occur.
The function will check for the existence of "filename" and if it's not present, will try again after prefixing the filename with the location of your application resources (as set up for the Resource module). If it still can't find a file, an error is returned.
This function returns NULL if there are no errors.
This looks up the given token in the given file, and copies the matched token's message to the given buffer (of length 'bufflen') and ensure that it is properly '\0' terminated. This allows up to four parameters to be subsituted with the strings passed in p0..p3. If you do not wish to substitute any of these, pass NULL instead of a string.
You can supply a token in the form "Token:Default string" and if the token isn't found in the file the default string is used instead.
This function returns NULL if there are no errors.
This closes a message file opened with MsgTrans_LoadFile (so long as filedesc is not NULL), and frees the memory occupied by that file. You should pass the file descriptor returned by that earlier call.
This function returns NULL if there are no errors.
This looks up the given token in the given message file, copies it into an internal buffer and passes it to Error_Report if 'fatal' is FALSE or Error_ReportFatal if 'fatal' is TRUE. This allows subsitution of up to four parameters with the strings in p0..p3. If you do not wish to substitute any of these, pass NULL instead of a string.
You can supply a token in the form "Token:Default string" and if the token isn't found in the file the default string is used instead.
This function returns NULL if it is successful.
#define MsgTrans_Lookup(filedesc, token, buffer, bufflen) \
MsgTrans_LookupPS((filedesc), (token), (buffer), (bufflen), \
NULL, NULL, NULL, NULL)
MACRO: extern os_error *MsgTrans_Lookup(msgtrans_filedesc *filedesc, char *token, char *buffer, int bufflen);
This looks up the given token in the given file, and copies the matched token's message to the given buffer (of length 'bufflen') and ensures that it is properly '\0' terminated. This doesn't allow parameter substitution.
You can supply a token in the form "Token:Default string" and if the token isn't found in the file the default string is used instead.
This function returns NULL if there are no errors.
#define MsgTrans_Report(filedesc, token, fatal) \ MsgTrans_ReportPS((filedesc),(token),(fatal),0,0,0,0)
MACRO: extern os_error *MsgTrans_Report(msgtrans_filedesc *filedesc, char *token, BOOL fatal);
This looks up the given token in the given message file, copies it into an internal buffer and passes it to Error_Report if 'fatal' is FALSE or Error_ReportFatal if 'fatal' is TRUE.
You can supply a token in the form "Token:Default string" and if the token isn't found in the file the default string is used instead.
This function returns NULL if it is successful.
This is a file descriptor block for use with the MessageTrans SWIs. This shouldn't be accessed directly by the user, only passed to and returned from various SWIs intact.