Plugin Development

This is designed so that others may write plugins for different carriers that are not supported by default.

These plugins are stand alone programs that receive the user's credentials, and retrieve the usage information from the provider's web site
 and returns formatted output to a file that will then be absorbed into the main program.

Below are the technical details on how to implement such a plugin. Here is what you will need

* Knowledge of python. In theory you might be able to use another language, but it would make things FAR more difficult
* At least one, and preferably multiple accounts on the provider you want to add access to
* The python source code for my tool http://sourceforge.net/p/emailcellusage/code/

Things to keep in mind
* Often carriers represent data for single user account differently from family accounts, test on both
* I hope this goes without saying, but NEVER send the user's credentials ANYWHERE but the cell providers web site
* Feel free to study how I am pulling down data from ATT, Sprint, and Verizon. These techniques 'should' work for other providers

Plugins should be placed in ./lib/communicationPlugins/

Here is the heart of a plugin

    #load the file containing the user credentials
    result, preferences = email_cell_usage_lib.plugin_loadPreferences()

    #if this fails, write the error message and exit
    if not result == 'Ok':
        data = {}
        data['result'] = result
        email_cell_usage_lib.plugin_write_data(data)
        sys.exit()

    #make your call to retrieve the data. My plugins make heavy use of
    #email_cell_usage_lib.get_web_page and
    #email_cell_usage_lib.dataToArray, but you are free to use other 
    #methods if you so choose    
    result, data = cellProviderData(preferences)

    #once you have data, clean up the cookie files that were written
    #needed if you made any calls using email_cell_usage_lib.get_web_page
    email_cell_usage_lib.cleanup_cookie()

    #if data was successfully retrieve, insert a result = 'Ok',
    if result == 'Ok':
        data['result'] = 'Ok'

    #if not insert the error into the result field
    else:
        data = {}
        data['result'] = result

    #write the data list so it can be read in by the main process
    email_cell_usage_lib.plugin_write_data(data)

    #exit
    sys.exit()

Here is the structure of the dictionary list you need to build

    'cycleLength': 30,   #length of billing cycle. If provider does not explicitly provide, assume 30 or some other reasonable number
    'daysLeft': '9',    #the days left in the billing cycle
    'phoneNumCount': 3,  #the number of phone numbers associated with the account

    #additional fields can be added, such as account number of other information that is useful to track to help assemble the data
    #the extra fields will be ignored by the main code
    'phoneNumbers': {   '5103333333': {  
                                          'data': {   'max': '4096',
                                                      'usage': '763'},
                                          'name': 'Ronald Dorn',
                                          'texts': {   'count': '343',
                                                       'max': 'Unlimited'},
                                          'voice': {   'day': '91',
                                                       'mobile': '70',
                                                       'night': '8'}},
                        '5104444444': {  
                                          'data': {   'max': '200',
                                                      'usage': '80.2'},
                                          'name': 'Jodi Dorn',
                                          'texts': {   'count': '7068',
                                                       'max': 'Unlimited'},
                                          'voice': {   'day': '9',
                                                       'mobile': '139',
                                                       'night': '6'}},
                        '5109999999': {  
                                          'data': {   'max': '200',
                                                      'usage': '66.42'},
                                          'name': 'Elaina Dorn',
                                          'texts': {   'count': '442',
                                                       'max': 'Unlimited'},
                                          'voice': {   'day': '1',
                                                       'mobile': '125',
                                                       'night': '25'}}},
    #this is the status of your data collection efforts
    #if a password is wrong, web site is down, or any other
    #error is encountered, here is where you provide that information
    'result': 'Ok',

    #these are the account total settings and limits for shared data. This assumes
    #that voice is shared, but data and texts are not.                          
    'totalVoice': {   'max': {   'day': '700',
                                 'mobile': 'Unlimited',
                                 'night': 'Unlimited'},
                      'used': {   'day': '101', 'mobile': '334', 'night': '39'}}}    

You can test out your code by running the following

./bin/testProviderAccess.py {account name} {account password} {your plugin, minus any extension}

Example

bin/testProviderAccess.py 5103333333 myPassword ATT

This will return all the data you provided, plus it will add estimates and other derived data

Once you have a plugin that is working and generating the list results above, it should work within my code
without issue. Contact me and let me know that you have a plugin that would like to add to the site. I will

* Review the code and ensure that it is not do anything bad, and has decent error handling (bad passwords, etc)
* Compile the code for Windows, Mac
* Make the Windows, Mac, and raw python available on the plugin section of my site

If you want to distribute independently you can, but I think it would make more sense to have it associated with the main project

Thanks

Ron Dorn
ron_dorn_1@yahoo.com