libmusicbrainz-objc

This library is a iOS library for MusicBrainz Web Service and will eventually develop into a Framework for OS X use as well. This library was created as part of Brandon LeBlanc's 2012 Google Summer of Code project.

Getting Started

• To use the library in an iOS application
• Add libmusicbrainz-objc.xcodeproj to your project
• For the application's target under Build Phases add iOS-Framework to Target Dependencies
• Under Link Binary With Libraries add in order (all should be marked Required):
  1. Foundation.framework
  2. CFNetwork.framework
  3. SystemConfiguration.framework
  4. MobileCoreServices.framework
  5. UIKit.framework
  6. Security.framework
  7. libxml2.dylib
  8. libz.dylib
  9. libmusicbrainz-iphoneos.a
• Add $(SDKROOT)/usr/include/libxml2 to HEADER_SEARCH_PATHS under Build Settings
• Add #import <musicbrainz-ios/MB.h> to your source and away you go.

Examples

All communication with the webservice is done with MBConnection objects with MBRequest objects.

Create an MBConnection object like:

MBConnection * conn = [MBConnection connectionWithClientName:@"client-version"
                                                      server:@"musicbrainz.org"
                                                        port:[NSNumber numberWithInt:80]
                      ];

For all instances of the initializer, ClientName is a required parameter, cannot be empty and cannot be nil (see the webservice documentation as to why). Server defaults to ”musicbrainz.org” and port defaults to 80.

To create a request, examine MBRequest.h for the various helper creators. For a simple lookup request, you can use:

MBRequest * req = [MBRequest lookupWithEntity:MBEntityArtist
                                         mbid:@"7e84f845-ac16-41fe-9ff8-df12eb32af55"
                                incParameters:( MBIncParameterArtistRels | MBIncParameterReleaseGroups )
                  ];

MBEntity* and MBIncParameter* are enums declared in MBRequests.h.

To submit the request, use:

void (^successBlock) (MBRequest*, MBMetadata*) = ^(MBRequest * request, MBMetadata * metadata)
{
  // ObjC block that does something with metadata
};

void (^failureBlock) (MBRequest*, NSError*, NSData*) = ^(MBRequest * request, NSError * error, NSData * response)
{
  // ObjC block that does something with the error
  // response may be nil
};

[conn enqueueRequest:req
           onSuccess:successBlock
           onFailure:failureBlock];

where successBlock and failureBlock are ObjC blocks that handle the response from the webservice. successBlock and failureBlock may or may not be executed on the main thread, assume not and act accordingly.

MBMetadata, and all of it's siblings, have properties according to the data returned from the webservice. Any extra attributes or elements not contained in the properties can be accessed via the ExtraAttributes/ExtraElements dictionaries, respectively.

Documentation

You can access the documentation documentation in several ways:

1. Online: http://demosdemon.github.com/libmusicbrainz-objc/docs/html
2. Within Xcode:
   1. Open your Xcode Preferences (⌘,) and switch to Documentation tab.
   2. Click the + button
   3. Add the docset feed: feed://demosdemon.github.com/libmusicbrainz-objc/docs/publish/org.metabrainz.libmusicbrainz-objc.atom
3. Generate the documentation from the project repository with the genappledoc.sh script (appledoc must be installed for this to work)
4. Generate the documentation within xcode using the Documentation target (appledoc must be installed for this to work)

License

libmusicbrainz-objc is licensed under the MIT 'Expat' License. libmusicbrainz-objc uses software from:

• Google Toolbox for Mac with Apache 2.0 License
• KissXML with BSD License
• MKNetworkKit with the MIT License
• SSKeychain with the MIT License