GVoice: An Open Source Objective-C Google Voice Library

05/12/2011 Note: I failed to mention that the library, as it currently stands, builds for iOS only. I’m sure it could be rejiggered to work with OSX, because I don’t think I used any iOS specific features. All the project files would need to be changed, and I’m not sure what’s involved with that.

I am please to announce my free and open source Objective-C library for working with Google Voice. It’s called GVoice and you can find it here. It’s BSD licensed, which means you can use it for anything you want, both commercial and free/opensource.

It’s quite easy to use, and this example should help:

[objc]
// USERNAME, PASSWORD, SOURCE and ACCOUNT_TYPE should be replaced with proper
// values.
self.voice = [[GVoice alloc] initWithUser: USERNAME password: PASSWORD source: SOURCE
accountType: ACCOUNT_TYPE];

// This causes some logging to happen.
self.voice.logToConsole = YES;

BOOL res = [self.voice login];

if (!res) {
// error handling
}

// Assuming you have a phone whose id is 23, this would cause Google Voice
// to route calls to it.
res = [self.voice enablePhone: 23]

if (!res) {
// error handling
}

// Send an SMS. Replace TEXT_PHONE_NUMBER with a proper 10-digit phone number
// capable of receiving SMS messages
res = [self.voice sendSmsText: @"Testing 1, 2, 3" toNumber: TEXT_PHONE_NUMBER];

if (!res) {
// error handling
}
[/objc]

On line 3, we create an instance of GVoice, passing in the email address and password from the user. The third field, source, is a field required by Google to identify where the connection is coming from. It’s free-form, but they suggest a reverse_domain_name-app-version approach, , something like com.joeygibson-GVTest-1.0, for example. The fourth parameter is what sort of account you’re trying to connect to, and there are two choices: GOOGLE and HOSTED. (This is an enum that also has a value of HOSTED_OR_GOOGLE, but I would suggest letting your user decide which account they have. It will save you problems later.)

Line 9 is where the actual login happens. If you get back a YES, all is well. If not, you can look at the GVoice object’s errorDescription property.

Line 17 demonstrates using one of the features of the library: enabling a phone. You pass the phone’s Id, which is obtained through another part of the API, and GV will then ring that number when a call comes in. You can also disable phones in the same fashion.

Line 25 shows how to send an SMS message from the GV account to the specified mobile phone.

There are many features that are fully formed, though some are still not as polished as I’d like. Two things still remain to be done: handling redirects and CAPTCHAs. After a certain number of failed logins, a URL will be returned that leads to a CAPTCHA image. To login after than you need to send a response to the CAPTCHA, but none of that is implemented in the library yet. Similarly, sometimes requests can be redirected by Google, but the library doesn’t handle those either. I’ve never seen either of these cases occur, but they could.

There is a full test suite included, which provides many more examples of how to use it. Before trying to compile it, you need to copy a file in the GVTests directory called GVCredentials-Sample.h to GVCredentials.h, replacing the dummy values with proper values. After that, you should be able to compile it and run the tests.

Full API documentation is available in the doc/ directory.

I wrote this library to use with my own iPhone app, which is currently in final testing before submission to the app store. I thought it would be useful for other people, so that’s why it’s free. If you’d like to use it, please do. If you’d like to improve it, let me know, and I can give you access to the repo.

It’s hosted on Bitbucket: https://bitbucket.org/joeygibson/gvoice.

Objective-C 2.0 Properties Are Needlessly Verbose

I’ve been working in Objective-C for a little while now; not quite two years, off and on. I was really excited when Apple announced that Objective-C 2.0 was going to have generated properties, but the syntax they gave us leaves me flat, as it is needlessly verbose.

For those who don’t know, in Objective-C 1.x, if you had an instance variable in a class that you wanted to expose, you had to provide getter and setter methods for it, just like you do in Java, C++ and several other OO languages. You would see something like this in MyClass.h:

@interface MyClass : NSObject {
    NSString *name;
}

- (void) setName: (NSString *) aName;
- (NSString *) name;
@end

and then in MyClass.m, you would see this:

#import "MyClass.h"

@implementation MyClass
- (void) setName: (NSString *) aName
{
    [aName retain];
    [name release];
    name = aName;
}

- (NSString *) name
{
    return name;
}
@end

Objective-C 2.0 promised to eliminate all that boilerplate code in your *.m files for getting and setting variables. But they did it in a strange way. Now, in MyClass.h, you would see this:

@interface MyClass : NSObject {
    NSString *name;
}

@property(nonatomic, retain) NSString *name;
@end

and then in MyClass.m, this

#import "MyClass.h"

@implementation MyClass

@synthesize name

@end

Now, it certainly cut out quite a bit of code for the getter and setter, but why do I have to declare the type of the property twice? You have to declare the instance variable as usual, but then you also have to specify the data type again when you add the @property declaration. There’s no reason I can think of that those two lines couldn’t have been combined into the variable declaration. Objective-C already has tokens that are ignored, such as IBOutlet, so it shouldn’t have been an issue with breaking the parser. And the @synthesize declaration in the *.m file is annoying, but I guess it was necessary to keep the properties from being auto-created in the wrong place.  In my opinion, this is what property declarations should look like

@interface MyClass : NSObject {
    @property(nonatomic, retain) NSString *name;
}

@end

That’s it. No duplication. Simple. Elegant.

Can anyone think of a good reason why they didn’t do it like that?

12/28/2008 15:13:23 Update: As Ahruman pointed out in his comment, I misspoke about IBOutlet. It is not actually ignored, but is used to tag an instance variable for use by Interface Builder. Sorry for the confusion. And be sure to read his comment below. It’s packed with good info that I didn’t know.