community-cordova-plugin-magnetometer 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.3] - 2025-02-04
+
+### Changed
+
+- Error handling now returns structured error objects with `code` and `message` properties
+- Error code `3` (NOT_AVAILABLE) is now consistently returned when magnetometer sensor is unavailable
+- Improved error detection for "sensor not available" scenarios across both Android and iOS
+
+### Fixed
+
+- Consistent error format across platforms (Android and iOS now both return `{code: 3, message: "..."}` for unavailable sensor)
+
 ## [1.0.0] - 2025-01-20
 
 ### Added

package/README.md

@@ -242,6 +242,43 @@ Get the total magnetic field strength (magnitude).
 
 **Returns:** Field strength in microteslas (μT).
 
+## Error Handling
+
+When errors occur, the plugin returns structured error objects:
+
+```typescript
+interface MagnetometerError {
+    code: number;
+    message: string;
+}
+```
+
+### Error Codes
+
+| Code | Constant | Description |
+|------|----------|-------------|
+| `3` | `NOT_AVAILABLE` | Magnetometer sensor is not available on the device |
+
+### Example Error Handling
+
+```typescript
+MagnetometerPlugin.watchReadings(
+    (reading) => {
+        console.log('Reading:', reading);
+    },
+    (error) => {
+        if (error.code === 3) {
+            // Sensor not available - show user-friendly message
+            console.log('This device does not have a magnetic sensor');
+        } else {
+            // Other error
+            console.error('Magnetometer error:', error.message);
+        }
+    },
+    { frequency: 100 }
+);
+```
+
 ## Interfaces
 
 ### IMagnetometerReading

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "community-cordova-plugin-magnetometer",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Cordova plugin to access the device magnetometer (compass) sensor",
   "main": "./types/index.d.ts",
   "types": "./types/index.d.ts",

package/src/android/Magnetometer.java

@@ -20,6 +20,9 @@ public class Magnetometer extends CordovaPlugin implements SensorEventListener {
 
     private static final String LOG_TAG = "Magnetometer";
 
+    // Error codes - matching DeviceOrientation plugin convention
+    private static final int ERROR_NOT_AVAILABLE = 3;
+
     private SensorManager sensorManager;
     private Sensor magnetometer;
     private Sensor rotationVector;
@@ -96,7 +99,7 @@ public class Magnetometer extends CordovaPlugin implements SensorEventListener {
 
     private void getReading(final CallbackContext callbackContext) {
         if (magnetometer == null) {
-            callbackContext.error("Magnetometer not available");
+            sendError(callbackContext, ERROR_NOT_AVAILABLE, "Magnetometer not available");
             return;
         }
 
@@ -146,7 +149,7 @@ public class Magnetometer extends CordovaPlugin implements SensorEventListener {
 
     private void getHeading(final CallbackContext callbackContext) {
         if (magnetometer == null) {
-            callbackContext.error("Magnetometer not available");
+            sendError(callbackContext, ERROR_NOT_AVAILABLE, "Magnetometer not available");
             return;
         }
 
@@ -217,7 +220,7 @@ public class Magnetometer extends CordovaPlugin implements SensorEventListener {
 
     private void watchReadings(CallbackContext callbackContext, final int frequency) {
         if (magnetometer == null) {
-            callbackContext.error("Magnetometer not available");
+            sendError(callbackContext, ERROR_NOT_AVAILABLE, "Magnetometer not available");
             return;
         }
 
@@ -246,7 +249,7 @@ public class Magnetometer extends CordovaPlugin implements SensorEventListener {
 
     private void watchHeading(CallbackContext callbackContext, final int frequency) {
         if (magnetometer == null) {
-            callbackContext.error("Magnetometer not available");
+            sendError(callbackContext, ERROR_NOT_AVAILABLE, "Magnetometer not available");
             return;
         }
 
@@ -388,7 +391,7 @@ public class Magnetometer extends CordovaPlugin implements SensorEventListener {
 
     private void getFieldStrength(final CallbackContext callbackContext) {
         if (magnetometer == null) {
-            callbackContext.error("Magnetometer not available");
+            sendError(callbackContext, ERROR_NOT_AVAILABLE, "Magnetometer not available");
             return;
         }
 
@@ -507,6 +510,38 @@ public class Magnetometer extends CordovaPlugin implements SensorEventListener {
         }
     }
 
+    /**
+     * Send a structured error with code and message
+     */
+    private void sendError(CallbackContext callbackContext, int code, String message) {
+        try {
+            JSONObject error = new JSONObject();
+            error.put("code", code);
+            error.put("message", message);
+            callbackContext.error(error);
+        } catch (JSONException e) {
+            callbackContext.error(message);
+        }
+    }
+
+    /**
+     * Send a structured error with code and message, keeping callback alive
+     */
+    private void sendErrorKeepCallback(CallbackContext callbackContext, int code, String message) {
+        try {
+            JSONObject error = new JSONObject();
+            error.put("code", code);
+            error.put("message", message);
+            PluginResult result = new PluginResult(PluginResult.Status.ERROR, error);
+            result.setKeepCallback(true);
+            callbackContext.sendPluginResult(result);
+        } catch (JSONException e) {
+            PluginResult result = new PluginResult(PluginResult.Status.ERROR, message);
+            result.setKeepCallback(true);
+            callbackContext.sendPluginResult(result);
+        }
+    }
+
     @Override
     public void onReset() {
         if (watchCallbackContext != null) {

package/src/ios/CDVMagnetometer.m

@@ -1,5 +1,8 @@
 #import "CDVMagnetometer.h"
 
+// Error codes - matching DeviceOrientation plugin convention
+static const int ERROR_NOT_AVAILABLE = 3;
+
 @implementation CDVMagnetometer
 
 - (void)pluginInitialize {
@@ -10,6 +13,27 @@
     self.calibrationNeeded = NO;
 }
 
+#pragma mark - Error Helpers
+
+- (void)sendErrorWithCode:(int)code message:(NSString *)message callbackId:(NSString *)callbackId {
+    NSDictionary *error = @{
+        @"code": @(code),
+        @"message": message
+    };
+    CDVPluginResult *result = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsDictionary:error];
+    [self.commandDelegate sendPluginResult:result callbackId:callbackId];
+}
+
+- (void)sendErrorWithCode:(int)code message:(NSString *)message callbackId:(NSString *)callbackId keepCallback:(BOOL)keepCallback {
+    NSDictionary *error = @{
+        @"code": @(code),
+        @"message": message
+    };
+    CDVPluginResult *result = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsDictionary:error];
+    [result setKeepCallbackAsBool:keepCallback];
+    [self.commandDelegate sendPluginResult:result callbackId:callbackId];
+}
+
 #pragma mark - Availability Check
 
 - (void)isAvailable:(CDVInvokedUrlCommand *)command {
@@ -25,8 +49,7 @@
 - (void)getReading:(CDVInvokedUrlCommand *)command {
     [self.commandDelegate runInBackground:^{
         if (!self.motionManager.magnetometerAvailable) {
-            CDVPluginResult *result = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Magnetometer not available"];
-            [self.commandDelegate sendPluginResult:result callbackId:command.callbackId];
+            [self sendErrorWithCode:ERROR_NOT_AVAILABLE message:@"Magnetometer not available" callbackId:command.callbackId];
             return;
         }
 
@@ -66,8 +89,7 @@
 - (void)getHeading:(CDVInvokedUrlCommand *)command {
     [self.commandDelegate runInBackground:^{
         if (![CLLocationManager headingAvailable]) {
-            CDVPluginResult *result = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Heading not available"];
-            [self.commandDelegate sendPluginResult:result callbackId:command.callbackId];
+            [self sendErrorWithCode:ERROR_NOT_AVAILABLE message:@"Heading not available" callbackId:command.callbackId];
             return;
         }
 
@@ -108,8 +130,7 @@
 
 - (void)watchReadings:(CDVInvokedUrlCommand *)command {
     if (!self.motionManager.deviceMotionAvailable) {
-        CDVPluginResult *result = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Device motion not available"];
-        [self.commandDelegate sendPluginResult:result callbackId:command.callbackId];
+        [self sendErrorWithCode:ERROR_NOT_AVAILABLE message:@"Device motion not available" callbackId:command.callbackId];
         return;
     }
 
@@ -169,8 +190,7 @@
 
 - (void)watchHeading:(CDVInvokedUrlCommand *)command {
     if (![CLLocationManager headingAvailable]) {
-        CDVPluginResult *result = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Heading not available"];
-        [self.commandDelegate sendPluginResult:result callbackId:command.callbackId];
+        [self sendErrorWithCode:ERROR_NOT_AVAILABLE message:@"Heading not available" callbackId:command.callbackId];
         return;
     }
 
@@ -288,8 +308,7 @@
 - (void)getFieldStrength:(CDVInvokedUrlCommand *)command {
     [self.commandDelegate runInBackground:^{
         if (!self.motionManager.magnetometerAvailable) {
-            CDVPluginResult *result = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR messageAsString:@"Magnetometer not available"];
-            [self.commandDelegate sendPluginResult:result callbackId:command.callbackId];
+            [self sendErrorWithCode:ERROR_NOT_AVAILABLE message:@"Magnetometer not available" callbackId:command.callbackId];
             return;
         }