Core Device Info Sync Time

Sync Device Time

Synchronize the connected device's internal clock with the current time. Use this operation when the device needs to align its clock without supplying a specific date.

Prerequisites

Before synchronizing the device time, ensure:

• The device is connected and in a stable state
• The device supports the DeviceInfoAPI protocol

API Reference

Framework

AIBuds.xcframework

Import

In the files where you want to use the SDK, import the main framework:

Swift

import AIBuds

Objective-C

#import <AIBuds/AIBuds.h>
#import <AIBuds/AIBuds-Swift.h>

Protocol

The syncDeviceTime method is defined in DeviceInfoAPI. The protocol inherits from the base device API protocol.

Swift

/// The protocol for device information related API.
protocol DeviceInfoAPI: DeviceAPI {
    /// Synchronizes the device time with the current time.
    /// - Parameters:
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: `true` if the operation was successful; otherwise `false`.
    ///     - statusCode: The status code returned by the device. `nil` if the operation failed.
    ///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    func syncDeviceTime(_ completion: AIBudsStatusCodeCompletionHandler?)
}

Objective-C

/// The protocol for device information related API.
@protocol AIBudsDeviceInfoAPI <AIBudsDeviceAPI>
    /// Synchronizes the device time with the current time.
    /// - Parameters:
    ///   - completion: A closure that is called when the operation completes.
    ///     - success: `true` if the operation was successful; otherwise `false`.
    ///     - statusCode: The status code returned by the device. `nil` if the operation failed.
    ///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
    - (void)syncDeviceTimeWithCompletion:(AIBudsStatusCodeCompletionHandler _Nullable)completion;
@end

Instance Method

Synchronizes the device time with the current time.

Swift

/// Synchronizes the device time with the current time.
/// - Parameters:
///   - completion: A closure that is called when the operation completes.
///     - success: `true` if the operation was successful; otherwise `false`.
///     - statusCode: The status code returned by the device. `nil` if the operation failed.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
func syncDeviceTime(_ completion: AIBudsStatusCodeCompletionHandler?)

Objective-C

/// Synchronizes the device time with the current time.
/// - Parameters:
///   - completion: A closure that is called when the operation completes.
///     - success: `true` if the operation was successful; otherwise `false`.
///     - statusCode: The status code returned by the device. `nil` if the operation failed.
///     - error: An `NSError` object that describes the error that occurred, or `nil` if the operation was successful.
- (void)syncDeviceTimeWithCompletion:(AIBudsStatusCodeCompletionHandler _Nullable)completion;

Parameters

Parameter	Type	Description
completion	AIBudsStatusCodeCompletionHandler?	Optional completion handler called when the operation finishes.

Callback Parameters:

Name	Type	Description
success	Bool / BOOL	true if the operation succeeded; otherwise false.
statusCode	NSNumber?	The status code returned by the device. The SDK documents this value as nil when the operation fails.
error	NSError?	Error details if the operation failed; otherwise nil.

Return Value

This method does not return a value directly. The result is provided through the completion handler.

Usage Examples

Swift

import AIBuds

final class DeviceManager {

    /// The connected device
    weak var device: DeviceConvertible?

    /// Synchronizes the connected device with the current time
    func synchronizeDeviceTime() {
        guard let device = device as? DeviceInfoAPI else {
            print("Device does not support time synchronization")
            return
        }

        device.syncDeviceTime { success, statusCode, error in
            if !success {
                print(
                    "Time synchronization failed: " +
                    (error?.localizedDescription ?? "Unknown error")
                )
                return
            }

            print(
                "Time synchronized successfully. Status code: " +
                (statusCode?.stringValue ?? "N/A")
            )
        }
    }
}

Objective-C

#import <AIBuds/AIBuds.h>
#import <AIBuds/AIBuds-Swift.h>

@interface DeviceManager ()

/// The connected device
@property (weak, nonatomic) id<AIBudsDeviceConvertible> device;

@end

@implementation DeviceManager

- (void)synchronizeDeviceTime {
    id<AIBudsDeviceInfoAPI> device = (id<AIBudsDeviceInfoAPI>)self.device;

    if (![device conformsToProtocol:@protocol(AIBudsDeviceInfoAPI)]) {
        NSLog(@"Device does not support time synchronization");
        return;
    }

    [device syncDeviceTimeWithCompletion:^(
        BOOL success,
        NSNumber * _Nullable statusCode,
        NSError * _Nullable error
    ) {
        if (!success) {
            NSLog(@"Time synchronization failed: %@",
                  error.localizedDescription ?: @"Unknown error");
            return;
        }

        NSLog(@"Time synchronized successfully. Status code: %@",
              statusCode ?: @"N/A");
    }];
}

@end

Error Handling

The completion handler reports the result of the synchronization:

1. Check success before treating the operation as complete.
2. When success is false, use error for failure details.
3. Preserve statusCode for diagnostics or device-specific handling when it is available.
4. Do not assume a particular error or status code unless it is documented for the target device.

Best Practices

1. Check Protocol Conformance: Confirm that the device supports DeviceInfoAPI before calling the method.

2. Call After Connection: Synchronize only after the device is connected and ready.

3. Handle All Completion Values: Evaluate success, statusCode, and error instead of relying on error alone.

4. Update UI on the Main Queue: Dispatch completion-driven UIKit updates to the main queue.

Notes

• syncDeviceTime does not accept a target Date; use setDeviceTime(to:completion:) when you need to provide one.
• The public API describes synchronization with the current time but does not define a UTC conversion contract.
• Support for time synchronization can vary by device model and firmware.