ThingWorx C SDK
Classes | Macros | 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  twFileManager
 File Manager singleton structure definition. More...
 
struct  twFileTransferInfo
 File Transfer Information structure definition. More...
 
struct  twFile
 File/directory data structure. More...
 

Macros

#define TW_FAKE_TID   "XXXXXX"
 
#define TW_FAKE_TID_LEN   6
 
#define TW_FAKE_THINGNAME   "XXXXX"
 
#define TW_FAKE_THINGNAME_LEN   5
 

Typedefs

typedef struct twFileManager twFileManager
 File Manager singleton structure definition.
 
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...
 
char twFileManager_IsEnabled ()
 returns whether the twFileManager singleton is enabled based off of its pointer value 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...
 
enum msgCodeEnum twFileManager_GetFileChecksum (const char *entityName, twInfoTable **content, const char *realPath, const char *adjustedPath)
 Get the MD5 checksum of a file. 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...
 
enum msgCodeEnum twFileManager_FinishFileTransfer (const char *entityName, twFileTransferInfo *ft, const char *path, const char *adjustedPath)
 Completes the specified file transfer based on the content of job, invoking any file callbacks and closing the open file. 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...
 
TW_FILE_HANDLE twFile_FOpen (const char *name, const char *mode)
 

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.
enum msgCodeEnum twFileManager_FinishFileTransfer ( const char *  entityName,
twFileTransferInfo ft,
const char *  path,
const char *  adjustedPath 
)

Completes the specified file transfer based on the content of job, invoking any file callbacks and closing the open file.

Parameters
[in]entityNameThe entity name to use when looking up a virtual directory path.
[in]ftPopulated twFileTransferInfo structure
[in]pathPath to the file
[in]adjustedPathCleaned up path to the file (see adjustPath()) match the mask.
Returns
TWX_SUCCESS if files are cleaned up, TWX_INTERNAL_SERVER_ERROR if no matching open files can be found.
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]timeoutTime (in milliseconds) to wait for a response from the ThingWorx server. 0 uses DEFAULT_MESSAGE_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()).
enum msgCodeEnum twFileManager_GetFileChecksum ( const char *  entityName,
twInfoTable **  content,
const char *  realPath,
const char *  adjustedPath 
)

Get the MD5 checksum of a file.

Parameters
[in]entityNameThe entity name associated with the target file.
[in]contentData to create the result infotable around.
[in]realPathThe native filesystem path to this file.
[in]adjustedPathCleaned up path to the file (see adjustPath()) to match the mask.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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.
char twFileManager_IsEnabled ( )

returns whether the twFileManager singleton is enabled based off of its pointer value

Returns
TRUE is enabled, FALSE if not enabled
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]timeoutTime (in milliseconds) to wait for a response from the ThingWorx server. 0 uses DEFAULT_MESSAGE_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()).
In a single-threaded environment, this function must be invoked asynchronously.
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.