com.parse
Class PushService

Object
  extended by android.content.Context
      extended by android.content.ContextWrapper
          extended by android.app.Service
              extended by com.parse.PushService
All Implemented Interfaces:
ComponentCallbacks

public final class PushService
extends Service

A service to listen for push notifications. This operates in the same process as the parent application. The PushService can listen to pushes from two different sources: Google Cloud Messaging (GCM) or the Parse Push Notification Service (PPNS). Parse will inspect your application's manifest at runtime and determine which service to use for push. We recommend using GCM for push on devices that have Google Play Store support. PPNS support is provided for apps that want to avoid a dependency on the Google Play Store, and for devices (like Kindles) which do not have Play Store support. To configure the PushService for GCM, ensure these permission declarations are present in your AndroidManifest.xml as children of the <manifest> element:

 <uses-permission android:name="android.permission.INTERNET" />
 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
 <uses-permission android:name="android.permission.VIBRATE" />
 <uses-permission android:name="android.permission.WAKE_LOCK" />
 <uses-permission android:name="android.permission.GET_ACCOUNTS" />
 <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
 <permission android:name="YOUR_PACKAGE_NAME.permission.C2D_MESSAGE"
   android:protectionLevel="signature" />
 <uses-permission android:name="YOUR_PACKAGE_NAME.permission.C2D_MESSAGE" />
 
 
 Replace YOUR_PACKAGE_NAME in the declarations above with your application's package name. Also,
 make sure that com.parse.GcmBroadcastReceiver and com.parse.PushService are declared as children
 of the <application> element:
 
 
 <service android:name="com.parse.PushService" />
 <receiver android:name="com.parse.GcmBroadcastReceiver"
  android:permission="com.google.android.c2dm.permission.SEND">
   <intent-filter>
     <action android:name="com.google.android.c2dm.intent.RECEIVE" />
     <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
     <category android:name="YOUR_PACKAGE_NAME" />
   </intent-filter>
 </receiver>
 
Again, replace YOUR_PACKAGE_NAME with your application's package name. To configure the PushService for PPNS, ensure these permission declarations are present in your AndroidManifest.xml as children of the <manifest> element:
 <uses-permission android:name="android.permission.INTERNET" />
 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
 <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
 <uses-permission android:name="android.permission.VIBRATE" />
 <uses-permission android:name="android.permission.WAKE_LOCK" />
 
Also, make sure that com.parse.ParseBroadcastReceiver and com.parse.PushService are declared as children of the <application> element: <service android:name="com.parse.PushService" /> <receiver android:name="com.parse.ParseBroadcastReceiver"> <intent-filter> <action android:name="android.intent.action.BOOT_COMPLETED" /> <action android:name="android.intent.action.USER_PRESENT" /> </intent-filter> </receiver> Note that you can configure the push service for both GCM and PPNS by adding all the declarations above to your application's manifest. In this case, Parse will use GCM on devices with Play Store support and fall back to using PPNS on devices without Play Store support. Once push notifications are configured in the manifest, you can subscribe to a push channel by calling:
 PushService.subscribe(context, "the_channel_name", YourActivity.class);
 
When the client receives a push message, a notification will appear in the system tray. When the user taps the notification, they will enter the application through a new instance of YourActivity.


Field Summary
 
Fields inherited from class android.content.Context
ACTIVITY_SERVICE, ALARM_SERVICE, AUDIO_SERVICE, BIND_AUTO_CREATE, BIND_DEBUG_UNBIND, CLIPBOARD_SERVICE, CONNECTIVITY_SERVICE, CONTEXT_IGNORE_SECURITY, CONTEXT_INCLUDE_CODE, INPUT_METHOD_SERVICE, KEYGUARD_SERVICE, LAYOUT_INFLATER_SERVICE, LOCATION_SERVICE, MODE_APPEND, MODE_PRIVATE, MODE_WORLD_READABLE, MODE_WORLD_WRITEABLE, NOTIFICATION_SERVICE, POWER_SERVICE, SEARCH_SERVICE, SENSOR_SERVICE, TELEPHONY_SERVICE, VIBRATOR_SERVICE, WALLPAPER_SERVICE, WIFI_SERVICE, WINDOW_SERVICE
 
Constructor Summary
PushService()
          Client code should not construct a PushService directly.
 
Method Summary
static Set<String> getSubscriptions(Context context)
          Accesses the current set of channels for which the current installation is subscribed.
 IBinder onBind(Intent intent)
          onBind should not be called directly.
 void onCreate()
          Client code should not call onCreate directly.
 void onDestroy()
          Client code should not call onDestroy directly.
 int onStartCommand(Intent intent, int flags, int startId)
           
static void setDefaultPushCallback(Context context, Class<? extends Activity> cls)
          Provides a default Activity class to handle pushes.
static void setDefaultPushCallback(Context context, Class<? extends Activity> cls, int icon)
          Provides a default Activity class to handle pushes.
static void startServiceIfRequired(Context context)
           
static void subscribe(Context context, String channel, Class<? extends Activity> cls)
          Helper function to subscribe to push notifications with the default application icon.
static void subscribe(Context context, String channel, Class<? extends Activity> cls, int icon)
          Call this function when the user should be subscribed to a new push channel.
static void unsubscribe(Context context, String channel)
          Cancels a previous call to subscribe.
 
Methods inherited from class android.app.Service
dump, finalize, getApplication, onConfigurationChanged, onLowMemory, onRebind, onStart, onUnbind, setForeground, stopSelf, stopSelf, stopSelfResult
 
Methods inherited from class android.content.ContextWrapper
attachBaseContext, bindService, checkCallingOrSelfPermission, checkCallingOrSelfUriPermission, checkCallingPermission, checkCallingUriPermission, checkPermission, checkUriPermission, checkUriPermission, clearWallpaper, createPackageContext, databaseList, deleteDatabase, deleteFile, enforceCallingOrSelfPermission, enforceCallingOrSelfUriPermission, enforceCallingPermission, enforceCallingUriPermission, enforcePermission, enforceUriPermission, enforceUriPermission, fileList, getApplicationContext, getAssets, getBaseContext, getCacheDir, getClassLoader, getContentResolver, getDatabasePath, getDir, getFilesDir, getFileStreamPath, getMainLooper, getPackageCodePath, getPackageManager, getPackageName, getPackageResourcePath, getResources, getSharedPreferences, getSystemService, getTheme, getWallpaper, getWallpaperDesiredMinimumHeight, getWallpaperDesiredMinimumWidth, grantUriPermission, openFileInput, openFileOutput, openOrCreateDatabase, peekWallpaper, registerReceiver, registerReceiver, removeStickyBroadcast, revokeUriPermission, sendBroadcast, sendBroadcast, sendOrderedBroadcast, sendOrderedBroadcast, sendStickyBroadcast, setTheme, setWallpaper, setWallpaper, startActivity, startInstrumentation, startService, stopService, unbindService, unregisterReceiver
 
Methods inherited from class android.content.Context
getString, getString, getText, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes
 
Methods inherited from class Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PushService

public PushService()
Client code should not construct a PushService directly.

Method Detail

startServiceIfRequired

public static void startServiceIfRequired(Context context)

subscribe

public static void subscribe(Context context,
                             String channel,
                             Class<? extends Activity> cls)
Helper function to subscribe to push notifications with the default application icon.

Parameters:
context - This is used to access local storage to cache the subscription, so it must currently be a viable context.
channel - A string identifier that determines which messages will cause a push notification to be sent to this client. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.
cls - This should be a subclass of Activity. An instance of this Activity is started when the user responds to this push notification. If you are not sure what to use here, just use your application's main Activity subclass.
Throws:
IllegalArgumentException - if the channel name is not valid.

subscribe

public static void subscribe(Context context,
                             String channel,
                             Class<? extends Activity> cls,
                             int icon)
Call this function when the user should be subscribed to a new push channel. When push notifications are sent out on this channel subsequently, this device will display a "toast" notification in the system tray. This function returns immediately, even when there is no internet access. In that case the subscription is cached and when internet access is next available the client will inform the server of its subscription. This starts a PushService running in the background that will not permanently terminate as long as the user is subscribed to some channel, unless the application is uninstalled.

Parameters:
context - This is used to access local storage to cache the subscription, so it must currently be a viable context.
channel - A string identifier that determines which messages will cause a push notification to be sent to this client. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.
cls - This should be a subclass of Activity. An instance of this Activity is started when the user responds to this push notification. If you are not sure what to use here, just use your application's main Activity subclass.
icon - The icon to show for the notification.
Throws:
IllegalArgumentException - if the channel name is not valid.

unsubscribe

public static void unsubscribe(Context context,
                               String channel)
Cancels a previous call to subscribe. If the user is not subscribed to this channel, this is a no-op. This call does not require internet access. It returns without blocking.

Parameters:
context - A currently viable Context.
channel - The string defining the channel to unsubscribe from.

setDefaultPushCallback

public static void setDefaultPushCallback(Context context,
                                          Class<? extends Activity> cls)
Provides a default Activity class to handle pushes. Setting a default allows your program to handle pushes that aren't registered with a subscribe call. This can happen when your application changes its subscriptions directly through the ParseInstallation or via push-to-query.

Parameters:
context - This is used to access local storage to cache the subscription, so it must currently be a viable context.
cls - This should be a subclass of Activity. An instance of this Activity is started when the user responds to this push notification. If you are not sure what to use here, just use your application's main Activity subclass.

setDefaultPushCallback

public static void setDefaultPushCallback(Context context,
                                          Class<? extends Activity> cls,
                                          int icon)
Provides a default Activity class to handle pushes. Setting a default allows your program to handle pushes that aren't registered with a subscribe call. This can happen when your application changes its subscriptions directly through the ParseInstallation or via push-to-query.

Parameters:
context - This is used to access local storage to cache the subscription, so it must currently be a viable context.
cls - This should be a subclass of Activity. An instance of this Activity is started when the user responds to this push notification. If you are not sure what to use here, just use your application's main Activity subclass.
icon - The icon to show for the notification.

getSubscriptions

public static Set<String> getSubscriptions(Context context)
Accesses the current set of channels for which the current installation is subscribed. It is important to remember that the device may receive pushes by means other than channels. This method returns the local cache, so it returns without blocking on network IO. In rare circumstances this may be stale, but only after the installation was edited via the REST API using the master key.

Parameters:
context - A currently viable Context.
Returns:
A set containing all of the channels this application is currently subscribed to.

onCreate

public void onCreate()
Client code should not call onCreate directly.

Overrides:
onCreate in class Service

onStartCommand

public int onStartCommand(Intent intent,
                          int flags,
                          int startId)

onBind

public IBinder onBind(Intent intent)
onBind should not be called directly.

Specified by:
onBind in class Service

onDestroy

public void onDestroy()
Client code should not call onDestroy directly.

Overrides:
onDestroy in class Service