Poster of Linux kernelThe best gift for a Linux geek
tp_c.h

tp_c.h

Section: MusicBrainz Tunepimp Library (3) Updated: Fri Mar 25 2011
Local index Up
 

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 255This 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 32This 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_tThe abstraction of a Track object. Functions to manipulate have a prefix of 'tr_'.

 

typedef void* tunepimp_ttunepimp_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 (TPAlbumStatusstatus, char *albumStatus, intmaxLen)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 (TPAlbumTypetype, char *albumType, intmaxLen)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_to, 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_to, const char *fileName, intreadMetadataNow)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_to)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_to, 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_to, char *allowedFileCharacters, intmaxLen)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_to)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_to)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_to)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_to)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_to)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_to, char *destDir, intmaxLen)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_to, char *error, intmaxLen)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_to, int *ids, intnumIds)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_to, char *fileMask, intmaxLen)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_to, char *encoding, intmaxEncodingLen)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_to)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_to)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_to)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_to, char *clientId, intmaxClientIdLen)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_to, char *nonAlbumFileMask, intmaxLen)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_to, 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_to)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_to)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_to)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_to)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_to)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_to, char *serverAddr, intmaxLen, 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_to, intthreshold, 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_to)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_to, char *serverAddr, intmaxLen, 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_to, char *status, intstatusLen)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_to)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_to, charextensions[][TP_EXTENSION_LEN])

 

void tp_GetTopSrcDir (tunepimp_to, char *topSrcDir, intmaxLen)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_to, intfileId)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_to, int *counts, intmaxCounts)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_to, char *variousFileMask, intmaxLen)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_to, 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_to)

 

int tp_GetWriteID3v1 (tunepimp_to)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_to)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_to, intfileId)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_to, intfileId)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, intstartThreads, 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_to, track_ttrack)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_to, intfileId)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_to, 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_to, TPThreadPriorityEnumpriority)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_to, intautoRemoveSavedFiles)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_to, intautoSaveThreshold)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_to, intclearTags)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_to, intdebug)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_to, 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_to, 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_to, 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_to, TPID3Encodingencoding)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_to, intmaxFileNameLen)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_to, intmove)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_to, 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_to, 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_to, tp_notify_callbackcallback, 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_to, const char *serverAddr, shortserverPort)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_to, intrename)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_to, const char *serverAddr, shortserverPort)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_to, tp_status_callbackcallback, 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_to, 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_to, 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_to, intwinSafeFileNames)

 

void tp_SetWriteID3v1 (tunepimp_to, intwriteID3v1)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_to, intwriteID3v2_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_to, track_ttrack)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_to, int *fileIds, intnumFileIds)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_tt, char *error, intmaxLen)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_tt, char *fileName, intmaxLen)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_tt, 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_tt, char *puid, intmaxLen)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_tt, 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_tt)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_tt)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_tt)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_tt)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_tt)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_tt, 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_tt, 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_tt, const TPFileStatusstatus)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_tt)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.


 

Index

NAME
SYNOPSIS
Classes
Defines
Typedefs
Functions
Define Documentation
#define TP_ALBUM_NAME_LEN 255
#define TP_ARTIST_NAME_LEN 255This structure holds the meta data of a track.
#define TP_COUNTRY_LEN 3
#define TP_EXTENSION_LEN 32This function returns a list of supported audio formats. The elements of the list are the usual filename extensions like '.wav', '.mp3', '.ogg' etc.
#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().
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().
typedef void* track_tThe abstraction of a Track object. Functions to manipulate have a prefix of 'tr_'.
typedef void* tunepimp_ttunepimp_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.
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.
void md_ConvertFromAlbumStatus (TPAlbumStatusstatus, char *albumStatus, intmaxLen)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.
void md_ConvertFromAlbumType (TPAlbumTypetype, char *albumType, intmaxLen)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.
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.
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.
void md_Delete (metadata_t *mdata)Delete a metadata_t object.
metadata_t* md_New (void)Create a new metadata_t object.
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
int tp_AddDir (tunepimp_to, 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().
int tp_AddFile (tunepimp_to, const char *fileName, intreadMetadataNow)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.
void tp_Delete (tunepimp_to)The destructor for the TunePimp class.
void tp_DeleteRecognizedFileList (tunepimp_to, int *fileIds)Release the memory allocated by tp_GetRecognizedFileList(). You can use this function even if there were no fileIds returned.
void tp_GetAllowedFileCharacters (tunepimp_to, char *allowedFileCharacters, intmaxLen)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.
TPThreadPriorityEnum tp_GetAnalyzerPriority (tunepimp_to)This function gets the analyzer thread priority level.
int tp_GetAutoRemovedSavedFiles (tunepimp_to)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.
int tp_GetAutoSaveThreshold (tunepimp_to)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.
int tp_GetClearTags (tunepimp_to)Query the tunepimp object if tag clearing is enabled. See tp_SetClearTags() for more information.
int tp_GetDebug (tunepimp_to)Check if debugging is enabled.
void tp_GetDestDir (tunepimp_to, char *destDir, intmaxLen)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.
void tp_GetError (tunepimp_to, char *error, intmaxLen)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.
void tp_GetFileIds (tunepimp_to, int *ids, intnumIds)Returns the fileIds in tunepimp's list. At most numIds are returned.
void tp_GetFileMask (tunepimp_to, char *fileMask, intmaxLen)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.
void tp_GetFileNameEncoding (tunepimp_to, char *encoding, intmaxEncodingLen)Parameters:
TPID3Encoding tp_GetID3Encoding (tunepimp_to)Check which encoding is set for writing ID3v2 tags.
int tp_GetMaxFileNameLen (tunepimp_to)Use this function to get the current maximum filename length
int tp_GetMoveFiles (tunepimp_to)Check if file moving is enabled. See tp_SetMoveFiles() for more information.
void tp_GetMusicDNSClientId (tunepimp_to, char *clientId, intmaxClientIdLen)Get the MusicDNS clientId that was set with the tp_SetMusicDNSClientId function.
void tp_GetNonAlbumFileMask (tunepimp_to, char *nonAlbumFileMask, intmaxLen)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.
int tp_GetNotification (tunepimp_to, 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.
tp_notify_callback tp_GetNotifyCallback (tunepimp_to)Get the function registered to receive notification messages. See tp_SetNotifyCallback() for more information.
int tp_GetNumFileIds (tunepimp_to)Get the number of filesIds that a call to tp_GetFileIds() would return.
int tp_GetNumFiles (tunepimp_to)This function returns the number of files that tunepimp has in its list.
int tp_GetNumSupportedExtensions (tunepimp_to)Query the number of audio file formats supported by tunepimp. The number depends on which libraries were present when tunepimp was compiled.
int tp_GetNumUnsavedItems (tunepimp_to)This function returns the number of track that have been recognized and are ready to be saved.
void tp_GetProxy (tunepimp_to, char *serverAddr, intmaxLen, 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.
int tp_GetRecognizedFileList (tunepimp_to, intthreshold, 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.
int tp_GetRenameFiles (tunepimp_to)Query the tunepimp object if file renaming is enabled. See tp_SetRenameFiles() for an explanation.
void tp_GetServer (tunepimp_to, char *serverAddr, intmaxLen, 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.
int tp_GetStatus (tunepimp_to, char *status, intstatusLen)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.
tp_status_callback tp_GetStatusCallback (tunepimp_to)Get the function registered to receive status messages. See tp_SetStatusCallback() for more information.
void tp_GetSupportedExtensions (tunepimp_to, charextensions[][TP_EXTENSION_LEN])
void tp_GetTopSrcDir (tunepimp_to, char *topSrcDir, intmaxLen)Use this function to get the top source directory. See tp_SetTopSrcDir() for more information.
track_t tp_GetTrack (tunepimp_to, intfileId)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.
int tp_GetTrackCounts (tunepimp_to, int *counts, intmaxCounts)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]
void tp_GetVariousFileMask (tunepimp_to, char *variousFileMask, intmaxLen)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.
void tp_GetVersion (tunepimp_to, int *major, int *minor, int *rev)Get the version number of this library.
int tp_GetWinSafeFileNames (tunepimp_to)
int tp_GetWriteID3v1 (tunepimp_to)Check if writing ID3v1 tags to MP3 files is enabled.
int tp_GetWriteID3v2_3 (tunepimp_to)Check if writing ID3v2_3 tags to MP3 files is enabled.
void tp_IdentifyAgain (tunepimp_to, intfileId)Mark a file as misidentified.
void tp_Misidentified (tunepimp_to, intfileId)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.
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.
tunepimp_t tp_NewWithArgs (const char *appName, const char *appVersion, intstartThreads, 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.
void tp_ReleaseTrack (tunepimp_to, track_ttrack)Release the specified track object.
void tp_Remove (tunepimp_to, intfileId)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.
void tp_SetAllowedFileCharacters (tunepimp_to, const char *allowedFileCharacters)Use this function to set a white list of characters that are permitted in a filename.
void tp_SetAnalyzerPriority (tunepimp_to, TPThreadPriorityEnumpriority)This function sets the analyzer thread priority level.
void tp_SetAutoRemovedSavedFiles (tunepimp_to, intautoRemoveSavedFiles)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.
void tp_SetAutoSaveThreshold (tunepimp_to, intautoSaveThreshold)Use this function to set the auto save threshold.
void tp_SetClearTags (tunepimp_to, intclearTags)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.
void tp_SetDebug (tunepimp_to, intdebug)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.
void tp_SetDestDir (tunepimp_to, 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.
void tp_SetFileMask (tunepimp_to, 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.
void tp_SetFileNameEncoding (tunepimp_to, const char *encoding)Use this function to specify the encoding to be used for writing filenames to the filesystem. Defaults to UTF-8.
void tp_SetID3Encoding (tunepimp_to, TPID3Encodingencoding)Use this function to set which encoding to write to ID3v2 tags.
void tp_SetMaxFileNameLen (tunepimp_to, intmaxFileNameLen)Use this function to set the maximum filename length
void tp_SetMoveFiles (tunepimp_to, intmove)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.
void tp_SetMusicDNSClientId (tunepimp_to, const char *clientId)Set the MusicDNS clientId.
void tp_SetNonAlbumFileMask (tunepimp_to, const char *nonAlbumFileMask)Set the file mask for non-album releases. See tp_SetFileMask() for a discussion of file masks.
void tp_SetNotifyCallback (tunepimp_to, tp_notify_callbackcallback, 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.
void tp_SetProxy (tunepimp_to, const char *serverAddr, shortserverPort)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 ('').
void tp_SetRenameFiles (tunepimp_to, intrename)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.
void tp_SetServer (tunepimp_to, const char *serverAddr, shortserverPort)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.
void tp_SetStatusCallback (tunepimp_to, tp_status_callbackcallback, 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.
void tp_SetTopSrcDir (tunepimp_to, 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.
void tp_SetVariousFileMask (tunepimp_to, const char *variousFileMask)Set the file mask for various artists releases. See tp_SetFileMask() for a discussion of file masks.
void tp_SetWinSafeFileNames (tunepimp_to, intwinSafeFileNames)
void tp_SetWriteID3v1 (tunepimp_to, intwriteID3v1)Use this function to enable writing of legacy ID3v1 tags to MP3 files. ID3v1 tags are supported by almost every existing MP3 player.
void tp_SetWriteID3v2_3 (tunepimp_to, intwriteID3v2_3)Use this function to enable writing of ID3v2.3 tags to MP3 files. ID3v2.4 tags are the default for tunepimp.
void tp_Wake (tunepimp_to, track_ttrack)Wake up tunepimp to look for work to do.
int tp_WriteTags (tunepimp_to, int *fileIds, intnumFileIds)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.
void tr_GetError (track_tt, char *error, intmaxLen)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.
void tr_GetFileName (track_tt, char *fileName, intmaxLen)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.
void tr_GetLocalMetadata (track_tt, 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.
void tr_GetPUID (track_tt, char *puid, intmaxLen)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.
void tr_GetServerMetadata (track_tt, 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.
int tr_GetSimilarity (track_tt)Get the similarity of the local and the server meta data.
TPFileStatus tr_GetStatus (track_tt)Returns the status of a track.
int tr_HasChanged (track_tt)Returns true if local and server meta data differ and false otherwise.
void tr_Lock (track_tt)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.
void tr_SetChanged (track_tt)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.
void tr_SetLocalMetadata (track_tt, const metadata_t *mdata)Set the track's local meta data to the specified values. No I/O takes place.
void tr_SetServerMetadata (track_tt, 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).
void tr_SetStatus (track_tt, const TPFileStatusstatus)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.
void tr_Unlock (track_tt)Unlock a track object previously locked using tr_Lock(). You are not allowed to unlock tracks that were locked by tunepimp itself.
Author

This document was created by man2html, using the manual pages.
Time: 21:57:45 GMT, April 16, 2011