ThingWorx C SDK
Classes | Typedefs | Functions
twFileManager.h File Reference

ThingWorx file transfer structure definitions and functions. More...

#include "twOSPort.h"
#include "twDefinitions.h"
#include "twDefaultSettings.h"
#include "twList.h"
#include "twInfoTable.h"

Go to the source code of this file.

Classes

struct  twFileTransferInfo
 File Transfer Information structure definition. More...
 
struct  twFile
 File/directory data structure. More...
 

Typedefs

typedef struct twFileTransferInfo twFileTransferInfo
 File Transfer Information structure definition.
 
typedef void(* file_cb) (char fileRcvd, twFileTransferInfo *info, void *userdata)
 Signature of a callback function that is registered to be called when a file transfer completes or fails. More...
 
typedef struct twFile twFile
 File/directory data structure.
 

Functions

twFileTransferInfotwFileTransferInfo_Create (twInfoTable *it)
 Creates a new twFileTransferInfo structure. More...
 
void twFileTransferInfo_Delete (void *transferInfo)
 Frees all memory associated with a twFileTransferInfo structure and all its owned substructures. More...
 
int twFileManager_Create ()
 Creates the twFileManager singleton. More...
 
int twFileManager_Delete ()
 Deletes the twFileManager singleton and all its owned substructures. More...
 
int twFileManager_AddVirtualDir (const char *thingName, char *dirName, char *path)
 Adds a virtual directory to the twFileManager singleton. More...
 
int twFileManager_RemoveVirtualDir (const char *thingName, char *dirName)
 Removes a virtual directory from the twFileManager singleton. More...
 
twListtwFileManager_ListVirtualDirs (const char *entityName)
 Returns a list of all virtual directories from the twFileManager singleton. More...
 
twFiletwFileManager_OpenFile (const char *thingName, const char *path, const char *filename, char *mode)
 Creates a new twFile structure and populates it with information obtained from a file/directory. More...
 
void twFileManager_CloseFile (void *file)
 Closes a file and frees all memory associated with the twFile structure. More...
 
twFiletwFileManager_GetOpenFile (const char *thingName, const char *path, const char *filename, const char *tid, char *isTimedOut)
 Checks to see if the specified file is already open. More...
 
char * twFileManager_GetRealPath (const char *thingName, const char *path, const char *filename)
 Gets the native file system path for a file. More...
 
void twFileManager_MakeFileCallback (char rcvd, twFileTransferInfo *fti)
 Forces the file to complete a callback. More...
 
int twFileManager_RegisterFileCallback (file_cb cb, char *filter, char onceOnly, void *userdata)
 Registers a function to be called when a file transfer completes. More...
 
int twFileManager_UnregisterFileCallback (file_cb cb, char *filter, void *userdata)
 Unregisters a file callback function registered via twFileManager_RegisterFileCallback(). More...
 
int twFileManager_SendFile (const char *sourceRepo, const char *sourcePath, const char *sourceFile, const char *targetRepo, const char *targetPath, const char *targetFile, uint32_t timeout, char asynch, char **tid)
 
int twFileManager_GetFile (const char *sourceRepo, const char *sourcePath, const char *sourceFile, const char *targetRepo, const char *targetPath, const char *targetFile, uint32_t timeout, char asynch, char **tid)
 Gets a file from the server. More...
 
void twFileManager_CheckStalledTransfers ()
 Checks for any stalled file transfers and deletes them. More...
 
twListtwFileManager_ListEntities (const char *entityName, const char *path, const char *namemask, char returnType)
 Lists the files or subdirectories in a directory path. More...
 
void twFile_SetIsInUse (twFile *file, const char isInUse)
 uses the file->inUseMutex to safely set file->isInUse to the value of the isInUse parameter More...
 
twFiletwFile_Create ()
 allocates memory for the twFile and initializes the twFile->inUseMutex More...
 
void twFile_Delete (void *f)
 Deletes mutex's, file handles, and Free's memory realted to the twFile struct. More...
 

Detailed Description

ThingWorx file transfer structure definitions and functions.

Contains structure type definitions and function prototypes for ThingWorx API file transfer operations.

Typedef Documentation

typedef void(* file_cb) (char fileRcvd, twFileTransferInfo *info, void *userdata)

Signature of a callback function that is registered to be called when a file transfer completes or fails.

Parameters
[in]fileRcvd#TRUE if the file was received, #FALSE if it was sent.
[in]infoA pointer to the twFileTransferInfo associated with the callback.
[in]userdataAn opaque pointer that is passed in when the callback is registered.
Returns
Nothing.

Function Documentation

twFile* twFile_Create ( )

allocates memory for the twFile and initializes the twFile->inUseMutex

Returns
a valid pointer to a twFile struct or NULL if there was a failure
void twFile_Delete ( void *  f)

Deletes mutex's, file handles, and Free's memory realted to the twFile struct.

Parameters
[in]fileThe twFile to be deleted
void twFile_SetIsInUse ( twFile file,
const char  isInUse 
)

uses the file->inUseMutex to safely set file->isInUse to the value of the isInUse parameter

Parameters
[in]fileThe twFile to be modified
[in]pathboolean value to use for file->isInUse
int twFileManager_AddVirtualDir ( const char *  thingName,
char *  dirName,
char *  path 
)

Adds a virtual directory to the twFileManager singleton.

Parameters
[in]thingNameThe name of the ::twThing that this virtual directory is associated with.
[in]dirNameA name to apply to this virtual directory.
[in]pathThe absolute path to the underlying directory in the filesystem.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
A named virtual directory is associated with a specific ::twThing and has a specific path in the underlying filesystem. There can be more than one virtual directory assigned to a single ::twThing.
void twFileManager_CheckStalledTransfers ( )

Checks for any stalled file transfers and deletes them.

Returns
Nothing.
void twFileManager_CloseFile ( void *  file)

Closes a file and frees all memory associated with the twFile structure.

Parameters
[in]fA pointer to the twFile to close.
Returns
Nothing.
int twFileManager_Create ( )

Creates the twFileManager singleton.

Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The twFileManager singleton must be freed via twFileManager_Delete().
int twFileManager_Delete ( )

Deletes the twFileManager singleton and all its owned substructures.

Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twFileManager_GetFile ( const char *  sourceRepo,
const char *  sourcePath,
const char *  sourceFile,
const char *  targetRepo,
const char *  targetPath,
const char *  targetFile,
uint32_t  timeout,
char  asynch,
char **  tid 
)

Gets a file from the server.

Parameters
[in]sourceRepoThe entity name to get the file from.
[in]sourcePathThe virtual path of the file to get (not including the file name).
[in]sourceFileThe name of the file to get.
[in]targetRepoThe target repository of the file.
[in]targetPathThe path of the resulting file in the target repository (not including the file name).
[in]targetFileThe name of the resulting file in the target directory.
[in]timeoutThe timeout for the transfer in seconds. Zero will use the system's default timeout.
[in]asynchIf #TRUE return immediately and call the callback function when the transfer completes. If #FALSE block until the transfer is complete.
[out]tidA pointer to the transfer ID used for this transfer.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The callback will be called for synchronous or asynchronous transactions.
The calling function is responsible for registering/unregistering callback functions (see twFileManager_RegisterFilecallback() and twFileManager_UnregisterFileCallback()).
twFile* twFileManager_GetOpenFile ( const char *  thingName,
const char *  path,
const char *  filename,
const char *  tid,
char *  isTimedOut 
)

Checks to see if the specified file is already open.

Parameters
[in]thingNameThe name of the ::twThing this file is associated with.
[in]pathThe full path to the file or directory. May be passed as NULL if tid is specified.
[in]filenameThe name of the file or directory.
[in]tidThe tid of an open transaction. May be passed as NULL if path is specified.
[out]isTimedOutpointer to boolean which will signal if the specified file has timed out, NULL can be passed in if the calling funciton does not care about this value
Returns
A pointer to the twFile associated with the file or directory if it is already open. NULL if the file is not open or an error was encountered.
char* twFileManager_GetRealPath ( const char *  thingName,
const char *  path,
const char *  filename 
)

Gets the native file system path for a file.

Parameters
[in]thingNameThe name of the ::twThing this file is associated with.
[in]pathThe virtual path of the file.
[in]filenameThe name of the file. Passing NULL will assume file name is already appended to path.
Returns
The native filesystem path to this file.
Note
The calling function gains ownership of the returned pointer and is responsible for freeing it.
twList* twFileManager_ListEntities ( const char *  entityName,
const char *  path,
const char *  namemask,
char  returnType 
)

Lists the files or subdirectories in a directory path.

Parameters
[in]entityNameThe entity name to use when looking up a virtual directory path.
[in]pathThe virtual path to the directory to investigate.
[in]namemaskA wildcard enabled mask to list only files that match the mask.
[in]returnType#LIST_ALL returns all files and directories, #LIST_FILES returns files only, #LIST_DIRS returns directories only.
Returns
A twList of twFile pointers representing all requested items within the given path. Returns if an error was encountered.
Note
The calling function gains ownership of the returned twList and is responsible for freeing it via twList_Delete().
twList* twFileManager_ListVirtualDirs ( const char *  entityName)

Returns a list of all virtual directories from the twFileManager singleton.

Parameters
[in]entityNameA filter on virtual directories registered with a given entity name (NULL returns all virtual directories).
Returns
A pointer to a twList of twFile pointers representing the virtual directories. Returns 0 if an error was encountered.
Note
The calling function will gain ownership of the returned twList and is responsible for deleting it via twList_Delete().
void twFileManager_MakeFileCallback ( char  rcvd,
twFileTransferInfo fti 
)

Forces the file to complete a callback.

Parameters
[in]rcvdTRUE if the file was received, FALSE if it was sent.
[in]ftiA pointer to the twFileTransferInfo structure.
Returns
Nothing.
twFile* twFileManager_OpenFile ( const char *  thingName,
const char *  path,
const char *  filename,
char *  mode 
)

Creates a new twFile structure and populates it with information obtained from a file/directory.

Parameters
[in]thingNameThe name of the ::twThing this file is associated with.
[in]pathVirtual path to the file or directory.
[in]filenameThe name of the file or directory.
[in]modeThe mode to open the file in (see Cfopen() documentation).
Returns
A pointer to the newly allocated twFile structure. Returns NULL if an error was encountered.
Note
The function will check to make sure the path is valid (either in the root or a virtual directory).
The function will open the file to provide an OS specific reference or handle for any I/O.
The calling function gains ownership of the returned twFile structure and is responsible for deleting it via twFileManager_CloseFile().
int twFileManager_RegisterFileCallback ( file_cb  cb,
char *  filter,
char  onceOnly,
void *  userdata 
)

Registers a function to be called when a file transfer completes.

Parameters
[in]cbThe function to be registered.
[in]filterA wildcard-supporting filter to apply to the filename of transfers to be associated with the callback.
[in]onceOnlyIf #TRUE, this registration will be deleted after it is called once.
[in]userdataAn opaque pointer that is passed in when the callback is registered.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twFileManager_RemoveVirtualDir ( const char *  thingName,
char *  dirName 
)

Removes a virtual directory from the twFileManager singleton.

Parameters
[in]thingNameThe name of the ::twThing that this virtual directory is associated with.
[in]dirNameThe name of the virtual directory to remove ("*" removes all associated with thingName).
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twFileManager_SendFile ( const char *  sourceRepo,
const char *  sourcePath,
const char *  sourceFile,
const char *  targetRepo,
const char *  targetPath,
const char *  targetFile,
uint32_t  timeout,
char  asynch,
char **  tid 
)
Parameters
Sendsa file to the server.
[in]sourceRepoThe entity name to use when sending the file (and looking up the virtual path).
[in]sourcePathThe virtual path of the file to send (not including the file name).
[in]sourceFileThe name of the file to send.
[in]targetRepoThe target repository of the file.
[in]targetPathThe path of the resulting file in the target repository (not including the file name).
[in]targetFileThe name of the resulting file in the target directory.
[in]timeoutThe timeout for the transfer in seconds. Zero will use the system's default timeout.
[in]asynchIf #TRUE return immediately and call the callback function when the transfer completes. If #FALSE block until the transfer is complete.
[out]tidA pointer to the transfer ID used for this transfer.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The callback will be called for synchronous or asynchronous transactions.
The calling function is responsible for registering/unregistering callback functions (see twFileManager_RegisterFilecallback() and twFileManager_UnregisterFileCallback()).
int twFileManager_UnregisterFileCallback ( file_cb  cb,
char *  filter,
void *  userdata 
)

Unregisters a file callback function registered via twFileManager_RegisterFileCallback().

Parameters
[in]cbThe function to be unregistered.
[in]filterA wildcard-supporting filter to apply to the filename of transfers to be unregistered.
[in]userdataAn opaque pointer that is passed in when the callback is registered.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
twFileTransferInfo* twFileTransferInfo_Create ( twInfoTable it)

Creates a new twFileTransferInfo structure.

Parameters
[in]itA twInfoTable containing all file transfer information for the new twFileTransferInfo structure.
Returns
A pointer to the newly allocated twFileTransferInfo structure.
Note
The calling function retains ownership of the it pointer.
The calling function gains ownership of the returned twFileTransferInfo structure and is responsible for freeing it via twFileTransferInfo_Delete().
void twFileTransferInfo_Delete ( void *  transferInfo)

Frees all memory associated with a twFileTransferInfo structure and all its owned substructures.

Parameters
[in]transferInfoA pointer to the twFileTransferInfo structure to delete.
Returns
Nothing.