From 1ef13dc7129f56afa66e2432102500011131e666 Mon Sep 17 00:00:00 2001 From: Aleksander Nowakowski Date: Wed, 22 Jul 2015 14:41:39 +0200 Subject: [PATCH] More documentation added. --- .../android/dfu/DfuBaseService.java | 30 +++++++------------ .../android/dfu/DfuLogListener.java | 4 +++ .../android/dfu/DfuProgressListener.java | 4 +++ .../android/dfu/DfuServiceListenerHelper.java | 9 ++++++ 4 files changed, 28 insertions(+), 19 deletions(-) diff --git a/dfu/src/main/java/no/nordicsemi/android/dfu/DfuBaseService.java b/dfu/src/main/java/no/nordicsemi/android/dfu/DfuBaseService.java index 0419bd5..6cd2b63 100644 --- a/dfu/src/main/java/no/nordicsemi/android/dfu/DfuBaseService.java +++ b/dfu/src/main/java/no/nordicsemi/android/dfu/DfuBaseService.java @@ -57,10 +57,11 @@ import java.io.FileNotFoundException; import java.io.IOException; import java.io.InputStream; import java.lang.reflect.Method; -import java.security.InvalidParameterException; import java.util.Locale; import java.util.UUID; +import no.nordicsemi.android.dfu.internal.ArchiveInputStream; +import no.nordicsemi.android.dfu.internal.HexInputStream; import no.nordicsemi.android.dfu.internal.exception.DeviceDisconnectedException; import no.nordicsemi.android.dfu.internal.exception.DfuException; import no.nordicsemi.android.dfu.internal.exception.HexFileValidationException; @@ -68,8 +69,6 @@ import no.nordicsemi.android.dfu.internal.exception.RemoteDfuException; import no.nordicsemi.android.dfu.internal.exception.UnknownResponseException; import no.nordicsemi.android.dfu.internal.exception.UploadAbortedException; import no.nordicsemi.android.dfu.internal.scanner.BootloaderScannerFactory; -import no.nordicsemi.android.dfu.internal.ArchiveInputStream; -import no.nordicsemi.android.dfu.internal.HexInputStream; import no.nordicsemi.android.error.GattError; /** @@ -79,25 +78,18 @@ import no.nordicsemi.android.error.GattError; * To run the service to your application extend it in your project and overwrite the missing method. Remember to add your class to the AndroidManifest.xml file. *

*

- * Start the service with the following parameters: + * The {@link DfuServiceInitiator} object should be used to start the DFU Service. *

* 

- * final Intent service = new Intent(this, yourClass);
- * service.putExtra(EXTRA_DEVICE_ADDRESS, mSelectedDevice.getAddress()); // Target device address
- * service.putExtra(EXTRA_DEVICE_NAME, mSelectedDevice.getName()); // This name will be shown on the notification
- * service.putExtra(EXTRA_FILE_MIME_TYPE, mFileType == TYPE_AUTO ? YourMIME_TYPE_ZIP : YourMIME_TYPE_OCTET_STREAM);
- * service.putExtra(EXTRA_FILE_TYPE, mFileType);
- * service.putExtra(EXTRA_FILE_PATH, mFilePath);
- * service.putExtra(EXTRA_FILE_URI, mFileStreamUri);
- * // optionally
- * service.putExtra(EXTRA_INIT_FILE_PATH, mInitFilePath);
- * service.putExtra(EXTRA_INIT_FILE_URI, mInitFileStreamUri);
- * service.putExtra(EXTRA_RESTORE_BOND, mRestoreBond);
- * startService(service);
+ * final DfuServiceInitiator starter = new DfuServiceInitiator(mSelectedDevice.getAddress())
+ * 		.setDeviceName(mSelectedDevice.getName())
+ * 		.setKeepBond(keepBond)
+ * 		.setZip(mFileStreamUri, mFilePath)
+ *		.start(this, DfuService.class);
  *
- *

- * The {@link #EXTRA_FILE_MIME_TYPE} and {@link #EXTRA_FILE_TYPE} parameters are optional. If not provided the application upload from HEX/BIN file is assumed. - * The service API is compatible with previous versions. + *

+ * You may register the progress and log listeners using the {@link DfuServiceListenerHelper} helper class. See {@link DfuProgressListener} and {@link DfuLogListener} for + * more information. *

*

* The service will show its progress on the notification bar and will send local broadcasts to the application. diff --git a/dfu/src/main/java/no/nordicsemi/android/dfu/DfuLogListener.java b/dfu/src/main/java/no/nordicsemi/android/dfu/DfuLogListener.java index c1f777e..cb25392 100644 --- a/dfu/src/main/java/no/nordicsemi/android/dfu/DfuLogListener.java +++ b/dfu/src/main/java/no/nordicsemi/android/dfu/DfuLogListener.java @@ -22,6 +22,10 @@ package no.nordicsemi.android.dfu; +/** + * Listener for log events. This listener should be used instead of creating the BroadcastReceiver on your own. + * @see DfuServiceListenerHelper + */ public interface DfuLogListener { /** * Method called when a log event was sent from the DFU service. diff --git a/dfu/src/main/java/no/nordicsemi/android/dfu/DfuProgressListener.java b/dfu/src/main/java/no/nordicsemi/android/dfu/DfuProgressListener.java index 2cb3f7b..0a3ce7b 100644 --- a/dfu/src/main/java/no/nordicsemi/android/dfu/DfuProgressListener.java +++ b/dfu/src/main/java/no/nordicsemi/android/dfu/DfuProgressListener.java @@ -22,6 +22,10 @@ package no.nordicsemi.android.dfu; +/** + * Listener for status, progress and error events. This listener should be used instead of creating the BroadcastReceiver on your own. + * @see DfuServiceListenerHelper + */ public interface DfuProgressListener { /** diff --git a/dfu/src/main/java/no/nordicsemi/android/dfu/DfuServiceListenerHelper.java b/dfu/src/main/java/no/nordicsemi/android/dfu/DfuServiceListenerHelper.java index d561b2c..9f46fec 100644 --- a/dfu/src/main/java/no/nordicsemi/android/dfu/DfuServiceListenerHelper.java +++ b/dfu/src/main/java/no/nordicsemi/android/dfu/DfuServiceListenerHelper.java @@ -33,6 +33,15 @@ import java.util.Map; import no.nordicsemi.android.error.GattError; +/** + * A helper class that should be used to register listeners for DFU Service broadcast events. + * The {@link DfuProgressListener} should be registered to listen for DFU status updates and errors, while the {@link DfuLogListener} listener receives the log updates. + * Listeners may be registered for a specified device (given with device address) or for any device. Keep in mind, that while updating the SoftDevice using the buttonless update + * the device may change its address in the bootloader mode. + * + *

Use {@link #registerProgressListener(Context, DfuProgressListener)} or {@link #registerLogListener(Context, DfuLogListener)} to register your listeners. Remember about unregistering them + * when your context is destroyed.

+ */ public class DfuServiceListenerHelper { private static LogBroadcastReceiver mLogBroadcastReceiver; private static ProgressBroadcastsReceiver mProgressBroadcastReceiver;