Set Device Time

Set the connected device's internal clock to a specific date and time supplied by your application.

Prerequisites

Before setting the device time, ensure:

• The device is connected and in a stable state
• The device supports the DeviceInfoAPI protocol
• The target Date represents the time your application intends to send

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 setDeviceTime 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 {
    /// Sets the device's system time.
    /// - Parameters:
    ///   - date: The target time to set on the device.
    ///   - 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 setDeviceTime(
        to date: Date,
        completion: AIBudsStatusCodeCompletionHandler?
    )
}

Objective-C

Objective-C

/// The protocol for device information related API.
@protocol AIBudsDeviceInfoAPI <AIBudsDeviceAPI>
/// Sets the device's system time.
/// - Parameters:
///   - date: The target time to set on the device.
///   - 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)setDeviceTime:(NSDate *_Nonnull)date
           completion:(AIBudsStatusCodeCompletionHandler _Nullable)completion;
@end

Instance Method

Sets the device's system time to the supplied date.

Swift

Swift

/// Sets the device's system time.
/// - Parameters:
///   - date: The target time to set on the device.
///   - 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 setDeviceTime(
    to date: Date,
    completion: AIBudsStatusCodeCompletionHandler?
)

Objective-C

Objective-C

/// Sets the device's system time.
/// - Parameters:
///   - date: The target time to set on the device.
///   - 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)setDeviceTime:(NSDate *_Nonnull)date
           completion:(AIBudsStatusCodeCompletionHandler _Nullable)completion;

Parameters

Parameter	Type	Description
date	Date / NSDate	The target time to set on the device.
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?

    /// Sets the connected device to the supplied date
    func setDeviceTime(to date: Date) {
        guard let device = device as? DeviceInfoAPI else {
            print("Device does not support setting the time")
            return
        }

        device.setDeviceTime(to: date) { success, statusCode, error in
            if !success {
                print(
                    "Failed to set device time: " + (error?.localizedDescription ?? "Unknown error")
                )
                return
            }

            print(
                "Device time set 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)setDeviceTime:(NSDate *)date {
    id<AIBudsDeviceInfoAPI> device = (id<AIBudsDeviceInfoAPI>)self.device;

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

    [device
        setDeviceTime:date
           completion:^(BOOL success, NSNumber *_Nullable statusCode, NSError *_Nullable error) {
               if (!success) {
                   NSLog(@"Failed to set device time: %@",
                         error.localizedDescription ?: @"Unknown error");
                   return;
               }

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

@end

Error Handling

The completion handler reports the result of the operation:

1. Check success before treating the target time as applied.
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. Validate the Target Date: Ensure the application is sending the intended date and time.

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

3. Call After Connection: Set the time only after the device is connected and ready.

4. Handle All Completion Values: Evaluate success, statusCode, and error.

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

Notes

• The public API accepts a Date but does not define a UTC conversion contract. Avoid adding timezone assumptions that are not specified by the target device.
• Use syncDeviceTime(_:) when the device only needs to synchronize with the current time.
• Support for setting a target time can vary by device model and firmware.