Phonegap javascript API proposal

[Brude]

The company I work for has given me a project which involves adding a
significant amount of functionality to the android version of
phonegap.

The hope is that we'll do this work and some of it can be repeated on
the iPhone and other platforms by someone else :) Therefore I would
like to do it with some approval.

Here is the API for feedback.

Cheers
Ray

SMS Class
• Void startListener([successCallback], [errorCallback])
• Void stopListener([successCallback], [errorCallback])
• Void onReceive(successCallback(sendersNumber, smsContent),
[errorCallback] )
• Void send(number, message, [successCallback], [errorCallback])

File IO Class
• void createDirectory(directory, successCallback, [errorCallback])
• void deleteDirectory(directory, successCallback, [errorCallback])
• Boolean testDirectoryExists(directory);
• Long getFreeDiskSpace(sucessCallback, [errorCallback]);

Audio class
• Void startRecording(fileName, encoding, successCallback,
[errorCallback])
• Void stopRecording(successCallback, [errorCallback])
• Void startPlaying(filename, successCallback, [errorCallback])
• Void stopPlaying(successCallback, [errorCallback])
• Int getDuration(successCallback, [errorCallback])
• Int getCurrentPosition(successCallback, [errorCallback])
• Void setOutputDevice(device, successCallback, [errorCallback]) //
EARPIECE, SPEAKER
• String getOutputDevice(successCallback, [errorCallback])
• Void startSpooling(url, successCallback, [errorCallback])

HTTP Class
• Void get(url, fileName, successCallback, [errorCallback]) //
filename is the full save path
• Void post(??? TBD)

Phone Class
• Void call(number, [mode], [successCallback], [errorCallback]) //
mode = DIAL, CALL where CALL requires no further confirmation

Settings Class
• String getNetworkOperatorName(successCallback, [errorCallback])
• String getVoicemailNumber(successCallback, [errorCallback])
• String getTimeZoneID(successCallback, [errorCallback]);
• String getSimCountryIso(successCallback, [errorCallback])
• String getLine1Number(successCallback, [errorCallback]);

[Brude]

Sorry I spotted one mistake already.

Int getDuration(filename, successCallback, [errorCallback])

[dave johnson]

That looks awesome Ray!

That is exactly where we want to go with the API esp wrt the SMS listening - I would like to see that over top of general notification listening functionality (essentially listen for phone calls, emails, sms, whatever else in a general way).

One thing that I would suggest is to think about is using the same W3C geolocation API semantics for "listening" where they go with Geolocation.watchPosition / clearWatch instead of something like Geolocation.startListener / stopListener. I prefer the more generic startListener / stopListener myself but it might be good to align with those "standard" APIs :S I guess we can just alias them too.

As far as the Phone class goes we have something defined for "Telephony" that has a call method that takes just the number - wasn't sure if the success / error callbacks would quite work or not and I am not sure about if there is the equivalent "mode" in IPhone? http://github.com/davejohnson/phonegap/blob/b052eb95c153fb9a7ce22405aca76a8781f4d415/javascripts/telephony.js

Finally, what do people think about how to normalize the file access stuff and directory creation etc... I have been grappling with this a bit between BlackBerry and Android. For example on most devices there is device memory and SD memory. How do we differentiate in a device agnostic way? What can be written to / read from and what sort of generic interfaces might we want for that?

-dave

[dave johnson]

FYI Ray the JavaScript API stuff in my repo (http://github.com/davejohnson/phonegap) or Rob's (http://github.com/silentrob/phonegap/) is soon going to move to the sintaxi master soon.

Thinking more about the file system normalization and talking with Brian maybe we just do something like "sdcard://", "file://" and map that on platform by platform? It could even be cool to do something like Android does in terms of giving URIs to all content like "contacts://" ... hmmm


-d

[Andre Charland]

Maybe we should post the API to the wiki? Has anyone looked at the OMTP Bondi spec? http://bondi.omtp.org/default.aspx It seems to have gotten a lot of buzz at the Mobile World Conference in Barcelona this week.

Andre.

--
André Charland
President and Co-Founder, Nitobi
e. andre.c...@gmail.com
skype. ebadre
b. http://blogs.nitobi.com/andre
w. http://www.nitobi.com

[Chris Webb]

Andre,

Good point and something I was about to ask as well.

Chris

[Chris Webb]

About Bondi that is.

[dave johnson]

The JS API is on the wiki http://phonegap.pbwiki.com/JavaScript-API and on the PhoneGap site as generated from the JSDoc in the source code http://www.phonegap.com/docs/

Yes we should look at the Bondi spec http://bondi.omtp.org/apis/

-dave

[Brude]

Hi Dave,

I think you’re spot on with the listener. In fact that’s exactly the
design android uses so I’m not sure why I didn’t think of it.

I agree it’s better to suck it up and use the dodgy W3C listener
names.

With attempting a phone call is it better to allow for many modes and
fallback to a supported mode? I suppose that could be a hard coded
override or an order of preference similar to fonts in CSS?

I was thinking the same thing about file access, abstract the root
directory whatever it may be, I like your idea of file:// etc

I had a quick look at Bondi:
http://bondi.omtp.org/apis-current/annotated.html

I noticed the file class was remarkably similar, right down to names.
They seem to have taken a different approach than notification start/
stop listening. Their API has certainly had a lot of work put into it.
The more consolidation of specs the better, it certainly deserves a
long look.

Cheers
Ray