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

Swift

import AIBuds

Objective-C

Objective-C

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

Protocol

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

Swift

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

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

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

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

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

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBuds/AIBuds.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.