WorldClock Module

The WorldClock module provides comprehensive functionality for managing world clocks on connected devices. It enables setting, querying, and deleting world clock entries with timezone information, allowing users to track time across multiple cities and regions with support for both 12-hour and 24-hour time formats.

Prerequisites

Device must be connected and authenticated before performing world clock operations
Device firmware must support world clock functionality
Valid timezone identifiers (IANA timezone database format) must be used for clock configuration

Data Models

TSWorldClockModel

World clock model for managing time zone information and city-based time tracking.

Property	Type	Description
`clockId`	`UInt8`	Unique identifier for the clock entry (0-255). A random number assigned to each world clock entry.
`cityName`	`NSString *`	The name of the city for the world clock.
`timeZoneIdentifier`	`NSString *`	The IANA time zone identifier (e.g., "Asia/Shanghai").
`utcOffsetInSeconds`	`NSInteger`	UTC offset in seconds for this time zone. Range is -43200 to +43200. Positive values indicate time zones ahead of UTC, negative values indicate time zones behind UTC.

Enumerations

No public enumerations are defined in this module.

Callback Types

Type	Description
`void (^)(NSArray<TSWorldClockModel > _Nullable allWorldClocks, NSError * _Nullable error)`	Callback block that returns an array of world clock models and any error that occurred during query operations.

API Reference

Get the maximum number of supported world clocks

Retrieve the maximum number of world clock entries that can be configured on the device.

- (NSInteger)supportMaxWorldClockCount;

Parameter	Type	Description
(return)	`NSInteger`	The maximum number of world clocks that can be set on the device.

Code Example:

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;
NSInteger maxCount = [worldClock supportMaxWorldClockCount];
TSLog(@"Device supports up to %ld world clocks", (long)maxCount);

Get the maximum city-name byte length

- (NSInteger)supportMaxCityNameLength;

Returns the maximum UTF-8 byte length accepted for cityName; 0 means unsupported or unavailable.

Set world clocks for the device

Configure one or more world clock entries on the device. This operation will update the world clock settings with the provided models.

- (void)setAllWorldClocks:(NSArray<TSWorldClockModel *> *_Nullable)allWorldClocks
                completion:(TSCompletionBlock)completion;

Parameter	Type	Description
`worldClocks`	`NSArray<TSWorldClockModel > `	Array of world clock models to be set on the device.
`completion`	`TSCompletionBlock`	Callback block to be executed after the operation completes.

Code Example:

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;

TSWorldClockModel *shanghaiClock = [TSWorldClockModel modelWithClockId:1
                                                               cityName:@"Shanghai"
                                                     timeZoneIdentifier:@"Asia/Shanghai"
                                                     utcOffsetInSeconds:28800];

TSWorldClockModel *newYorkClock = [TSWorldClockModel modelWithClockId:2
                                                                cityName:@"New York"
                                                      timeZoneIdentifier:@"America/New_York"
                                                      utcOffsetInSeconds:-18000];

[worldClock setAllWorldClocks:@[shanghaiClock, newYorkClock]
                    completion:^(BOOL success, NSError * _Nullable error) {
    if (error) {
        TSLog(@"Failed to set world clocks: %@", error.localizedDescription);
    } else {
        TSLog(@"World clocks set successfully");
    }
}];

Query all world clocks from the device

Retrieve all world clock entries currently configured on the device.

- (void)getAllWorldClocksCompletion:(_Nullable TSWorldClockResultBlock)completion;

Parameter	Type	Description
`completion`	`void (^)(NSArray<TSWorldClockModel > _Nullable allWorldClocks, NSError * _Nullable error)`	Callback block that returns an array of all world clock models and any error that occurred.

Code Example:

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;

[worldClock getAllWorldClocksCompletion:^(NSArray<TSWorldClockModel *> *allWorldClocks, NSError * _Nullable error) {
    if (error) {
        TSLog(@"Failed to query world clocks: %@", error.localizedDescription);
    } else {
        for (TSWorldClockModel *clock in allWorldClocks) {
            TSLog(@"Clock: %@ (ID: %d, Offset: %ld seconds)", 
                  clock.cityName, clock.clockId, (long)clock.utcOffsetInSeconds);
        }
    }
}];

Delete a specific world clock from the device

Remove a single world clock entry from the device.

- (void)deleteWorldClockWithId:(UInt8)clockId completion:(_Nullable TSCompletionBlock)completion;

Parameter	Type	Description
`clockId`	`UInt8`	ID obtained from `getAllWorldClocksCompletion:`.
`completion`	`TSCompletionBlock`	Callback block to be executed after the operation completes.

Code Example:

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;

TSWorldClockModel *clockToDelete = [TSWorldClockModel modelWithClockId:1
                                                                 cityName:@"Shanghai"
                                                       timeZoneIdentifier:@"Asia/Shanghai"
                                                       utcOffsetInSeconds:28800];

[worldClock deleteWorldClockWithId:clockToDelete.clockId completion:^(BOOL success, NSError * _Nullable error) {
    if (error) {
        TSLog(@"Failed to delete world clock: %@", error.localizedDescription);
    } else {
        TSLog(@"World clock deleted successfully");
    }
}];

Delete all world clocks from the device

Remove all world clock entries currently configured on the device.

- (void)deleteAllWorldClocksWithCompletion:(_Nullable TSCompletionBlock)completion;

Parameter	Type	Description
`completion`	`TSCompletionBlock`	Callback block to be executed after the operation completes.

Code Example:

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;

[worldClock deleteAllWorldClocksWithCompletion:^(BOOL success, NSError * _Nullable error) {
    if (error) {
        TSLog(@"Failed to delete all world clocks: %@", error.localizedDescription);
    } else {
        TSLog(@"All world clocks deleted successfully");
    }
}];

Add one world clock

- (void)addWorldClock:(TSWorldClockModel *)worldClock
            completion:(_Nullable TSCompletionBlock)completion;

The SDK preserves existing clocks and assigns the first available clockId. The request fails after supportMaxWorldClockCount is reached.

Observe world-clock changes

- (void)registerWorldClocksDidChangedBlock:(_Nullable TSWorldClockResultBlock)completion;

Only one listener is retained; registering again replaces the previous listener. Pass nil to clear it.

Create a world clock model instance

Initialize a new world clock model with the specified parameters.

+ (instancetype)modelWithClockId:(UInt8)clockId
                        cityName:(NSString *)cityName
              timeZoneIdentifier:(NSString *)timeZoneIdentifier
              utcOffsetInSeconds:(NSInteger)utcOffsetInSeconds;

Parameter	Type	Description
`clockId`	`UInt8`	The unique identifier for the clock entry (0-255).
`cityName`	`NSString *`	The name of the city.
`timeZoneIdentifier`	`NSString *`	The IANA time zone identifier.
`utcOffsetInSeconds`	`NSInteger`	The UTC offset in seconds (-43200 to +43200).
(return)	`TSWorldClockModel *`	A new TSWorldClockModel instance.

Code Example:

TSWorldClockModel *tokyoClock = [TSWorldClockModel modelWithClockId:3
                                                            cityName:@"Tokyo"
                                                  timeZoneIdentifier:@"Asia/Tokyo"
                                                  utcOffsetInSeconds:32400];

TSLog(@"Created clock for %@", tokyoClock.cityName);

Compare two world clock models

Check if two world clock models are equal based on their properties.

- (BOOL)isEqualToWorldClockModel:(TSWorldClockModel *)otherModel;

Parameter	Type	Description
`otherModel`	`TSWorldClockModel *`	The other world clock model to compare with.
(return)	`BOOL`	YES if the models are equal, NO otherwise.

Code Example:

TSWorldClockModel *clock1 = [TSWorldClockModel modelWithClockId:1
                                                        cityName:@"London"
                                              timeZoneIdentifier:@"Europe/London"
                                              utcOffsetInSeconds:0];

TSWorldClockModel *clock2 = [TSWorldClockModel modelWithClockId:1
                                                        cityName:@"London"
                                              timeZoneIdentifier:@"Europe/London"
                                              utcOffsetInSeconds:0];

if ([clock1 isEqualToWorldClockModel:clock2]) {
    TSLog(@"The two clocks are identical");
} else {
    TSLog(@"The two clocks are different");
}

Important Notes

The clockId property must be unique for each world clock entry on the device and should be in the range of 0-255.
The timeZoneIdentifier must be a valid IANA timezone identifier (e.g., "Asia/Shanghai", "America/New_York", "Europe/London"). Invalid identifiers will cause operation failures.
The utcOffsetInSeconds must be synchronized with the timeZoneIdentifier. Mismatched values may result in incorrect time display. Acceptable range is -43200 seconds (UTC-12) to +43200 seconds (UTC+12).
Before setting world clocks, check the device's maximum supported count using supportMaxWorldClockCount to avoid exceeding device limitations.
The timeFormat and geographic coordinate properties (longitude, latitude) are marked as NS_UNAVAILABLE and should not be used in current implementation.
Always check for errors in callback completion blocks to handle network failures or device-specific errors appropriately.
World clock operations are asynchronous; ensure the device remains connected until the completion block is called.
When updating world clocks, the entire set should be provided in setAllWorldClocks:completion: because it replaces the current collection.
The TSWorldClockModel class does not support direct initialization via init, new, or copy operations; use the provided factory methods instead.
Query world clocks regularly to synchronize local application state with device settings, as external modifications may occur.

Prerequisites​

Data Models​

TSWorldClockModel​

Enumerations​

Callback Types​

API Reference​

Get the maximum number of supported world clocks​

Get the maximum city-name byte length​

Set world clocks for the device​

Query all world clocks from the device​

Delete a specific world clock from the device​

Delete all world clocks from the device​

Add one world clock​

Observe world-clock changes​

Create a world clock model instance​

Compare two world clock models​

Important Notes​

Prerequisites

Data Models

TSWorldClockModel

Enumerations

Callback Types

API Reference

Get the maximum number of supported world clocks

Get the maximum city-name byte length

Set world clocks for the device

Query all world clocks from the device

Delete a specific world clock from the device

Delete all world clocks from the device

Add one world clock

Observe world-clock changes

Create a world clock model instance

Compare two world clock models

Important Notes