blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal
Defines | Typedefs | Enumerations | Functions

C Language Programming Interface List

This page lists the elements of the BlackBerry Dynamics C language programming interface. More...

Defines

Typedefs

Enumerations

Functions


Detailed Description

There is a C language programming interface for some BlackBerry Dynamics capabilities. Functions and other elements in the interface in general have the same names as the corresponding elements in the Standard C library or POSIX standard interface, but with a "GD_" or "GD_UNISTD_" prefix. For example, the BlackBerry Dynamics functions are GD_fopen() instead of fopen(), and GD_accept() instead of accept(). The interfaces are otherwise the same, with some exceptions.

Note that opening a file with the C interface doesn't lock the file.

See also:
System Interfaces: Detailed Table of Contents on the opengroup.org website for links to specifications of the POSIX standard interface.
GDFileManager for details of the BlackBerry Dynamics secure file system.

Define Documentation

#define GD_C_API_EXT
#define GD_C_API_EXT

Typedef Documentation

typedef size_t GD_FILE
typedef size_t GD_DIR
typedef void(* nslookupCompletionCallback)(const char *jsonResponse)

Pass a reference to a function of this type as the callback parameter to the GD_nslookup() function.

The callback receives one parameter.

Parameters:
jsonResponsechar * containing a JSON string representation of the results, or an empty string, or NULL. See GD_nslookup() for details.
typedef void(* nslookupCompletionCallbackEx)(const char *jsonResponse, const void *data)

Pass a reference to a function of this type as the callback parameter to the GD_nslookupEx() function.

The callback receives two parameters.

Parameters:
jsonResponsechar * containing a JSON string representation of the results, or an empty string, or NULL. See GD_nslookup() for details.
datavoid * pointer to the extended data that was passed to the original function call.

Use these constants to specify the type of results required for a BlackBerry Dynamics name service lookup. The type parameter of the GD_nslookup() function always takes one of these values.

typedef void(* completionCallback)(const char *myIP)

Pass a reference to a function of this type as the callback parameter to the GD_myipaddress() function.

The callback receives one parameter.

Parameters:
myIPchar * containing an IP address, or an empty string, or NULL. See GD_myipaddress() for details.
typedef void(* completionCallbackEx)(const char *myIP, const void *data)

Pass a reference to a function of this type as the callback parameter to the GD_myipaddressEx() function.

The callback receives two parameters.

Parameters:
myIPchar * containing an IP address, or an empty string, or NULL. See GD_myipaddress() for details.
datavoid * pointer to the extended data that was passed to the original function call.

Enumeration Type Documentation

enum GD_ROUTE

Use the constants in this enumeration to check the return value of GD_getRouteInfo.

Enumerator:
GD_ROUTE_UNKNOWN 

The connection information didn't include BlackBerry Dynamics routing information.

GD_ROUTE_INTERNET 

The connection will be routed direct to the Internet.

GD_ROUTE_GOOD_PROXY 

The connection will be routed via the BlackBerry Dynamics infrastructure.

GD_ROUTE_DENY 

The connection will be denied via the BlackBerry Dynamics SDK.

GD_ROUTE_INTERNET_LISTED 

The connection will be routed direct to the Internet per WhiteList.

Use these constants to specify the type of results required for a BlackBerry Dynamics name service lookup. The type parameter of the GD_nslookup() function always takes one of these values.

Enumerator:
GD_nslookup_CNAME 

Specify a CNAME lookup.

GD_nslookup_ARECORD 

Specify an A record lookup.


Function Documentation

int GD_fcntl ( int  fd,
int  cmd,
  ... 
)
GD_FILE* GD_fopen ( const char *  filename,
const char *  mode 
)

Call this function to open a file in the secure store for reading or writing. Files in the secure store are encrypted on the device; this function provides access to decrypted data.

Parameters:
filenameconst char* pointer to a C string containing the path, within the secure store, that represents the file to be opened.
modeconst char* pointer to a C string of the mode. The values are analogous to the standard C call fopen and can be:

  • write "w"
  • read "r"
  • append "a"

Note that the "+" qualifier is supported for opening a file for both reading and writing.
The "b" and "t" qualifiers aren't supported.

Returns:
GD_FILE* object pointer (analogous to the FILE* file pointer returned from fopen) which can be used for subsequent file access, or NULL if the file could not be opened or created.
int GD_fclose ( GD_FILE filePointer)

Call this function to close a file that was previously opened by a call to GD_fopen.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.

Note that this should always be called when file access is no longer required. It also forces a flush of any uncommitted write operation.

Returns:
int 0 if successful, EOF otherwise
size_t GD_fread ( void *  ptr,
size_t  size,
size_t  count,
GD_FILE filePointer 
)

Call this function to read a file in the secure store previously opened with GD_open in a read mode such as "r" or "w+".

Parameters:
ptrvoid* pointer to a buffer to receive the read data.
sizesize_t size of the data block.
countsize_t number of data blocks.
filePointerGD_FILE* a pointer to a valid GD_FILE* object.

(Note that the underlying library simply reads size * count bytes from the secure file system.)

Returns:
size_t The total number of elements successfully read is returned. If this number differs from the count parameter, either a reading error occurred or the end-of-file was reached while reading. In both cases, the proper indicator is set, which can be checked with ferror and feof, respectively. If either size or count is zero, the function returns zero and both the stream state and the content pointed by ptr remain unchanged.
size_t is an unsigned integral type.
size_t GD_fwrite ( const void *  ptr,
size_t  size,
size_t  count,
GD_FILE filePointer 
)

Call this function to read a file in the secure store previously opened with GD_open in a read mode such as "w" or "r+".

Parameters:
ptrvoid* pointer to a buffer containing the data to be written
sizesize_t size of the data block.
countsize_t number of data blocks
filePointerGD_FILE* a pointer to a valid GD_FILE* object

(Note that the underlying library simply writes size * count bytes to the encrypted file system.)

Returns:
size_t The total number of elements successfully written is returned. If this number differs from the count parameter, a writing error prevented the function from completing. In this case, the error indicator (ferror) will be set for the stream. If either size or count is zero, the function returns zero and the error indicator remains unchanged. size_t is an unsigned integral type.
int GD_remove ( const char *  filename)

Call this function to delete a file by path.

Parameters:
filenameconst char* the path of the field to be deleted.
Returns:
int 0 if successful, -1 otherwise.
long int GD_ftell ( GD_FILE filePointer)

Call this function obtain the current file pointer position.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
Returns:
long int the position of the file pointer or -1 if an error has occurred.
off_t GD_ftello ( GD_FILE filePointer)

Call this function obtain the current file pointer position.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
Returns:
off_t the position of the file pointer or -1 if an error has occurred.
int GD_fseek ( GD_FILE filePointer,
long int  offset,
int  origin 
)

Call this function to set the file pointer position.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
offsetlong int offset relative to the origin parameter
originint one of SEEK_SET, SEEK_CUR, SEEK_END
Returns:
int 0 for success or -1 for failure
int GD_fseeko ( GD_FILE filePointer,
off_t  offset,
int  origin 
)

Call this function to set the file pointer position.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
offsetoff_t offset relative to the origin parameter
originint one of SEEK_SET, SEEK_CUR, SEEK_END
Returns:
int 0 for success or -1 for failure
int GD_fscanf ( GD_FILE filePointer,
const char *  format,
  ... 
)

Reads data from the stream and stores them according to the parameter format into the locations pointed by the additional arguments. The additional arguments should point to already allocated objects of the type specified by their corresponding format specifier (subsequences beginning with %) within the format string.

Parameters:
filePointerPointer to a GD_FILE object that identifies an input stream to read data from.
formatC string that contains a sequence of characters that control how characters extracted from the stream are treated.
Returns:
int On success, the function returns the number of items of the argument list successfully filled. On error, the function returns EOF and sets the error indicator (ferror).
int GD_vfscanf ( GD_FILE filePointer,
const char *  format,
va_list  args 
)

Reads data from the stream and stores them according to parameter format into the locations pointed to by the elements in the variable argument list identified by args.

Internally, the function retrieves arguments from the list identified by arg as if va_arg was used on it, and thus the state of arg is likely to be altered by the call.

In any case, arg should have been initialized by va_start at some point before the call, and it is expected to be released by va_end at some point after the call.

Parameters:
filePointerPointer to a GD_FILE object that identifies an input stream.
formatC string that contains a format string that follows the same specification as scanf (see scanf for details).
argsA value identifying a variable arguments list initialized with va_start. va_list is a special type defined in <stdarg.h> file.
Returns:
int On success, the function returns the number of items of the argument list successfully filled. On error, the function returns EOF and sets the error indicator (ferror).
int GD_feof ( GD_FILE filePointer)

Call this function to check if the file pointer is at the end of the file.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
Returns:
int non-zero if the end of file indicator is set, otherwise 0
char* GD_tmpnam ( char *  str)

Call this function to check or generate a unique file name

Parameters:
strchar* an array of bytes of at least L_tmpnam length to contain the proposed file name. If this argument is NULL then an internal static array is used.
Returns:
char* a pointer to a unique filename. If the str argument is not NULL then the pointer will refer to this array otherwise it will point to an internal static array. If the function cannot create a unique filename then NULL is returned.
int GD_truncate ( const char *  filename,
off_t  length 
)

Call this function to truncate a file in the secure store to a specified length. If file was previously larger than the length specified, the file will be truncated and the extra data lost. If the file was previously smaller than the length specified, the file will be extended and padded with null bytes ('\0').

Parameters:
filenameconst char* pointer to a C string containing the path, within the secure store, that represents the file to be truncated.
lengthoff_t in bytes of the file once truncated.
Returns:
int 0 for success or -1 for failure
int GD_ftruncate ( GD_FILE filePointer,
off_t  length 
)

Call this function to truncate a file in the secure store to a specified length. If file was previously larger than the length specified, the file will be truncated and the extra data lost. If the file was previously smaller than the length specified, the file will be extended and padded with null bytes ('\0').

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
lengthoff_t in bytes of the file once truncated.
Returns:
int 0 for success or -1 for failure
GD_FILE* GD_freopen ( const char *  filename,
const char *  mode,
GD_FILE filePointer 
)

Reuses stream to either open the file specified by filename or to change its access mode. If a new filename is specified, the function first attempts to close any file already associated with filePointer (third parameter) and disassociates it. Then, independently of whether that filePointer was successfuly closed or not, freopen opens the file specified by filename and associates it with the filePointer just as fopen would do using the specified mode. If filename is a null pointer, the function attempts to change the mode of the filePointer. The error indicator and eof indicator are automatically cleared (as if clearerr was called).

Parameters:
filenameconst char* C string containing the name of the file to be opened.
modeconst char* pointer to a C string of the mode. The values are analogous to the standard C call fopen and can be:

  • write "w"
  • read "r"
  • append "a"

Note that the "+" qualifier is supported for opening a file for both reading and writing.
The "b" and "t" qualifiers aren't supported.

filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
Returns:
GD_FILE* If the file is successfully reopened, the function returns the pointer passed as parameter filePointer, which can be used to identify the reopened stream. Otherwise, a null pointer is returned.
int GD_fgetpos ( GD_FILE filePointer,
fpos_t *  pos 
)

Retrieves the current position in the stream. The function fills the fpost_t object pointed by pos with the information needed from the filePointer's position indicator to restore the stream to its current position (and multibyte state, if wide-oriented) with a call to fsetpos. The ftell function can be used to retrieve the current position in the stream as an integer value.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
posfpos_t Pointer to a fpos_t object.
Returns:
int On success, the function returns zero. In case of error, errno is set to a platform-specific positive value and the function returns a non-zero value.
int GD_fsetpos ( GD_FILE filePointer,
const fpos_t *  pos 
)

Restores the current position in the stream to pos. The internal file position indicator associated with stream is set to the position represented by pos, which is a pointer to an fpos_t object whose value shall have been previously obtained by a call to fgetpos. The end-of-file internal indicator of the stream is cleared after a successful call to this function, and all effects from previous calls to ungetc on this stream are dropped. On streams open for update (read+write), a call to fsetpos allows to switch between reading and writing.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
posfpos_t Pointer to a fpos_t object containing a position previously obtained with fgetpos.
Returns:
int On success, the function returns zero. On failure, a non-zero value is returned and errno is set to a system-specific positive value.
void GD_rewind ( GD_FILE filePointer)

Sets the position indicator associated with stream to the beginning of the file. The end-of-file and error internal indicators associated to the stream are cleared after a successful call to this function, and all effects from previous calls to ungetc on this stream are dropped. TBC::On streams open for update (read+write), a call to rewind allows to switch between reading and writing.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
int GD_fgetc ( GD_FILE filePointer)

Returns the character currently pointed by the internal file position indicator of the specified stream. The internal file position indicator is then advanced to the next character. If the stream is at the end-of-file when called, the function returns EOF and sets the end-of-file indicator for the stream (feof). If a read error occurs, the function returns EOF and sets the error indicator for the stream (ferror).

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
Returns:
int On success, the character read is returned (promoted to an int value). The return type is int to accommodate for the special value EOF, which indicates failure: If the position indicator was at the end-of-file, the function returns EOF and sets the eof indicator (feof) of stream. If some other reading error happens, the function also returns EOF, but sets its error indicator (ferror) instead.
char* GD_fgets ( char *  buf,
int  count,
GD_FILE filePointer 
)

Reads characters from stream and stores them as a C string into str until (num-1) characters have been read or either a newline or the end-of-file is reached, whichever happens first. A newline character makes fgets stop reading, but it is considered a valid character by the function and included in the string copied to str. A terminating null character is automatically appended after the characters copied to str.

Parameters:
bufchar* Pointer to an array of chars where the string read is copied.
countint Maximum number of characters to be copied into str (including the terminating null-character).
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
Returns:
char* On success, the function returns str. If the end-of-file is encountered while attempting to read a character, the eof indicator is set (feof). If this happens before any characters could be read, the pointer returned is a null pointer (and the contents of str remain unchanged). If a read error occurs, the error indicator (ferror) is set and a null pointer is also returned (but the contents pointed by str may have changed).
int GD_fputc ( int  character,
GD_FILE filePointer 
)

Writes a character to the stream and advances the position indicator. The character is written at the position indicated by the internal position indicator of the stream, which is then automatically advanced by one.

Parameters:
characterint The int promotion of the character to be written. The value is internally converted to an unsigned char when written.
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
Returns:
int On success, the character written is returned. If a writing error occurs, EOF is returned and the error indicator (ferror) is set.
int GD_fputs ( const char *  buf,
GD_FILE filePointer 
)

Writes the C string pointed by str to the stream. The function begins copying from the address specified (str) until it reaches the terminating null character ('\0'). This terminating null-character is not copied to the stream.

Parameters:
bufconst char* C string with the content to be written to stream.
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
Returns:
int On success, a non-negative value is returned. On error, the function returns EOF and sets the error indicator (ferror).
int GD_fprintf ( GD_FILE filePointer,
const char *  format,
  ... 
)

Writes the C string pointed by format to the stream. If format includes format specifiers (subsequences beginning with %), the additional arguments following format are formatted and inserted in the resulting string replacing their respective specifiers.

Parameters:
filePointerPointer to a GD_FILE object that identifies an output stream.
formatC string that contains the text to be written to the stream. It can optionally contain embedded format specifiers that are replaced by the values specified in subsequent additional arguments and formatted as requested.
Returns:
int On success, the total number of characters written is returned. On error, the function returns EOF and sets the error indicator (ferror).
int GD_vfprintf ( GD_FILE filePointer,
const char *  format,
va_list  args 
)

Writes the C string pointed by format to the stream, replacing any format specifier in the same way as printf does, but using the elements in the variable argument list identified by arg instead of additional function arguments.

Internally, the function retrieves arguments from the list identified by arg as if va_arg was used on it, and thus the state of arg is likely altered by the call.

In any case, arg should have been initialized by va_start at some point before the call, and it is expected to be released by va_end at some point after the call.

Parameters:
filePointerPointer to a GD_FILE object that identifies an output stream.
formatC string that contains a format string that follows the same specifications as format in printf (see printf for details).
argsA value identifying a variable arguments list initialized with va_start. va_list is a special type defined in the <stdarg.h> file.
Returns:
int On success, the total number of characters written is returned. On error, the function returns EOF and sets the error indicator (ferror).
int GD_rename ( const char *  oldname,
const char *  newname 
)

Changes the name of the file or directory specified by oldname to newname. This is an operation performed directly on a file; No streams are involved in the operation. If oldname and newname specify different paths and this is supported by the system, the file is moved to the new location. If newname names an existing file, the function may either fail or override the existing file, depending on the specific system and library implementation.

Parameters:
oldnameconst char* C string containing the name of an existing file to be renamed and/or moved.
newnameconst char* C string containing the new name for the file.
Returns:
int If the file is successfully renamed, a zero value is returned. On failure, a nonzero value is returned.
int GD_setvbuf ( GD_FILE filePointer,
char *  buf,
int  mode,
size_t  size 
)

Specifies a buffer for stream. The function allows to specify the mode and size of the buffer (in bytes). If buffer is a null pointer, the function automatically allocates a buffer (using size as a hint on the size to use). Otherwise, the array pointed by buffer may be used as a buffer of size bytes. This function should be called once the stream has been associated with an open file, but before any input or output operation is performed with it. A stream buffer is a block of data that acts as intermediary between the i/o operations and the physical file associated to the stream: For output buffers, data is output to the buffer until its maximum capacity is reached, then it is flushed (i.e.: all data is sent to the physical file at once and the buffer cleared). Likewise, input buffers are filled from the physical file, from which data is sent to the operations until exhausted, at which point new data is acquired from the file to fill the buffer again. Stream buffers can be explicitly flushed by calling fflush. They are also automatically flushed by fclose and freopen, or when the program terminates normally.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
bufchar* User allocated buffer. Shall be at least size bytes long. If set to a null pointer, the function automatically allocates a buffer.
modeint Specifies a mode for file buffering.(_IOFBF, _IOLBF and _IONBF)
sizesize_t Buffer size, in bytes. If the buffer argument is a null pointer, this value may determine the size automatically allocated by the function for the buffer.
Returns:
int If the buffer is correctly assigned to the file, a zero value is returned. Otherwise, a non-zero value is returned; This may be due to an invalid mode parameter or to some other error allocating or assigning the buffer.
void GD_setbuffer ( GD_FILE filePointer,
char *  buf,
int  size 
)

Specifies a buffer for stream. The function allows to specify the size of the buffer (in bytes). If buffer is a null pointer, the function automatically allocates a buffer (using size as a hint on the size to use). Otherwise, the array pointed by buffer may be used as a buffer of size bytes. This function should be called once the stream has been associated with an open file, but before any input or output operation is performed with it. A stream buffer is a block of data that acts as intermediary between the i/o operations and the physical file associated to the stream: For output buffers, data is output to the buffer until its maximum capacity is reached, then it is flushed (i.e.: all data is sent to the physical file at once and the buffer cleared). Likewise, input buffers are filled from the physical file, from which data is sent to the operations until exhausted, at which point new data is acquired from the file to fill the buffer again. Stream buffers can be explicitly flushed by calling fflush. They are also automatically flushed by fclose and freopen, or when the program terminates normally.

Except for the lack of a return value, the GD_setbuffer function is exactly equivalent to the call setvbuf(stream, buf, buf ? _IOFBF : _IONBF, size);

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
bufchar* User allocated buffer. Shall be at least size bytes long. If set to a null pointer, the function automatically allocates a buffer.
sizeint Buffer size, in bytes. If the buffer argument is a null pointer, this value may determine the size automatically allocated by the function for the buffer.
void GD_setbuf ( GD_FILE filePointer,
char *  buf 
)

Specifies a buffer for stream. If buffer is a null pointer, the function automatically allocates a buffer. Otherwise, the array pointed by buffer may be used as a buffer of size BUFSIZ. This function should be called once the stream has been associated with an open file, but before any input or output operation is performed with it. A stream buffer is a block of data that acts as intermediary between the i/o operations and the physical file associated to the stream: For output buffers, data is output to the buffer until its maximum capacity is reached, then it is flushed (i.e.: all data is sent to the physical file at once and the buffer cleared). Likewise, input buffers are filled from the physical file, from which data is sent to the operations until exhausted, at which point new data is acquired from the file to fill the buffer again. Stream buffers can be explicitly flushed by calling fflush. They are also automatically flushed by fclose and freopen, or when the program terminates normally.

Except for the lack of a return value, the GD_setbuf() function is exactly equivalent to the call GD_setvbuf(filePointer, buf, buf ? _IOFBF : _IONBF, BUFSIZ);

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
bufchar* User allocated buffer. Shall be BUFSIZ bytes long. If set to a null pointer, the function automatically allocates a buffer.
int GD_fflush ( GD_FILE filePointer)

If the given stream was open for writing (or if it was open for updating and the last i/o operation was an output operation) any unwritten data in its output buffer is written to the file. If stream is a null pointer, all such streams are flushed. In all other cases, the behavior depends on the specific library implementation. In some implementations, flushing a stream open for reading causes its input buffer to be cleared (but this is not portable expected behavior). The stream remains open after this call. When a file is closed, either because of a call to fclose or because the program terminates, all the buffers associated with it are automatically flushed.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
Returns:
int A zero value indicates success. If an error occurs, EOF is returned and the error indicator is set (see ferror).
void GD_clearerr ( GD_FILE filePointer)

Resets both the error and the eof indicators of the stream. When a i/o function fails either because of an error or because the end of the file has been reached, one of these internal indicators may be set for the stream. The state of these indicators is cleared by a call to this function, or by a call to any of: rewind, fseek, fsetpos and freopen.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
int GD_ferror ( GD_FILE filePointer)

Checks if the error indicator associated with stream is set, returning a value different from zero if it is. This indicator is generally set by a previous operation on the stream that failed, and is cleared by a call to clearerr, rewind or freopen.

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
Returns:
int A non-zero value is returned in the case that the error indicator associated with the stream is set. Otherwise, zero is returned.
int GD_mkdir ( const char *  dirname,
mode_t  mode 
)

The directory path is created at the path specified. The mode parameter is not used and exists here for compatability.

Parameters:
dirnameconst char* directory path to be created.
modemode not used (all directories are rwx)
Returns:
int
GD_DIR* GD_opendir ( const char *  dirname)

The opendir() function opens the directory named by dirname, associates a directory stream with it, and returns a pointer to be used to identify the directory stream in subsequent operations. The pointer NULL is returned if dirname cannot be accessed or if it cannot malloc(3) enough memory to hold the whole thing.

Parameters:
dirnamechar* string of the path to the directory.
Returns:
GD_DIR* object which represents the directory, NULL is returned in the case of an error.
int GD_closedir ( GD_DIR dirp)

The closedir() function closes the named directory stream and frees the structure associated with the dirp pointer, returning 0 on success. On failure, -1 is returned and the global variable errno is set to indicate the error.

Parameters:
dirpGD_DIR* directory stream to close
Returns:
int 0 on success, -1 on failure
struct dirent* GD_readdir ( GD_DIR dirp) [read]

This function returns a pointer to the next directory entry. It returns NULL upon reaching the end of the directory or detecting an invalid seekdir() operation.

Parameters:
dirpdirp directory stream to read from.
Returns:
struct dirent* pointer to a directory entry or NULL if the end has been reached.
int GD_readdir_r ( GD_DIR dirp,
struct dirent *  entry,
struct dirent **  result 
)

This function provides the same functionality as GD_readdir(), but the caller must provide a directory entry buffer to store the results in.

If the read succeeds, result is pointed at the entry; upon reaching the end of the directory, result is set to NULL. readdir_r() returns 0 on success or an error number to indicate failure.

Parameters:
dirpGD_DIR* directory stream to use.
entrystruct dirent* caller provided buffer to store the directory entry.
resultstruct dirent** on sucess result is pointed to entry.
Returns:
int 0 on success, -1 on failure.
void GD_rewinddir ( GD_DIR dirp)

This function resets the position of the named directory stream to the beginning of the directory.

Parameters:
dirpGD_DIR* directory stream to use.
void GD_seekdir ( GD_DIR dirp,
long  loc 
)

This function sets the position of the next readdir() operation on the directory stream. The new position reverts to the one associated with the directory stream when the telldir() operation was performed.

Parameters:
dirpGD_DIR* directory stream to use.
loclong position to seek to.
long GD_telldir ( GD_DIR dirp)

This function returns the current location associated with the named directory stream. Values returned by this function are good only for the lifetime of the DIR pointer (e.g., dirp) from which they are derived. If the directory is closed and then reopened, prior values returned by a previous call will no longer be valid.

Parameters:
dirpGD_DIR* directory stream to use.
Returns:
long current location in the stream.
int GD_stat ( const char *  path,
struct stat *  buf 
)

This function returns information about the file at a specified path. Read, write or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable.

Parameters:
pathconst char* pointer to a C string containing the path to the file.
bufstruct stat* buffer in which to write the stat data.
Returns:
int 0 on success, -1 on failure.
int GD_statdir ( GD_DIR dirp,
const char *  name,
struct stat *  buf 
)
Parameters:
dirpGD_DIR* directory stream to use.
nameconst char* pointer to a C string containing the name to the file or directory.
bufstruct stat* buffer in which to write the stat data.
Returns:
int 0 on success, -1 on failure.
int GD_getc ( GD_FILE filePointer)

Returns the character currently pointed by the internal file position indicator of the specified stream. The internal file position indicator is then advanced to the next character. If the stream is at the end-of-file when called, the function returns EOF and sets the end-of-file indicator for the stream (feof). If a read error occurs, the function returns EOF and sets the error indicator for the stream (ferror).

Parameters:
filePointerGD_FILE* object which was returned by a previous call to GD_fopen.
Returns:
int On success, the character read is returned (promoted to an int value). The return type is int to accommodate for the special value EOF, which indicates failure: If the position indicator was at the end-of-file, the function returns EOF and sets the eof indicator (feof) of stream. If some other reading error happens, the function also returns EOF, but sets its error indicator (ferror) instead.
int GD_ungetc ( int  character,
GD_FILE filePointer 
)

This function pushes the character c (converted to an unsigned char) back onto the specified input stream. The pushed-back character will be returned (in reverse order) by subsequent reads on the stream. A successful intervening call to one of the file positioning functions using the same stream, will discard the pushed-back characters.

Returns:
The GD_ungetc function returns the character pushed-back after the conversion, or EOF if the operation fails. If the value of the argument c character equals EOF, the operation will fail and the stream will remain unchanged.
struct hostent* GD_gethostbyname ( const char *  name) [read]
int GD_getaddrinfo ( const char *  node,
const char *  service,
const struct addrinfo *  hints,
struct addrinfo **  addresses 
)
int GD_freeaddrinfo ( struct addrinfo *  ai)
int GD_getnameinfo ( const struct sockaddr *  address,
socklen_t  addressLength,
char *  node,
size_t  nodeLength,
char *  service,
size_t  serviceLength,
int  flags 
)
enum GD_ROUTE GD_getRouteInfo ( const struct sockaddr *  address)

Call this function to check how a connection would be routed, either via the BlackBerry Dynamics infrastructure, direct to the Internet or Denied. The connection is specified by a socket address, sockaddr, structure that is passed as an input parameter. This route check compares the host name to the Connectivity Profile entries to determine routing.

The input socket address structure must have been obtained from the GD_getaddrinfo function.

Parameters:
addresspointer to a sockaddr structure for the required connection.
Returns:
GD_ROUTE constant for the result.
void GD_nslookup ( const char *  host,
GD_nslookup_type  type,
nslookupCompletionCallback  callback 
)

Call this function to execute a BlackBerry Dynamics name service lookup. The lookup can be for canonical name (CNAME) or address record (A record).

The lookup will be executed from an enterprise end point of the BlackBerry Dynamics deployment to which the application is connected. The end point could be a BlackBerry Proxy server located behind the enterprise firewall or in its perimeter network (also known as DMZ, demilitarized zone, and screened subnet). Details for enterprise application servers could be in scope of the lookup, depending on the network configuration at the enterprise.

The lookup is asynchronous. When the lookup completes, a completion callback will be invoked. The callback will be passed a char* pointer to memory containing the results represented as a JSON string, if the lookup was successful. If the specified host is not listed for client connection in the enterprise management console, then an empty string is passed to the callback instead. If an error occurred, then NULL is passed.

Parameters:
hostchar* pointer to memory containing the name to look up.
typeGD_nslookup_type specifying the type of result required, either CNAME or A record.
callbackfunction to execute when the lookup completes. The function receives one parameter as described above.
void GD_nslookupEx ( const char *  host,
GD_nslookup_type  type,
nslookupCompletionCallbackEx  callback,
const void *  data 
)

Call this function to execute a BlackBerry Dynamics name service lookup and supply extended data to the results callback. This function does the same lookup as the GD_nslookup() function, see above.

The completion callback will receive extended data, which is passed as a parameter to this function.

Parameters:
hostchar* pointer to memory containing the name to look up.
typeGD_nslookup_type specifying the type of result required, either CNAME or A record.
callbackfunction to execute when the lookup completes. The function receives a response parameter, as described above under GD_nslookup(), and extended data, as passed in the data parameter, below.
datavoid* pointer to the extended data for the callback.
char* GD_getFqdn ( const char *  host)

Call this function to retrieve a fully qualified domain name (FQDN) for a specified host server. An FQDN will be available after a successful socket connection has been made to the server.

The host specifier passed to this function must be the same as was used when the socket connection was set up. The returned value will be the FQDN to which the host specifier resolved at set-up time.

The returned value, if any, will be a pointer to memory that has been allocated from the heap using malloc. The caller must release the memory, by calling free.

Parameters:
hostchar* pointer to memory containing the specifier for the server.
Returns:
char* pointer to allocated memory containing the FQDN, or NULL if an FQDN isn't available.
void GD_myipaddress ( const char *  host,
unsigned int  port,
completionCallback  callback 
)

Call this function to retrieve the IP address of the BlackBerry Dynamics end point for a specified host.

Only hosts that are listed for client connection in the enterprise management console will have a BlackBerry Dynamics end point. The end point could be a BlackBerry Proxy server, or legacy Good Proxy server, for example.

Retrieval is asynchronous. When retrieval completes, a completion callback will be invoked.
The callback will be passed a char * pointing to a buffer containing the IP address if retrieval was successful. The callback must copy the contents of the buffer if the IP address is to be used later. The memory for the passed buffer will be released when the callback completes.
If the specified host isn't listed for client connection in the management console then an empty string is passed to the callback instead. If an error occurred then NULL is passed.

Parameters:
hostchar * containing the server address of the host.
portunsigned int containing the port number of the host.
callbackFunction to execute when the retrieval completes. The function receives one parameter as described above.
void GD_myipaddressEx ( const char *  host,
unsigned int  port,
completionCallbackEx  callback,
const void *  data 
)

Call this function to retrieve the IP address of the BlackBerry Dynamics end point for a specified host and supply extended data to the results callback. This function does the same retrieval as the GD_myipaddress() function, see above.

The completion callback will receive extended data, which is passed as a parameter to this function.

Parameters:
hostchar * containing the server address of the host.
portunsigned int containing the port number of the host.
callbackFunction to execute when the retrieval completes. The function receives a results parameter, as described above under GD_myipaddress(), and extended data, as passed in the data parameter, below.
datavoid * pointer to the extended data for the callback.
int GD_UNISTD_lstat ( const char *  path,
struct stat *  buf 
)

This function returns information about the file at a specified path. Read, write or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. GD_UNISTD_lstat() is identical to GD_stat(), except that if path is a symbolic link, then the link itself is stat-ed, not the file that it refers to.

Parameters:
pathconst char* pointer to a C string containing the path to the file.
bufstruct stat* buffer in which to write the stat data.
Returns:
int 0 on success, -1 on failure.
int GD_accept ( int  ,
struct sockaddr *__restrict  addr,
socklen_t *__restrict  addrlen 
)
int GD_bind ( int  ,
const struct sockaddr *  ,
socklen_t   
)
int GD_connect ( int  ,
const struct sockaddr *  ,
socklen_t   
)
int GD_getpeername ( int  ,
struct sockaddr *  __restrict,
socklen_t *  __restrict 
)
int GD_getsockname ( int  ,
struct sockaddr *  __restrict,
socklen_t *  __restrict 
)
int GD_getsockopt ( int  ,
int  ,
int  ,
void *  __restrict,
socklen_t *  __restrict 
)
int GD_listen ( int  ,
int   
)
ssize_t GD_recv ( int  ,
void *  ,
size_t  ,
int   
)
ssize_t GD_recvfrom ( int  ,
void *  ,
size_t  ,
int  ,
struct sockaddr *  __restrict,
socklen_t *  __restrict 
)
ssize_t GD_recvmsg ( int  ,
struct msghdr *  ,
int   
)
ssize_t GD_send ( int  ,
const void *  ,
size_t  ,
int   
)
ssize_t GD_sendmsg ( int  ,
const struct msghdr *  ,
int   
)
ssize_t GD_sendto ( int  ,
const void *  ,
size_t  ,
int  ,
const struct sockaddr *  ,
socklen_t   
)
int GD_setsockopt ( int  ,
int  ,
int  ,
const void *  ,
socklen_t   
)
int GD_shutdown ( int  ,
int   
)
int GD_sockatmark ( int  )
int GD_socket ( int  ,
int  ,
int   
)
int GD_socketpair ( int  ,
int  ,
int  ,
int *   
)
int GD_ioctlsocket ( int  ,
long  ,
unsigned long *   
)
int GD_gethostname ( char *  name,
size_t  len 
)
int GD_select ( int  ,
fd_set *  ,
fd_set *  ,
fd_set *  ,
struct timeval *   
)
int GD_UNISTD_fstat ( int  fd,
struct stat *  buf 
)

This function returns information about the file at a specified path. Read, write or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. GD_UNISTD_fstat() is identical to GD_stat(), except that the file to be stat-ed is specified by the file descriptor fd.

Parameters:
fdint file descriptor which specifies file to be stat-ed.
bufstruct stat* buffer in which to write the stat data.
Returns:
int 0 on success, -1 on failure.
ssize_t GD_readv ( int  ,
const struct iovec *  ,
int   
)
ssize_t GD_writev ( int  ,
const struct iovec *  ,
int   
)
int GD_UNISTD_open ( const char *  path,
int  mode,
  ... 
)
int GD_UNISTD_close ( int  fd)
ssize_t GD_UNISTD_read ( int  fd,
void *  buffer,
size_t  nbytes 
)
ssize_t GD_UNISTD_write ( int  fd,
const void *  buffer,
size_t  nbytes 
)
off_t GD_UNISTD_lseek ( int  fd,
off_t  offset,
int  whence 
)
int GD_UNISTD_ftruncate ( int  fd,
off_t  length 
)
int GD_UNISTD_truncate ( const char *  path,
off_t  length 
)
int GD_UNISTD_fdatasync ( int  fd)
int GD_UNISTD_fsync ( int  fd)
int GD_UNISTD_fchown ( int  fd,
uid_t  owner,
gid_t  group 
)
int GD_UNISTD_chown ( const char *  path,
uid_t  owner,
gid_t  group 
)
int GD_UNISTD_lchown ( const char *  path,
uid_t  owner,
gid_t  group 
)
int GD_UNISTD_chroot ( const char *  path)
int GD_UNISTD_fchdir ( int  fd)
int GD_UNISTD_chdir ( const char *  path)
char* GD_UNISTD_getcwd ( char *  buf,
size_t  size 
)
int GD_UNISTD_rmdir ( const char *  path)
int GD_UNISTD_access ( const char *  path,
int  mode 
)
long int GD_UNISTD_fpathconf ( int  fd,
int  name 
)
long int GD_UNISTD_pathconf ( const char *  path,
int  name 
)
int GD_UNISTD_lockf ( int  fd,
int  function,
off_t  size 
)
char* GD_UNISTD_ttyname ( int  fd)
int GD_UNISTD_ttyname_r ( int  fd,
char *  name,
size_t  namesize 
)
int GD_UNISTD_pipe ( int  fds[2])
ssize_t GD_UNISTD_pread ( int  fd,
void *  buffer,
size_t  nbyte,
off_t  offset 
)
ssize_t GD_UNISTD_pwrite ( int  fd,
const void *  buffer,
size_t  nbyte,
off_t  offset 
)
ssize_t GD_UNISTD_writev ( int  fd,
const struct iovec *  iov,
int  iovcnt 
)
ssize_t GD_UNISTD_readv ( int  fd,
const struct iovec *  iov,
int  iovcnt 
)
int GD_UNISTD_dup ( int  oldd)
int GD_UNISTD_dup2 ( int  oldd,
int  newd 
)
int GD_UNISTD_symlink ( const char *  file_path,
const char *  symlink_path 
)
int GD_UNISTD_readlink ( const char *  path,
char *  buffer,
size_t  nbyte 
)
int GD_UNISTD_link ( const char *  file_path,
const char *  link_path 
)
int GD_UNISTD_unlink ( const char *  path)
void* GD_UNISTD_mmap ( void *  addr,
size_t  length,
int  prot,
int  flags,
int  fd,
off_t  offset 
)
int GD_UNISTD_munmap ( void *  addr,
size_t  length 
)
int GD_UNISTD_msync ( void *  addr,
size_t  length,
int  flags 
)
int GD_UNISTD_fchmod ( int  fildes,
mode_t  mode 
)
int GD_UNISTD_fstatfs ( int  fd,
struct statfs *  buf 
)

C API.

int GD_UNISTD_utimes ( int  fd,
const struct utimbuf *  times 
)