--- name: "tp_c.h" section: "3" platform: "linux" package: "libtunepimp-dev" version: "0.5.3-7.3" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/tp_c.h" --- # tp\_c.h(3) ## NAME tp\_c.h - ## SYNOPSIS `#include 'defs.h'`\ ### Classes struct **\_metadata\_t**\ ### Defines \#define **TP\_ARTIST\_NAME\_LEN** 255\ \#define **TP\_ALBUM\_NAME\_LEN** 255\ \#define **TP\_TRACK\_NAME\_LEN** 255\ \#define **TP\_ID\_LEN** 40\ \#define **TP\_FORMAT\_LEN** 32\ \#define **TP\_COUNTRY\_LEN** 3\ \#define **TP\_EXTENSION\_LEN** 32\ ### Typedefs typedef void \* **tunepimp\_t**\ typedef void \* **track\_t**\ typedef void(\* **tp\_notify\_callback** )(**tunepimp\_t** pimp, void \*data, **TPCallbackEnum** type, int fileId, **TPFileStatus** status)\ typedef void(\* **tp\_status\_callback** )(**tunepimp\_t** pimp, void \*data, const char \*status)\ typedef struct **\_metadata\_t** **metadata\_t**\ ### Functions **tunepimp\_t** **tp\_New** (const char \*appName, const char \*appVersion)\ **tunepimp\_t** **tp\_NewWithArgs** (const char \*appName, const char \*appVersion, int startThreads, const char \*pluginDir)\ void **tp\_Delete** (**tunepimp\_t** o)\ void **tp\_GetVersion** (**tunepimp\_t** o, int \*major, int \*minor, int \*rev)\ void **tp\_SetMusicDNSClientId** (**tunepimp\_t** o, const char \*clientId)\ void **tp\_GetMusicDNSClientId** (**tunepimp\_t** o, char \*clientId, int maxClientIdLen)\ void **tp\_SetFileNameEncoding** (**tunepimp\_t** o, const char \*encoding)\ void **tp\_GetFileNameEncoding** (**tunepimp\_t** o, char \*encoding, int maxEncodingLen)\ 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\_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, **TPFileStatus** \*status)\ 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 readMetadataNow)\ 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\_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)\ 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\_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\_SetWriteID3v2\_3** (**tunepimp\_t** o, int writeID3v2\_3)\ int **tp\_GetWriteID3v2\_3** (**tunepimp\_t** o)\ void **tp\_SetID3Encoding** (**tunepimp\_t** o, **TPID3Encoding** encoding)\ **TPID3Encoding** **tp\_GetID3Encoding** (**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\_SetNonAlbumFileMask** (**tunepimp\_t** o, const char \*nonAlbumFileMask)\ void **tp\_GetNonAlbumFileMask** (**tunepimp\_t** o, char \*nonAlbumFileMask, 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\_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)\ int **tp\_GetWinSafeFileNames** (**tunepimp\_t** o)\ void **tp\_SetWinSafeFileNames** (**tunepimp\_t** o, int winSafeFileNames)\ **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\_GetPUID** (**track\_t** t, char \*puid, 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)\ void **tr\_SetChanged** (**track\_t** t)\ void **tr\_Lock** (**track\_t** t)\ void **tr\_Unlock** (**track\_t** t)\ **metadata\_t** \* **md\_New** (void)\ void **md\_Delete** (**metadata\_t** \*mdata)\ void **md\_Clear** (**metadata\_t** \*mdata)\ int **md\_Compare** (const **metadata\_t** \*mdataA, const **metadata\_t** \*mdataB)\ **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)\ float **md\_Similarity** (const char \*a, const char \*b)\ ## Define Documentation ### #define TP\_ALBUM\_NAME\_LEN 255 ### #define TP\_ARTIST\_NAME\_LEN 255 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 PUID collision, numPUIDIds is set to a value greater than one. If variousArtist is true, the track is from a various artists release. If nonAlbum is true, the track resides within a special non-album tracklisting. 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()** ### #define TP\_COUNTRY\_LEN 3 ### #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()** ### #define TP\_FORMAT\_LEN 32 ### #define TP\_ID\_LEN 40 ### #define TP\_TRACK\_NAME\_LEN 255 ## Typedef Documentation ### typedef struct \_metadata\_t metadata\_t ### typedef void(\* tp\_notify\_callback)(tunepimp\_t pimp, void \*data, TPCallbackEnum type, int fileId, TPFileStatus status) 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()** ### int md\_Compare (const metadata\_t \* mdataA, const metadata\_t \* mdataB) Compare two metadata\_t objects and return a similarity value between 0.0 and 1.0, where zero is totally dissimilar and 1.0 is exactly the same. **Parameters:** *mdataA* a valid metadata\_t object \ *mdataB* a valid metadata\_t object ### 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()** ### float md\_Similarity (const char \* a, const char \* b) Does a fuzzy string comparison and returns the similarity value between 0.0 and 1.0 **Parameters:** *a* the first string \ *b* the second string **Returns:** a float value from 0.0 (completely dissimilar strings) to 1.0 (the exact same strings) ### 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, int readMetadataNow) 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 \ *readMetadataNow* read the file metadata before returning **Returns:** a fileId handle for your file **See also:** **tp\_AddDir()**, **tp\_SetNotifyCallback()** ### 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\_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()** ### void tp\_GetFileNameEncoding (tunepimp\_t o, char \* encoding, int maxEncodingLen) Parameters: *o* the tunepimp\_t object returned from **tp\_New()**\ *encoding* the encoding to use. \ *maxEncodingLen* length of the encoding string **See also:** **tp\_SetFileNameEncoding()** ### TPID3Encoding tp\_GetID3Encoding (tunepimp\_t o) Check which encoding is set for writing ID3v2 tags. **Parameters:** *o* the tunepimp\_t object returned from **tp\_New()** **Returns:** one of eLatin1, eUTF8 or eUTF16 **See also:** **tp\_SetID3Encoding()** ### 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\_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()** ### void tp\_GetMusicDNSClientId (tunepimp\_t o, char \* clientId, int maxClientIdLen) Get the MusicDNS clientId that was set with the tp\_SetMusicDNSClientId function. **Parameters:** *o* the tunepimp\_t object returned from **tp\_New()** \ *clientId* a user supplied buffer of maxClientIdLen characters \ *maxClientIdLen* the max size of the buffer for the client name ### void tp\_GetNonAlbumFileMask (tunepimp\_t o, char \* nonAlbumFileMask, 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()** \ *nonAlbumFileMask* a user supplied buffer of maxLen characters \ *maxLen* the size of the buffer **See also:** **tp\_SetNonAlbumFileMask()** ### int tp\_GetNotification (tunepimp\_t o, TPCallbackEnum \* type, int \* fileId, TPFileStatus \* status) 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 \ *status* the address of a variable to receive the current status **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 ### 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. ### 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\_SetVariousFileMask()** ### 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\_GetWinSafeFileNames (tunepimp\_t o) ### 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()** ### int tp\_GetWriteID3v2\_3 (tunepimp\_t o) Check if writing ID3v2\_3 tags to MP3 files is enabled. **Parameters:** *o* the tunepimp\_t object returned from **tp\_New()** **Returns:** true if ID3v2\_3 writing is enabled and false otherwise **See also:** **tp\_SetWriteID3v2\_3()** ### void tp\_IdentifyAgain (tunepimp\_t o, int fileId) Mark a file as misidentified. **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 PUID 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, const char \* pluginDir) 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. \ *pluginDir* the directory where tunepimp plugins can be found **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()** ### 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()**, **tp\_SetNonAlbumFileMask()** ### 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\_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\_SetPUIDCollision()) 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\_SetPUIDCollisionThreshold(), **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(), tp\_SetNonAlbumMask() ### 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()**, **tp\_SetNonAlbumFileMask()** ### void tp\_SetFileNameEncoding (tunepimp\_t o, const char \* encoding) Use this function to specify the encoding to be used for writing filenames to the filesystem. Defaults to UTF-8. UTF-8 and ISO-8859-1 are supported by default and more encodings are supported by ICU is ICU is available to libtp at compilation time. **Parameters:** *o* the tunepimp\_t object returned from **tp\_New()** \ *encoding* the encoding to use. Must be 'UTF-8', 'ISO-8859-1' or an ICU supported encoding. **See also:** **tp\_GetFileNameEncoding()** ### void tp\_SetID3Encoding (tunepimp\_t o, TPID3Encoding encoding) Use this function to set which encoding to write to ID3v2 tags. Default: utf-8 for ID3v2.4, ISO 8859-1 (latin1) for ID3v2.3 **Parameters:** *o* the tunepimp\_t object returned from **tp\_New()** \ *encoding* set to one of eLatin1, eUTF8 or eUTF16 **See also:** **tp\_GetWriteID3v2\_3()**, **tp\_WriteTags()** ### 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\_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()**, **tp\_SetNonAlbumFileMask()** ### void tp\_SetMusicDNSClientId (tunepimp\_t o, const char \* clientId) Set the MusicDNS clientId. **Parameters:** *o* the tunepimp\_t object returned from **tp\_New()** \ *clientId* a client id ### void tp\_SetNonAlbumFileMask (tunepimp\_t o, const char \* nonAlbumFileMask) Set the file mask for non-album releases. See tp\_SetFileMask() for a discussion of file masks. For regular album releases, **tp\_SetFileMask()** or **tp\_SetVariousFileMask()** has to be used. The default file mask is '%artist/%album/%artist-%track'. **Parameters:** *o* the tunepimp\_t object returned from **tp\_New()** \ *nonAlbumFileMask* a format string **See also:** **tp\_SetFileMask()**, **tp\_SetDestDir()**, tp\_SetVariousMask() ### 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()**, **tp\_SetNonAlbumFileMask()** ### 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\_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()**, **tp\_SetNonAlbumFileMask()** ### void tp\_SetWinSafeFileNames (tunepimp\_t o, int winSafeFileNames) ### 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()** ### void tp\_SetWriteID3v2\_3 (tunepimp\_t o, int writeID3v2\_3) Use this function to enable writing of ID3v2.3 tags to MP3 files. ID3v2.4 tags are the default for tunepimp. Default: disabled **Parameters:** *o* the tunepimp\_t object returned from **tp\_New()** \ *writeID3v2\_3* set a non-zero value to enable ID3v2\_3 tags **See also:** **tp\_GetWriteID3v2\_3()**, **tp\_WriteTags()** ### 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()**, **tp\_SetNonAlbumFileMask()**, **tp\_SetWriteID3v2\_3()**, **tp\_SetID3Encoding()** ### 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 PUID 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()** ### void tr\_GetPUID (track\_t t, char \* puid, int maxLen) Get the PUID of the specified track in an ASCII representation. The PUID is stored in a user supplied buffer. Not more than maxLen characters including the trailing '\\0' byte are copied into that buffer. A PUID is MB\_ID\_LEN=36 characters long, so you can set maxLen to 37. **Parameters:** *t* a track object obtained via **tp\_GetTrack()** \ *puid* a user supplied buffer of maxLen characters \ *maxLen* the size of the buffer ### 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. 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()** ### 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\_SetChanged (track\_t t) Mark a track as changed, so that it will be saved even if libtp doesn't think the track changed. (Useful for cases where the encoding changed, which libtp doesn't detect. **Parameters:** *t* a track object obtained via **tp\_GetTrack()** ### 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. 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). **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 ePUIDCollision, 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()** ## Author Generated automatically by Doxygen for MusicBrainz Tunepimp Library from the source code.