tp_c.h File Reference

#include "defs.h"

Go to the source code of this file.

Classes

struct  _metadata_t
struct  _artistresult_t
struct  _albumresult_t
struct  _albumtrackresult_t

Defines

#define TP_EXTENSION_LEN   32

Typedefs

typedef void * tunepimp_t
typedef void * track_t
typedef void * result_t
typedef void(* tp_notify_callback )(tunepimp_t pimp, void *data, TPCallbackEnum type, int fileId)
typedef void(* tp_status_callback )(tunepimp_t pimp, void *data, const char *status)
typedef _metadata_t metadata_t
typedef _artistresult_t artistresult_t
typedef _albumresult_t albumresult_t
typedef _albumtrackresult_t albumtrackresult_t

Functions

tunepimp_t tp_New (const char *appName, const char *appVersion)
tunepimp_t tp_NewWithArgs (const char *appName, const char *appVersion, int startThreads)
void tp_Delete (tunepimp_t o)
void tp_GetVersion (tunepimp_t o, int *major, int *minor, int *rev)
void tp_SetUserInfo (tunepimp_t o, const char *userName, const char *password)
void tp_GetUserInfo (tunepimp_t o, char *userName, int maxUserNameLen, char *password, int maxPasswordLen)
void tp_SetUseUTF8 (tunepimp_t o, int useUTF8)
int tp_GetUseUTF8 (tunepimp_t o)
void tp_SetServer (tunepimp_t o, const char *serverAddr, short serverPort)
void tp_GetServer (tunepimp_t o, char *serverAddr, int maxLen, short *serverPort)
void tp_SetProxy (tunepimp_t o, const char *serverAddr, short serverPort)
void tp_GetProxy (tunepimp_t o, char *serverAddr, int maxLen, short *serverPort)
int tp_GetNumSupportedExtensions (tunepimp_t o)
void tp_GetSupportedExtensions (tunepimp_t o, char extensions[][TP_EXTENSION_LEN])
void tp_SetAnalyzerPriority (tunepimp_t o, TPThreadPriorityEnum priority)
TPThreadPriorityEnum tp_GetAnalyzerPriority (tunepimp_t o)
void tp_SetAutoFileLookup (tunepimp_t o, int enable)
int tp_GetAutoFileLookup (tunepimp_t o)
void tp_SetNotifyCallback (tunepimp_t o, tp_notify_callback callback, void *data)
tp_notify_callback tp_GetNotifyCallback (tunepimp_t o)
int tp_GetNotification (tunepimp_t o, TPCallbackEnum *type, int *fileId)
void tp_SetStatusCallback (tunepimp_t o, tp_status_callback callback, void *data)
int tp_GetStatus (tunepimp_t o, char *status, int statusLen)
tp_status_callback tp_GetStatusCallback (tunepimp_t o)
void tp_GetError (tunepimp_t o, char *error, int maxLen)
void tp_SetDebug (tunepimp_t o, int debug)
int tp_GetDebug (tunepimp_t o)
int tp_AddFile (tunepimp_t o, const char *fileName)
int tp_AddDir (tunepimp_t o, const char *dirPath)
void tp_Remove (tunepimp_t o, int fileId)
int tp_GetNumFiles (tunepimp_t o)
int tp_GetNumUnsubmitted (tunepimp_t o)
int tp_GetNumUnsavedItems (tunepimp_t o)
int tp_GetTrackCounts (tunepimp_t o, int *counts, int maxCounts)
int tp_GetNumFileIds (tunepimp_t o)
void tp_GetFileIds (tunepimp_t o, int *ids, int numIds)
track_t tp_GetTrack (tunepimp_t o, int fileId)
void tp_ReleaseTrack (tunepimp_t o, track_t track)
void tp_Wake (tunepimp_t o, track_t track)
TPError tp_SelectResult (tunepimp_t o, track_t track, int resultIndex)
void tp_Misidentified (tunepimp_t o, int fileId)
void tp_IdentifyAgain (tunepimp_t o, int fileId)
int tp_WriteTags (tunepimp_t o, int *fileIds, int numFileIds)
void tp_AddTRMSubmission (tunepimp_t o, const char *trackId, const char *trmId)
TPError tp_SubmitTRMs (tunepimp_t o)
void tp_SetRenameFiles (tunepimp_t o, int rename)
int tp_GetRenameFiles (tunepimp_t o)
void tp_SetMoveFiles (tunepimp_t o, int move)
int tp_GetMoveFiles (tunepimp_t o)
void tp_SetWriteID3v1 (tunepimp_t o, int writeID3v1)
int tp_GetWriteID3v1 (tunepimp_t o)
void tp_SetClearTags (tunepimp_t o, int clearTags)
int tp_GetClearTags (tunepimp_t o)
void tp_SetFileMask (tunepimp_t o, const char *fileMask)
void tp_GetFileMask (tunepimp_t o, char *fileMask, int maxLen)
void tp_SetVariousFileMask (tunepimp_t o, const char *variousFileMask)
void tp_GetVariousFileMask (tunepimp_t o, char *variousFileMask, int maxLen)
void tp_SetAllowedFileCharacters (tunepimp_t o, const char *allowedFileCharacters)
void tp_GetAllowedFileCharacters (tunepimp_t o, char *allowedFileCharacters, int maxLen)
void tp_SetDestDir (tunepimp_t o, const char *destDir)
void tp_GetDestDir (tunepimp_t o, char *destDir, int maxLen)
void tp_SetTopSrcDir (tunepimp_t o, const char *topSrcDir)
void tp_GetTopSrcDir (tunepimp_t o, char *topSrcDir, int maxLen)
void tp_SetTRMCollisionThreshold (tunepimp_t o, int trmThreshold)
int tp_GetTRMCollisionThreshold (tunepimp_t o)
void tp_SetMinTRMThreshold (tunepimp_t o, int minThreshold)
int tp_GetMinTRMThreshold (tunepimp_t o)
void tp_SetAutoSaveThreshold (tunepimp_t o, int autoSaveThreshold)
int tp_GetAutoSaveThreshold (tunepimp_t o)
void tp_SetMaxFileNameLen (tunepimp_t o, int maxFileNameLen)
int tp_GetMaxFileNameLen (tunepimp_t o)
void tp_SetAutoRemovedSavedFiles (tunepimp_t o, int autoRemoveSavedFiles)
int tp_GetAutoRemovedSavedFiles (tunepimp_t o)
int tp_GetRecognizedFileList (tunepimp_t o, int threshold, int **fileIds, int *numIds)
void tp_DeleteRecognizedFileList (tunepimp_t o, int *fileIds)
TPFileStatus tr_GetStatus (track_t t)
void tr_SetStatus (track_t t, const TPFileStatus status)
void tr_GetFileName (track_t t, char *fileName, int maxLen)
void tr_GetTRM (track_t t, char *trm, int maxLen)
void tr_GetLocalMetadata (track_t t, metadata_t *mdata)
void tr_SetLocalMetadata (track_t t, const metadata_t *mdata)
void tr_GetServerMetadata (track_t t, metadata_t *mdata)
void tr_SetServerMetadata (track_t t, const metadata_t *mdata)
void tr_GetError (track_t t, char *error, int maxLen)
int tr_GetSimilarity (track_t t)
int tr_HasChanged (track_t t)
int tr_GetNumResults (track_t t)
void tr_GetResults (track_t t, TPResultType *type, result_t *results, int *numResults)
void tr_Lock (track_t t)
void tr_Unlock (track_t t)
metadata_tmd_New (void)
void md_Delete (metadata_t *mdata)
void md_Clear (metadata_t *mdata)
TPAlbumStatus md_ConvertToAlbumStatus (const char *albumStatus)
TPAlbumType md_ConvertToAlbumType (const char *albumType)
void md_ConvertFromAlbumStatus (TPAlbumStatus status, char *albumStatus, int maxLen)
void md_ConvertFromAlbumType (TPAlbumType type, char *albumType, int maxLen)
void rs_Delete (TPResultType type, result_t *result, int numResults)


Define Documentation

#define TP_EXTENSION_LEN   32
 

This function returns a list of supported audio formats. The elements of the list are the usual filename extensions like ".wav", ".mp3", ".ogg" etc.

The buffer you pass to the function has to be big enough to hold the list. You can use tp_GetNumSupportedExtensions() to get the number of supported extensions.

Parameters:
o the tunepimp_t object returned from tp_New()
extensions a user supplied buffer for the list of filename extensions
See also:
tp_GetNumSupportedExtensions()


Typedef Documentation

typedef struct _albumresult_t albumresult_t
 

This structure contains information about an album.

As in artistresult_t, a higher relevance value indicates a better match. The artist attribute points to an artistresult_t structure.

typedef struct _albumtrackresult_t albumtrackresult_t
 

This structure represents a matched track.

A higher relevance value indicates a better match. Information about the track's artist and the album can be found in the artist and album attributes.

typedef struct _artistresult_t artistresult_t
 

This structure contains information about an artist.

The relevance attribute is an indication for the quality of the match. The higher the better.

typedef struct _metadata_t metadata_t
 

This structure holds the meta data of a track.

The meanings of most attributes are pretty straight forward, but a few need additional explanations. Strings like artist, sortName, album etc. are never NULL. If the information isn't available, the attribute is set to the empty string ("").

The duration attribute is in milliseconds. fileFormat is one of the supported file formats (see tp_GetSupportedExtensions()) but without the dot ("mp3", "ogg", "wav" etc.). If there was a TRM collision, numTRMIds is set to a value greater than one. If variousArtist is true, the track is from a various artists release.

The memory containing the meta data will be released when calling md_Clear() or md_Delete(), so you have to copy the data if you want to use it.

See also:
md_New(), md_Clear(), md_Delete() tr_GetLocalMetadata(), tr_SetLocalMetadata(), tr_GetServerMetadata(), tr_SetServerMetadata()

typedef void* result_t
 

The abstraction of a TPResult object. Such objects are returned by tr_GetResults(), but there are no functions that operate on them. You have to cast them to albumresult_t, artistresult_t or albumtrackresult_t, depending on the type of the result (which is also returned by tr_GetResults()).

typedef void(* tp_notify_callback)(tunepimp_t pimp, void *data, TPCallbackEnum type, int fileId)
 

This is the signature definition of a function suitable as a notification callback. The data argument is the pointer that the user gave when registering the function using tp_SetNotifyCallback().

Parameters:
pimp the tunepimp object that invoked the callback function
data a pointer to user data set when registering the callback
type the type of this notification
fileId the Id of the file concerned
See also:
tp_SetNotifyCallback()

typedef void(* tp_status_callback)(tunepimp_t pimp, void *data, const char *status)
 

This is the signature definition of a function suitable as a status callback. The data argument is the pointer that the user gave when registering the function using tp_SetStatusCallback().

Parameters:
pimp the tunepimp object that invoked the callback function
data a pointer to user data set when registering the callback
status a pointer to a text message
See also:
tp_SetStatusCallback()

typedef void* track_t
 

The abstraction of a Track object. Functions to manipulate have a prefix of "tr_".

typedef void* tunepimp_t
 

tunepimp_t is the basic C abstraction for a TunePimp Object. It is completely transparent for the user. Don't try to manipulate it manually, use one of the functions starting with "tp_".


Function Documentation

void md_Clear metadata_t mdata  ) 
 

Clears a metadata_t object.

All values of the object are set to NULL values. After that the object is in the same state as directly after md_New().

Parameters:
mdata a valid metadata_t object
See also:
md_New(), md_Delete()

void md_ConvertFromAlbumStatus TPAlbumStatus  status,
char *  albumStatus,
int  maxLen
 

Convert the status of an album to its textual representation. The function stores the status string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

Parameters:
status an album status
albumStatus a user supplied buffer of maxLen characters
maxLen the size of the buffer
See also:
md_ConvertToAlbumStatus()

void md_ConvertFromAlbumType TPAlbumType  type,
char *  albumType,
int  maxLen
 

Convert the type of an album to its textual representation. The function stores the type string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

Parameters:
type an album type
albumType a user supplied buffer of maxLen characters
maxLen the size of the buffer
See also:
md_ConvertToAlbumType()

TPAlbumStatus md_ConvertToAlbumStatus const char *  albumStatus  ) 
 

Converts a string to TPAlbumStatus. The string's value has to be one of "official", "promotion" or "bootleg". Case doesn't matter.

Parameters:
albumStatus the string to convert
Returns:
an album status or eAlbumStatus_Error on error
See also:
md_ConvertToAlbumType()

TPAlbumType md_ConvertToAlbumType const char *  albumType  ) 
 

Converts a string to TPAlbumType. The string's value has to be one of "album", "single", "compilation", "soundtrack", "spokenword", "audiobook", "live" or "other". Case doesn't matter.

Parameters:
albumType the string to convert
Returns:
an album type or eAlbumType_Error on error
See also:
md_ConvertToAlbumStatus()

void md_Delete metadata_t mdata  ) 
 

Delete a metadata_t object.

Parameters:
mdata a valid metadata_t object
See also:
md_Clear()

metadata_t* md_New void   ) 
 

Create a new metadata_t object.

Don't forget to release it using md_Delete() when you don't need it any longer.

Returns:
a new metadata_t object
See also:
md_Clear()

void rs_Delete TPResultType  type,
result_t result,
int  numResults
 

Releases the memory for a result list allocated by tr_GetResults()

Parameters:
type the type of the result
result the result pointer returned by tr_GetResults()
numResults the number of results
See also:
tr_GetResults(), rs_Delete()

int tp_AddDir tunepimp_t  o,
const char *  dirPath
 

This function descends recursively into the specified directory and adds all files to the list that look like they contain music, judging by comparing file extensions. You can get a list of supported file formats using tp_GetSupportedExtensions().

Parameters:
o the tunepimp_t object returned from tp_New
dirPath a string containing a path
Returns:
the number of files found, -1 on error
See also:
tp_Add(), tp_GetSupportedExtensions()

int tp_AddFile tunepimp_t  o,
const char *  fileName
 

Add a file to the list. The fileId of the added file is returned which is a handle that is valid until the file is removed using tp_Remove() or TunePimp writes new metadata tags and automatically removes the file. Adding a file that is already in the list is a no-op. Initially, the status of a file is ePending.

For each file added, your registered notification callback is invoked. Its parameters are tpFileAdded and the fileId returned by tp_Add().

Please note that tp_AddFile() always succeeds, no matter if the file isn't a recognized audio file, if it isn't readable or doesn't exist at all. However, you can always query the track's status to see if there was an error.

Parameters:
o the tunepimp_t object returned from tp_New
fileName a string containing a filename
Returns:
a fileId handle for your file
See also:
tp_AddDir(), tp_SetNotifyCallback()

void tp_AddTRMSubmission tunepimp_t  o,
const char *  trackId,
const char *  trmId
 

Add a (trackId, TRM) pair to the list of unsubmitted TRMs. You have to call tp_SubmitTRMs() to actually send it to the server.

Parameters:
o the tunepimp_t object returned from tp_New()
trackId a musicbrainz track Id
trmId a TRM Id in its ASCII representation
See also:
tp_SubmitTRMs()

void tp_Delete tunepimp_t  o  ) 
 

The destructor for the TunePimp class.

Parameters:
o the handle for the tunepimp_t object to delete
See also:
tp_New()

void tp_DeleteRecognizedFileList tunepimp_t  o,
int *  fileIds
 

Release the memory allocated by tp_GetRecognizedFileList(). You can use this function even if there were no fileIds returned.

Parameters:
o the tunepimp_t object returned from tp_New()
fileIds the array returned by tp_GetRecognizedFileList()
See also:
tp_GetRecognizedFileList()

void tp_GetAllowedFileCharacters tunepimp_t  o,
char *  allowedFileCharacters,
int  maxLen
 

Use this function to get a string containing the characters allowed in a file name. This function stores the string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

If all characters are allowed, the empty string ("") is returned.

Parameters:
o the tunepimp_t object returned from tp_New()
allowedFileCharacters a user supplied buffer of maxLen characters
maxLen the size of the buffer
See also:
tp_SetAllowedFileCharacters()

TPThreadPriorityEnum tp_GetAnalyzerPriority tunepimp_t  o  ) 
 

This function gets the analyzer thread priority level.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
The current analyzer thread priorty. See include/defs.h for possible return codes.
See also:
tp_SetAnalyzerPriority()

int tp_GetAutoFileLookup tunepimp_t  o  ) 
 

Query the status of the AutoFileLookup feature. See tp_SetAutoFileLookup() for further information.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
true if AutoFileLookup is enabled and false otherwise
See also:
tp_SetAutoFileLookup()

int tp_GetAutoRemovedSavedFiles tunepimp_t  o  ) 
 

Use this function to determine if the tunepimp library automatically deletes files after they've been saved or if it moves them to the eSaved status.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
if tunepimp is auto removing files
See also:
tp_SetAutoRemovedSavedFiles()

int tp_GetAutoSaveThreshold tunepimp_t  o  ) 
 

Get the autosave threshold if autosave is enabled or a negative value if the feature is disabled. See tp_SetAutoSaveThreshold() for an explanation of the autosave feature.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
the autosave threshold or a negative number of disabled
See also:
tp_SetAutoSaveThreshold()

int tp_GetClearTags tunepimp_t  o  ) 
 

Query the tunepimp object if tag clearing is enabled. See tp_SetClearTags() for more information.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
true if the tag clearing is enabled and false otherwise
See also:
tp_SetClearTags()

int tp_GetDebug tunepimp_t  o  ) 
 

Check if debugging is enabled.

Parameters:
o the tunepimp_t object returned from tp_New
Returns:
true if debuggin is enabled and false otherwise
See also:
tp_SetDebug()

void tp_GetDestDir tunepimp_t  o,
char *  destDir,
int  maxLen
 

Use this function to get a string containing the destination directory. tp_GetDestDir() stores the string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

Parameters:
o the tunepimp_t object returned from tp_New()
destDir a user supplied buffer of maxLen characters
maxLen the size of the buffer
See also:
tp_SetDestDir()

void tp_GetError tunepimp_t  o,
char *  error,
int  maxLen
 

Use this function to get a printable error message for the last error that occured in the tunepimp object. tp_GetError() stores the error string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

Parameters:
o the tunepimp_t object returned from tp_New()
error a user supplied buffer of maxLen characters
maxLen the size of the buffer

void tp_GetFileIds tunepimp_t  o,
int *  ids,
int  numIds
 

Returns the fileIds in tunepimp's list. At most numIds are returned.

Use tp_GetNumFileIds to get the number of fileIds in the list. Do not use tp_Add() or tp_AddDir() between calls to tp_GetNumFileIds() and tp_GetFileIds().

Parameters:
o the tunepimp_t object returned from tp_New()
numIds the number of fileIds the buffer can receive
ids a poiner to the buffer that will receive the fileIds
See also:
tp_GetNumFileIds()

void tp_GetFileMask tunepimp_t  o,
char *  fileMask,
int  maxLen
 

Use this function to get a string containing the file mask. tp_GetFileMask() stores the string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

Parameters:
o the tunepimp_t object returned from tp_New()
fileMask a user supplied buffer of maxLen characters
maxLen the size of the buffer
See also:
tp_SetFileMask()

int tp_GetMaxFileNameLen tunepimp_t  o  ) 
 

Use this function to get the current maximum filename length

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
the current maximum filename length
See also:
tp_SetMaxFileNameLen()

int tp_GetMinTRMThreshold tunepimp_t  o  ) 
 

Get the minimum TRM match threshold. The returned value is between 0 and 100. See tp_SetMinTRMThreshold() for a discussion.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
the TRM minimum threshold
See also:
tp_SetMinTRMThreshold()

int tp_GetMoveFiles tunepimp_t  o  ) 
 

Check if file moving is enabled. See tp_SetMoveFiles() for more information.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
true if file moving was enabled and false otherwise
See also:
tp_SetMoveFiles()

int tp_GetNotification tunepimp_t  o,
TPCallbackEnum type,
int *  fileId
 

Get a notification message from tunepimp's queue. All messages are stored in a queue (FIFO) to make sure you get them in the right order.

Please note that this function only returns notification messages if no notification callback was set.

Parameters:
o the tunepimp_t object returned from tp_New()
type the address of a variable to receive the notification type
fileId the address of a variable to receive the fileId
Returns:
true if there was a notification message in the queue and false otherwise
See also:
tp_SetNotifyCallback(), tp_GetNotifyCallback()

tp_notify_callback tp_GetNotifyCallback tunepimp_t  o  ) 
 

Get the function registered to receive notification messages. See tp_SetNotifyCallback() for more information.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
the previously registered callback or NULL if none was registered
See also:
tp_SetNotifyCallback()

int tp_GetNumFileIds tunepimp_t  o  ) 
 

Get the number of filesIds that a call to tp_GetFileIds() would return.

Do not use tp_Add() or tp_AddDir() between calls to tp_GetNumFileIds() and tp_GetFileIds(). They might increase the number of fileIds.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
the number of fileIds
See also:
tp_GetFileIds()

int tp_GetNumFiles tunepimp_t  o  ) 
 

This function returns the number of files that tunepimp has in its list.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
the number of files in the list
See also:
tp_Add(), tp_AddDir(), tp_Remove()

int tp_GetNumSupportedExtensions tunepimp_t  o  ) 
 

Query the number of audio file formats supported by tunepimp. The number depends on which libraries were present when tunepimp was compiled.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
the number of supported audio file formats
See also:
tp_GetSupportedExtensions()

int tp_GetNumUnsavedItems tunepimp_t  o  ) 
 

This function returns the number of track that have been recognized and are ready to be saved.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
the number of tracks not saved

int tp_GetNumUnsubmitted tunepimp_t  o  ) 
 

This function returns the number of TRMs that haven't been submitted to the server yet.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
the number of TRMs not yet submitted
See also:
tp_SubmitTRMs(), tp_SetUserInfo()

void tp_GetProxy tunepimp_t  o,
char *  serverAddr,
int  maxLen,
short *  serverPort
 

Get the proxy settings. tp_GetProxy() stores the address in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

If no proxy was set, serverAddr is set to the empty string ("").

Parameters:
o the tunepimp_t object returned from tp_New()
serverAddr a user supplied buffer of maxLen characters
maxLen the size of the buffer
serverPort the address of a variable to receive the port
See also:
tp_SetProxy()

int tp_GetRecognizedFileList tunepimp_t  o,
int  threshold,
int **  fileIds,
int *  numIds
 

Get a list of recognized files (eRecognized) that have a similarity value of less than threshold. If such files were found, the function allocates an array of ints and returns it using the fileIds argument. The number of entries in the array can be found in the numIds argument.

Don't forget to free the allocated memory using tp_DeleteRecognizedFileList().

Parameters:
o the tunepimp_t object returned from tp_New()
threshold a threshold (between 0 and 100)
fileIds the address of an int pointer
numIds the address of a variable to receive the number of IDs returned
Returns:
true if there were matching files and false otherwise
See also:
tp_DeleteRecognizedFileList()

int tp_GetRenameFiles tunepimp_t  o  ) 
 

Query the tunepimp object if file renaming is enabled. See tp_SetRenameFiles() for an explanation.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
true if file renaming was enabled and false otherwise
See also:
tp_SetRenameFiles()

void tp_GetServer tunepimp_t  o,
char *  serverAddr,
int  maxLen,
short *  serverPort
 

Get the server settings. tp_GetServer() stores the address in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

If no proxy was set, serverAddr is set to the empty string ("").

Parameters:
o the tunepimp_t object returned from tp_New()
serverAddr a user supplied buffer of maxLen characters
maxLen the size of the buffer
serverPort the address of a variable to receive the port
See also:
tp_SetServer()

int tp_GetStatus tunepimp_t  o,
char *  status,
int  statusLen
 

Get a status message from tunepimp's queue. All messages are stored in a queue (FIFO) to make sure you get them in the right order.

Please note that this function only returns status messages if no status callback was set.

Parameters:
o the tunepimp_t object returned from tp_New()
status a user supplied buffer of statusLen characters
statusLen the size of the buffer
Returns:
true if there was a status message in the queue and false otherwise
See also:
tp_SetStatusCallback(), tp_GetStatusCallback()

tp_status_callback tp_GetStatusCallback tunepimp_t  o  ) 
 

Get the function registered to receive status messages. See tp_SetStatusCallback() for more information.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
the previously registered callback or NULL if none was registered
See also:
tp_SetStatusCallback()

void tp_GetSupportedExtensions tunepimp_t  o,
char  extensions[][TP_EXTENSION_LEN]
 

void tp_GetTopSrcDir tunepimp_t  o,
char *  topSrcDir,
int  maxLen
 

Use this function to get the top source directory. See tp_SetTopSrcDir() for more information.

tp_GetTopSrcDir() stores the string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

Parameters:
o the tunepimp_t object returned from tp_New()
topSrcDir a user supplied buffer of maxLen characters
maxLen the size of the buffer
See also:
tp_SetTopSrcDir()

track_t tp_GetTrack tunepimp_t  o,
int  fileId
 

Get a handle for a track object. Don't forget to release the track using tp_ReleaseTrack() when you don't need it any longer. YOU MUST CALL tr_Lock() BEFORE YOU MAKE ANY CHANGES TO THE TRACK. After your changes are complete, call tr_Unlock.

Parameters:
o the tunepimp_t object returned from tp_New()
fileId a fileId
Returns:
a track handle or NULL if fileId isn't associated with a track
See also:
tp_ReleaseTrack(),

tr_Lock(),

tr_Unlock()

int tp_GetTrackCounts tunepimp_t  o,
int *  counts,
int  maxCounts
 

This function returns the number of tracks in each of the TPFileStatus categories. For example, the count for the number of unrecognized files will be stored in: counts[(int)eUnrecognized]

Parameters:
o the tunepimp_t object returned from tp_New()
counts a pointer to an array of ints that will receive the counts
maxCounts max number of counts that can be written to the counts array.

int tp_GetTRMCollisionThreshold tunepimp_t  o  ) 
 

Get the TRM collision threshold. The returned value is between 0 and 100. See tp_SetTRMCollisionThreshold() for a discussion.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
the TRM collision threshold
See also:
tp_SetTRMCollisionThreshold()

void tp_GetUserInfo tunepimp_t  o,
char *  userName,
int  maxUserNameLen,
char *  password,
int  maxPasswordLen
 

Get the user name and password. The data is stored in the user supplied buffers userName and password. Not more than maxUserNameLen and maxPasswordLen characters respectively including the trailing '\0' byte are copied into that buffer.

Parameters:
o the tunepimp_t object returned from tp_New()
userName a user supplied buffer of maxUserNameLen characters
maxUserNameLen Len the size of the buffer for the user name
password a user supplied buffer of maxPasswordLen characters
maxPasswordLen the size of the buffer for the password

int tp_GetUseUTF8 tunepimp_t  o  ) 
 

Use this function to check if tunepimp returns data in UTF-8 or in ISO-8859-1 (latin1).

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
true if tunepimp returns UTF-8 and false for ISO-8859-1 (latin1)
See also:
tp_SetUseUTF8()

void tp_GetVariousFileMask tunepimp_t  o,
char *  variousFileMask,
int  maxLen
 

Use this function to get a string containing the various artists file mask. tp_GetVariousFileMask() stores the string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

Parameters:
o the tunepimp_t object returned from tp_New()
variousFileMask a user supplied buffer of maxLen characters
maxLen the size of the buffer
See also:
tp_SetVarousFileMask()

void tp_GetVersion tunepimp_t  o,
int *  major,
int *  minor,
int *  rev
 

Get the version number of this library.

Parameters:
o the tunepimp_t object returned from tp_New
major an int pointer that will receive the major number of the version
minor an int pointer that will receive the minor number
rev an int pointer that will receive the rev number

int tp_GetWriteID3v1 tunepimp_t  o  ) 
 

Check if writing ID3v1 tags to MP3 files is enabled.

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
true if ID3v1 writing is enabled and false otherwise
See also:
tp_SetWriteID3v1()

void tp_IdentifyAgain tunepimp_t  o,
int  fileId
 

Mark a file as misidentified. The status is set back to eFileLookup which causes file lookup to be done on the file. Any MusicBrainz ids that have been downloaded for this file are ignored and a lookup from the metadata is done in order to find the right file on the MB server.

Parameters:
o the tunepimp_t object returned from tp_New()
fileId a fileId
See also:
tp_Misidentified()

void tp_Misidentified tunepimp_t  o,
int  fileId
 

Discard all MusicBrainz idenitifiers and identify this file again. The status is set back to ePending which causes the whole identification process to start again, including TRM generation.

Parameters:
o the tunepimp_t object returned from tp_New()
fileId a fileId
See also:
tp_IdentifyAgain()

tunepimp_t tp_New const char *  appName,
const char *  appVersion
 

Create a new handle (a C abstraction) to the TunePimp object. Call tp_Delete() when done with the handle.

Parameters:
appName the name of your application
appVersion the version number of your application
Returns:
the tunepimp_t type is used in subsequent tunepimp functions.
See also:
tp_Delete()

tunepimp_t tp_NewWithArgs const char *  appName,
const char *  appVersion,
int  startThreads
 

Create a new handle (a C abstraction) to the TunePimp object, specifying which internal threads to start. Call tp_Delete() when done with the handle.

Parameters:
appName the name of your application
appVersion the version number of your application
startThreads a bit flag that specifies which internal threads to start. Pass in one or more TP_THREAD_XXXX flags that are or'ed together.
Returns:
the tunepimp_t type is used in subsequent tunepimp functions.
See also:
tp_Delete()

void tp_ReleaseTrack tunepimp_t  o,
track_t  track
 

Release the specified track object.

Parameters:
o the tunepimp_t object returned from tp_New()
track the track handle
See also:
tp_GetTrack(),

tr_Lock(),

tr_Unlock()

void tp_Remove tunepimp_t  o,
int  fileId
 

Remove a file entry from the list. fileId is the file's handle returned by tp_Add(). The file itself isn't removed from disk.

Parameters:
o the tunepimp_t object returned from tp_New()
fileId the Id of the file you want to remove.
See also:
tp_Add(), tp_AddDir()

TPError tp_SelectResult tunepimp_t  o,
track_t  track,
int  resultIndex
 

Select one of the results that were returned by tr_GetResults(). resultIndex is the index of an array element and thus starts at 0. The results MUST BE deleted using rs_Delete()

Parameters:
o the tunepimp_t object returned from tp_New()
track a track object obtained via tp_GetTrack()
resultIndex the array index of the result to select
Returns:
tpInvalidIndex if resultIndex was invalid and tpOk on success
See also:
tr_GetResults(), tr_GetNumResults(), rs_Delete()

void tp_SetAllowedFileCharacters tunepimp_t  o,
const char *  allowedFileCharacters
 

Use this function to set a white list of characters that are permitted in a filename.

If you set allowedFileCharacters to the empty string, all characters permitted by the underlying file system are regarded as allowed. All other characters are removed from filenames written by tunepimp. Please note, however, that the directory separator ("/" on Unix) is always permitted.

The default is the empty string ("").

Parameters:
o the tunepimp_t object returned from tp_New()
allowedFileCharacters the list of allowed characters
See also:
tp_GetAllowedFileCharacters(), tp_SetFileMask(), tp_SetVariousFileMask()

void tp_SetAnalyzerPriority tunepimp_t  o,
TPThreadPriorityEnum  priority
 

This function sets the analyzer thread priority level.

Parameters:
o the tunepimp_t object returned from tp_New()
priority The priority to set the analyzer to. See include/defs.h for values for this parameter.
See also:
tp_GetAnalyzerPriority()

void tp_SetAutoFileLookup tunepimp_t  o,
int  enable
 

Set enable to a non-zero value to activate AutoFileLookup. If set, tunepimp tries a file lookup (using data found in the file's tag) when the TRM of a track wasn't found in the musicbrainz database.

If enable is set to zero and no TRM is found in the database, the track's status is set to eUnrecognized. You can then manually set the state to eFileLookup using tr_SetState() to initiate a file lookup. A file lookup uses meta data found in the file to query the database.

For tracks that have matching TRMs in the database, AutoFileLookup has no effect.

Defaults to "enabled".

Parameters:
o the tunepimp_t object returned from tp_New()
enable a non-zero value enables automatic file lookup
See also:
tr_SetState(), tp_GetAutoFileLookup()

void tp_SetAutoRemovedSavedFiles tunepimp_t  o,
int  autoRemoveSavedFiles
 

Use this function to control if the tunepimp library automatically deletes files after they've been saved or if they should be moved to the eSaved status.

Parameters:
o the tunepimp_t object returned from tp_New()
autoRemoveSavedFiles automatically remove the files (true/false)
See also:
tp_GetAutoRemovedSavedFiles

void tp_SetAutoSaveThreshold tunepimp_t  o,
int  autoSaveThreshold
 

Use this function to set the auto save threshold.

When the similarity value (see tp_SetTRMCollision()) is greater or equal the auto save threshold, a recognized file (in state eRecognized) is marked as verified (eVerified). The effect is the same as calling tp_WriteTags() on a recognized file.

The writing is done immediately, without the possibility of user intervention.

Valid values for the threshold are between 0 and 100, including 0 and 100. Set it to a negative value to disable the auto save feature.

Default: 90.

Parameters:
o the tunepimp_t object returned from tp_New()
autoSaveThreshold the auto save threshold
See also:
tp_SetTRMCollisionThreshold(), tp_WriteTags(), tp_GetAutoSaveThreshold()

void tp_SetClearTags tunepimp_t  o,
int  clearTags
 

Use this function to enable/disable the clearning of metadata tags before the MusicBrainz data is written to the tag. If the metadata tags have crufty data in them and you want to clean them completely before writing new data to the tag, then enable this option.

Default: false

Parameters:
o the tunepimp_t object returned from tp_New()
clearTags set a non-zero value to enable tag clearing
See also:
tp_GetClearTags(), tp_WriteTags()

void tp_SetDebug tunepimp_t  o,
int  debug
 

Enable debugging output to stdout by sending a non-zero value to this function. Whenever the tunepimp library makes a server call, the data sent to the server and the data returned from the server is printed to stdout.

Default: disabled.

Parameters:
o the tunepimp_t object returned from tp_New
debug whether or not to enable debug (non-zero enables debug output)
See also:
tp_GetDebug(), tp_GetError()

void tp_SetDestDir tunepimp_t  o,
const char *  destDir
 

This function sets a base directory that is prepended to all files written by tunepimp if the move feature is enabled. The base directory may be absolute or relative. No trailing directory separator ("/" or "\") is required.

Default: "MyMusic" in the current working directory.

Parameters:
o the tunepimp_t object returned from tp_New()
destDir a directory name
See also:
tp_GetDestDir(), tp_SetFileMask(), tp_SetVariousFileMask(), tp_SetFileMove()

void tp_SetFileMask tunepimp_t  o,
const char *  fileMask
 

Set the file mask. The file mask is a format string roughly similar to the one used in printf(3). Whenever a filename has to be created, the escape sequences embedded in the file mask are expanded with meta data from the musicbrainz database.

The following escape sequences are supported:

  • artist (Name of the artist)
  • abc (The first character of the artist's sortname)
  • abc2 (The first two character of the artist's sortname)
  • abc3 (The first three character of the artist's sortname)
  • sortname (Sortname of the artist)
  • track (Title of the song)
  • album (Title of the album)
  • num (Track number on the album)
  • 0num (Track number on the album, zero padded to two places)
  • format (The format of the given file e.g. ogg/mp3/wav/flac/ape)
  • type (The release type: single, album, remix, etc)
  • status (The release status: official, bootleg, promo)
  • year (The first release year)
  • month (The first release month)
  • day (The first release day)
  • country (The first release country)

Please note that you have to use tp_SetVariousFileMask() to set the file mask for tracks from various artists releases.

The default file mask is "%artist/%album/%artist-%album-%0num-%track".

Parameters:
o the tunepimp_t object returned from tp_New()
fileMask a format string
See also:
tp_GetFileMask(), tp_SetVariousFileMask(), tp_SetDestDir()

void tp_SetMaxFileNameLen tunepimp_t  o,
int  maxFileNameLen
 

Use this function to set the maximum filename length

Parameters:
o the tunepimp_t object returned from tp_New()
maxFileNameLen the maximum filename length
See also:
tp_GetMaxFileNameLen

void tp_SetMinTRMThreshold tunepimp_t  o,
int  minThreshold
 

Set the minimum recognition threshold for TRM lookups.

If there is a TRM match for a given track, but the similarity between the metadata returned is below the minimum recognition threshold, then the TRM match should not be accepted and the file should be listed as unrecognized.

Valid values for the threshold are between 0 and 100, including 0 and 100.

Default: 50.

Parameters:
o the tunepimp_t object returned from tp_New()
minThreshold the threshold value to use
See also:
tp_GetMinTRMThreshold, tp_GetResults(), tp_SelectResult()

void tp_SetMoveFiles tunepimp_t  o,
int  move
 

If enabled, files are moved to the destination directory as specified in the file mask or the various artists file mask. Files are only moved to a new directory, but the file name isn't changed.

Default: enabled.

Parameters:
o the tunepimp_t object returned from tp_New()
move set a non-zero value to enable moving
See also:
tp_GetMoveFiles(), tp_SetRenameFiles(), tp_WriteTags(), tp_SetFileMask(), tp_SetVariousFileMask(), tp_SetDestDir()

void tp_SetNotifyCallback tunepimp_t  o,
tp_notify_callback  callback,
void *  data
 

Use this function to register a callback function with tunepimp that gets called each time a file is added (using tp_AddFile() or tp_AddDir()), removed (using tp_Remove()) or changed. A change is signalled every time the status of a track changes.

Note that if a callback is provided the tp_GetNotification() function will no longer return notification messages. To unset a callback, pass in NULL to this function. Only one function may be registered at a time.

Parameters:
o the tunepimp_t object returned from tp_New()
callback a function pointer to set or NULL to unset a callback
data a private data member that will be passed back verbatim to the callback
See also:
tp_SetStatusCallback(), tr_GetStatus(), tp_GetNotification(), tp_GetNotifyCallback()

void tp_SetProxy tunepimp_t  o,
const char *  serverAddr,
short  serverPort
 

Set the name of the HTTP Proxy to use. This function must be called anytime the client library must communicate via a proxy firewall. To disable the use of the proxy server, set serverAddr to the empty string ("").

Parameters:
o the tunepimp_t object returned from tp_New()
serverAddr the name of the proxy server to use e.g. proxy.mydomain.com
serverPort the port number to use. e.g. 8080
See also:
tp_GetProxy(), tp_SetServer()

void tp_SetRenameFiles tunepimp_t  o,
int  rename
 

If enabled, files are renamed as specified in the file mask or the various artists file mask. Only the file name is changed, this setting doesn't imply moving the file to a new directory.

Default: enabled.

Parameters:
o the tunepimp_t object returned from tp_New()
rename set a non-zero value to enable renaming
See also:
tp_GetRenameFiles(), tp_SetMoveFiles(), tp_WriteTags(), tp_SetFileMask(), tp_SetVariousFileMask()

void tp_SetServer tunepimp_t  o,
const char *  serverAddr,
short  serverPort
 

Set the name and the port of the MusicBrainz server to use. If this function is not called, the default www.musicbrainz.org server on port 80 will be used.

Parameters:
o the tunepimp_t object returned from tp_New
serverAddr the name of the musicbrainz server to use e.g. www.musicbrainz.org
serverPort the port number to use. e.g. 80
See also:
tp_GetServer(), tp_SetProxy()

void tp_SetStatusCallback tunepimp_t  o,
tp_status_callback  callback,
void *  data
 

Use this function to register a callback function to receive textual messages describing tunepimp's current status. The messages are intended for direct output to the user. Don't try to parse the messages. All important information can be retrieved by other means.

Note that if a callback is provided the tp_GetStatusCallback() function will no longer return Status messages. To unset a callback, pass in NULL to this function. Only one function may be registered at a time.

Parameters:
o the tunepimp_t object returned from tp_New()
callback a function pointer to set or NULL to unset a callback
data a private data member that will be passed back verbatim to the callback
See also:
tp_SetNotifyCallback(), tp_GetError(), tp_GetStatusCallback()

void tp_SetTopSrcDir tunepimp_t  o,
const char *  topSrcDir
 

When TunePimp moves a file out of a directory to a new directory, and the old directory is now empty, the old directory is removed. This process is repeated for the old directory's parent, until it reaches the TopSrcDir, where it stops removing directories. Set the TopDrcDir to root of the directory tree where Tunepimp is writing ID3 files to.

Example:

TopSrcDir in this case is set to: /mnt/mp3

/mnt/mp3/dirty_mp3s/Beatles/Yesterday.mp3

The Yesterday song is the only file left in the dirty_mp3s folder. When tunepimp moves this file to its new, clean location, it will remove the Beatles directory, then the dirty_mp3s directory, but it will not remove the /mnt/mp3 directory, since that is the TopSrcDir.

Parameters:
o the tunepimp_t object returned from tp_New()
topSrcDir the top src directory to use
See also:
tp_GetTopSrcDir()

void tp_SetTRMCollisionThreshold tunepimp_t  o,
int  trmThreshold
 

Set the recognition threshold for TRM collisions.

If there is more than one entry matching a TRM in the musicbrainz database, we have a TRM collision. In this case, a similarity value is calculated for each returned database entry using the file's meta data as the reference. The similarity is a percent value describing how good the match is.

If the similarity is greater or equal than the TRMCollisionThreshold, the file is marked as recognized (eRecognized). Otherwise, the track's status is set to eTRMCollision which requires user interaction to select one of the returned results.

Valid values for the threshold are between 0 and 100, including 0 and 100.

Default: 80.

Parameters:
o the tunepimp_t object returned from tp_New()
trmThreshold the TRM threshold
See also:
tp_GetTRMCollisionThreshold, tp_SetAutoSaveThreshold(), tp_GetResults(), tp_SelectResult()

void tp_SetUserInfo tunepimp_t  o,
const char *  userName,
const char *  password
 

This function must be called if you want to submit data to the server. Anonymous TRM submission using tp_SubmitTRMs() is not permitted. If you're looking up data from the server, you do not need to call tp_SetUserInfo.

Parameters:
o the tunepimp_t object returned from tp_New()
userName the name of the user
password the plaintext password of the user
See also:
tp_SubmitTRMs()

void tp_SetUseUTF8 tunepimp_t  o,
int  useUTF8
 

Use this function to select the charset of the data returned by tunepimp. Set it to a non-zero value to select UTF-8. Otherwise, ISO-8859-1 (latin1) will be used.

Parameters:
o the tunepimp_t object returned from tp_New()
useUTF8 if set to a non-zero value, UTF-8 will be used.
See also:
tp_GetUseUTF8()

void tp_SetVariousFileMask tunepimp_t  o,
const char *  variousFileMask
 

Set the file mask for various artists releases. See tp_SetFileMask() for a discussion of file masks.

For single artist releases, tp_SetFileMask() has to be used.

The default is "Various Artists/%album/%album-%0num-%artist-%track".

Parameters:
o the tunepimp_t object returned from tp_New()
variousFileMask a format string
See also:
tp_SetFileMask(), tp_SetDestDir()

void tp_SetWriteID3v1 tunepimp_t  o,
int  writeID3v1
 

Use this function to enable writing of legacy ID3v1 tags to MP3 files. ID3v1 tags are supported by almost every existing MP3 player.

Default: enabled.

Parameters:
o the tunepimp_t object returned from tp_New()
writeID3v1 set a non-zero value to enable ID3v1 tags
See also:
tp_GetWriteID3v1(), tp_WriteTags()

TPError tp_SubmitTRMs tunepimp_t  o  ) 
 

Send all unsubmitted TRMs to trackId mappings to the server. Except for TRM and trackId, no further meta data is sent.

To prevent abuse, however, you need to authenticate to the server using tp_SetUserInfo() before calling tp_SubmitTRMs().

Parameters:
o the tunepimp_t object returned from tp_New()
Returns:
tpOk on success and tpSubmitError on error
See also:
tp_GetNumUnsubmitted(), tp_SetUserInfo(), tp_GetError()

void tp_Wake tunepimp_t  o,
track_t  track
 

Wake up tunepimp to look for work to do.

You have to call this function every time you change a track's status using tr_SetStatus(). This call will wake up the TunePimp internal threads to look for tracks that need to be processed. If you do not call this function after you make a change to a track, the change will be ignored.

Parameters:
o the tunepimp_t object returned from tp_New()
track the handle of the track that changed
See also:
tr_SetStatus()

int tp_WriteTags tunepimp_t  o,
int *  fileIds,
int  numFileIds
 

Write tags for the specified files. Only files in state eRecognized will be written. If renaming was enabled using tp_SetRenameFiles(), the files are also renamed as specified in the file part of the file mask. Otherwise, the file name stays as it is.

If moving was enabled using tp_SetMoveFiles(), the files are moved to the destination directory (see tp_SetDestDir()) while keeping their original file names. If, additionally, renaming was enabled, the files are moved to a subdirectory of the destination directory depending on the directory part of the file mask.

If fileIds is set to the NULL pointer, all recognized files are written. In this case the numFileIds argument is ignored.

tp_WriteTags() doesn't return an error indicator if there were problems writing the files. You have to check the track status to see if writing was successful. The state is changed to eDeleted on success and deleted as soon as neither tunepimp nor the client have any more references to the track. The status is set to eError if an error occurs. Until writing of a track is done, the track stays in state eVerified.

Please note that files that had a similarity greater or equal to the AutoSaveThreshold are written automatically, right after they have been recognized.

Parameters:
o the tunepimp_t object returned from tp_New()
fileIds a pointer to an array of fileIds or NULL
numFileIds the number of fileIds in the array
Returns:
zero if a fileId was invalid or not all files were recognized
See also:
tp_SetAutoSaveThreshold(), tp_SetMoveFiles(), tp_SetRenameFiles, tp_SetAllowedFileChars(), tp_SetWriteID3v1(), tr_GetState(), tp_SetFileMask(), tp_SetVariousFileMask(), tp_SetDestDir()

void tr_GetError track_t  t,
char *  error,
int  maxLen
 

Use this function to get a printable error message for the last error that occured in the track object. tr_GetError() stores the error string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

Don't confuse this function with tp_GetError().

Parameters:
t a track object obtained via tp_GetTrack()
error a user supplied buffer of maxLen characters
maxLen the size of the buffer
See also:
tp_GetError()

void tr_GetFileName track_t  t,
char *  fileName,
int  maxLen
 

Get the filename of the specified track. The function stores the filename in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

Parameters:
t a track object obtained via tp_GetTrack()
fileName a user supplied buffer of maxLen characters
maxLen the size of the buffer

void tr_GetLocalMetadata track_t  t,
metadata_t mdata
 

Get the track's meta data that was already present in the file. The meta data is saved in a valid metadata_t object passed as an argument. No I/O takes place since the data will have been read during the TRM analisys stage. Files that are still in the ePending stage may not have correct local metadata.

Parameters:
t a track object obtained via tp_GetTrack()
mdata a meta data object created by md_New()
See also:
tr_SetLocalMetadata(), tr_GetServerData(), tp_GetTrack(), md_New()

int tr_GetNumResults track_t  t  ) 
 

Returns the number of results that were retrieved using TRM or file lookup.

Parameters:
t a track object obtained via tp_GetTrack()
Returns:
the number of results
See also:
tr_GetResults(), tp_SelectResult()

void tr_GetResults track_t  t,
TPResultType type,
result_t results,
int *  numResults
 

Get the results that were returned for a TRM or file lookup.

The results argument has to be a pointer to a result_t. When the function returns, it points to a an array of newly allocated objects, depending on the type argument. If type is eArtistList, results points to an artistresult_t array, for eAlbumList to a albumresult_t array and for eTrackList to a tracklist_t array.

Don't forget to release the memory using rs_Delete() when you're done.

Parameters:
t a track object obtained via tp_GetTrack()
type the address of a variable to receive the result type
results the address of a result_t variable
numResults the address of a variable to receive the number of results
See also:
tr_GetResults(), rs_Delete()

void tr_GetServerMetadata track_t  t,
metadata_t mdata
 

Retrieve the meta data we got back from the server. This data will have been downloaded from the server if a track was recognized or it was set by tunepimp when the user selected a Lookup result.

The server meta data is used to construct file and directory names and is written to the tags as soon as the data is verified (eVerified).

Parameters:
t a track object obtained via tp_GetTrack()
mdata a valid metadata_t object
See also:
tr_SetServerMetadata(), tr_GetLocalMetadata(), tp_GetTrack(), md_New()

int tr_GetSimilarity track_t  t  ) 
 

Get the similarity of the local and the server meta data.

The similarity is a percent value between 0 and 100. Before a lookup, the similarity is 0. If no metadata was extracted from the file, the similarity will also be 0.

Parameters:
t a track object obtained via tp_GetTrack()
Returns:
a similarity value

TPFileStatus tr_GetStatus track_t  t  ) 
 

Returns the status of a track.

It is also possible to get notifed as soon as the status of a track changes using the notfy callback.

Parameters:
t a track object obtained via tp_GetTrack()
Returns:
the status of the track
See also:
tp_SetNotifyCallback(), tp_GetTrack()

void tr_GetTRM track_t  t,
char *  trm,
int  maxLen
 

Get the TRM of the specified track in an ASCII representation. The TRM is stored in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.

A TRM is MB_ID_LEN=36 characters long, so you can set maxLen to 37.

Parameters:
t a track object obtained via tp_GetTrack()
trm a user supplied buffer of maxLen characters
maxLen the size of the buffer

int tr_HasChanged track_t  t  ) 
 

Returns true if local and server meta data differ and false otherwise.

Parameters:
t a track object obtained via tp_GetTrack()
Returns:
true if local and server meta data differ and false otherwise

void tr_Lock track_t  t  ) 
 

Lock a track object to make sure tunepimp doesn't change it while you are working on it. Tunepimp is multithreaded so it is needed to avoid race conditions. Don't forget to release the lock using tr_Unlock() when you're done.

Parameters:
t a track object obtained via tp_GetTrack()
See also:
tr_Unlock()

void tr_SetLocalMetadata track_t  t,
const metadata_t mdata
 

Set the track's local meta data to the specified values. No I/O takes place. The local meta data is sent to the server when doing a TRM or file lookup if there isn't server meta data from a previous lookup.

To avoid race conditions, you have to tr_Lock() the track before using tr_SetLocalMetadata() and tr_Unlock() afterwards.

Parameters:
t a track object obtained via tp_GetTrack()
mdata a valid metadata_t object
See also:
tr_GetLocalMetadata(), tr_SetServerData(), tp_GetTrack(), md_New()

void tr_SetServerMetadata track_t  t,
const metadata_t mdata
 

Set the server meta data. It is used to write the tag and to construct new file and directory names as soon as the data is verifed (eVerified).

When doing lookups the server meta data is used if it is available. Otherwise, the local meta data is used.

Parameters:
t a track object obtained via tp_GetTrack()
mdata a valid metadata_t object
See also:
tr_GetServerMetadata(), tr_SetLocalMetadata(), tp_GetTrack(), md_New()

void tr_SetStatus track_t  t,
const TPFileStatus  status
 

Set a track's status. Setting the status is necessary if a track is in state eTRMCollision, eUserSelection or eUnrecognized. Don't forget to lock the track before using this function and unlocking it afterwards.

Parameters:
t a track object obtained via tp_GetTrack()
status the new status of the track
See also:
tr_Lock(), tr_Unlock()

void tr_Unlock track_t  t  ) 
 

Unlock a track object previously locked using tr_Lock(). You are not allowed to unlock tracks that were locked by tunepimp itself.

Parameters:
t a track object obtained via tp_GetTrack()
See also:
tr_Lock()


Generated on Thu Jul 13 09:51:25 2006 for MusicBrainz Tunepimp Library by  doxygen 1.4.6