The Apple Delegation Pattern
This section should be a simple “teach Grandmother to suck eggs” discussion. If you are not already familiar with using Apple Cocoa Touch Delegates, then you really need to work on learning the basics of iOS programming. Delegation is absolutely crucial to effective Cocoa Touch development, and it is the fundamental structure for using the BMLTiOSLib.
Don’t feel bad if this is unfamiliar territory, but you’ll need to have at least the basic vocabulary in place to understand the discussions and concepts we’ll cover in these pages. Take the time to really learn iOS programming. It’s a lucrative field, and well worth the effort.
A Delegate Relationship is a Contract
At its most fundamental level, being a Delegate means that you are assuring the library that you will be able to be called back with certain functions. Think of it as telling someone “You can call me at any time at 123-456-7890.”
It also means that the library promises to call those functions in a certain manner. For example, you could follow up the above statement by saying “I only speak English, so whoever you have call me needs to speak English.”
In particular, for this page, we should refer to the BMLTiOSLibDelegate documentation.
The introductory header of the documentation has some fairly fundamental information that you need to understand:
Only 2 of these functions are required: · func bmltLibInstance(_ inLibInstance: BMLTiOSLib, serverIsValid: Bool) · func bmltLibInstance(_ inLibInstance: BMLTiOSLib, errorOccurred error: Error) All the rest are optional. These are all called in the main thread.
Optional vs. Required
The first note:
Only 2 of these functions are required: · func bmltLibInstance(_ inLibInstance: BMLTiOSLib, serverIsValid: Bool) · func bmltLibInstance(_ inLibInstance: BMLTiOSLib, errorOccurred error: Error)
Means that there are two functions that you MUST implement.
All the rest are optional.
Means that you have the option to implement the other nine functions, but you don’t have to, and the BMLTiOSLib needs to be cool with that.
It’s like saying “I’ll always immediately answer the phone if you call 123-456-7890, but I probably won’t use 123-456-7891, so make sure that you can handle getting a ‘there is no one at this number’ response if you call it.”
These are standard search request callbacks:
func bmltLibInstance(_: BMLTiOSLib, meetingSearchResults: [BMLTiOSLibMeetingNode])
func bmltLibInstance(_: BMLTiOSLib,formatSearchResults: [BMLTiOSLibFormatNode], isAllUsedFormats: Bool)
func bmltLibInstance(_: BMLTiOSLib, changeListResults: [BMLTiOSLibChangeNode])
func bmltLibInstance(_: BMLTiOSLib, deletedChangeListResults: [BMLTiOSLibChangeNode])
These are used for administration (Meeting Editor stuff):
func bmltLibInstance(_: BMLTiOSLib, loginChangedTo: Bool)
func bmltLibInstance(_: BMLTiOSLib, newMeetingAdded: BMLTiOSLibEditableMeetingNode)
func bmltLibInstance(_: BMLTiOSLib, meetingRolledback: BMLTiOSLibEditableMeetingNode)
func bmltLibInstance(_: BMLTiOSLib, adminMeetingChangeComplete: BMLTiOSLibChangedMeeting!)
func bmltLibInstance(_: BMLTiOSLib, deleteMeetingSuccessful: Bool)
This is for when users want to send messages to meeting contacts:
The functionality of your app will inform which of the above callbacks you implement. For example, a simple meeting search app (like NA Meeting Finder) won’t be doing any administration tasks, so there is no need to implement any of the five administration callbacks.
The last item:
These are all called in the main thread.
Means that you don’t have to worry about switching to the main execution thread (See the note at the end of this page) before doing anything. In Cocoa Touch, you shouldn’t attempt any UI unless you are in the main thread. Communication methods often use multiple threads when communicating, and callbacks are often performed in threads other than the main one; which means that you need to switch to the main thread before attempting anything that could affect UI.
This is not necessary with BMLTiOSLib delegate callbacks. They are already in the main thread when you get them, so don’t worry about doing things that affect UI.
- Other Topics
- An Illustration of the BMLT System
- BMLT Roles
- Is Your Server Set Up Correctly?
- Test Site Links
- The BMLT Satellite Base Class
- The BMLTiOSLib iOS Framework
- Configuration Management And Release