Introduce LockService interface to BriefcaseConnection

common/api/core-backend.api.md

@@ -20,6 +20,7 @@ import { BentleyError } from '@itwin/core-bentley';
 import { BentleyStatus } from '@itwin/core-bentley';
 import { BinaryImageSource } from '@itwin/core-common';
 import { BRepGeometryCreate } from '@itwin/core-common';
+import { BriefcaseConnectionProps } from '@itwin/core-common';
 import { BriefcaseId } from '@itwin/core-common';
 import { BriefcaseProps } from '@itwin/core-common';
 import { CalloutProps } from '@itwin/core-common';
@@ -621,6 +622,7 @@ export class BriefcaseDb extends IModelDb {
     revertAndPushChanges(arg: RevertChangesArgs): Promise<void>;
     // @internal (undocumented)
     get skipSyncSchemasOnPullAndPush(): boolean;
+    toJSON(): BriefcaseConnectionProps;
     // (undocumented)
     static tryFindByKey(key: string): BriefcaseDb | undefined;
     readonly txns: TxnManager;

common/api/core-common.api.md

@@ -851,6 +851,12 @@ export interface BRepThickenProps {
     frontDistance?: number;
 }
 
+// @public
+export interface BriefcaseConnectionProps extends IModelConnectionProps {
+    // @beta
+    readonly briefcaseId?: number;
+}
+
 // @public
 export interface BriefcaseDownloader {
     readonly briefcaseId: BriefcaseId;
@@ -5557,7 +5563,7 @@ export interface IpcAppFunctions {
     isRedoPossible: (key: string) => Promise<boolean>;
     isUndoPossible: (key: string) => Promise<boolean>;
     log: (_timestamp: number, _level: LogLevel, _category: string, _message: string, _metaData?: any) => Promise<void>;
-    openBriefcase: (args: OpenBriefcaseProps) => Promise<IModelConnectionProps>;
+    openBriefcase: (args: OpenBriefcaseProps) => Promise<BriefcaseConnectionProps>;
     openCheckpoint: (args: OpenCheckpointArgs) => Promise<IModelConnectionProps>;
     openSnapshot: (filePath: string, opts?: SnapshotOpenOptions) => Promise<IModelConnectionProps>;
     openStandalone: (filePath: string, openMode: OpenMode, opts?: StandaloneOpenOptions) => Promise<IModelConnectionProps>;

common/api/core-frontend.api.md

@@ -33,6 +33,7 @@ import { BentleyStatus } from '@itwin/core-bentley';
 import { BeTimePoint } from '@itwin/core-bentley';
 import { BeUiEvent } from '@itwin/core-bentley';
 import { BoundingSphere } from '@itwin/core-common';
+import { BriefcaseConnectionProps } from '@itwin/core-common';
 import { BriefcaseDownloader } from '@itwin/core-common';
 import { BriefcaseProps } from '@itwin/core-common';
 import { ByteStream } from '@itwin/core-bentley';
@@ -166,6 +167,7 @@ import { LinePixels } from '@itwin/core-common';
 import { Listener } from '@itwin/core-bentley';
 import { LocalBriefcaseProps } from '@itwin/core-common';
 import { Localization } from '@itwin/core-common';
+import { LockState } from '@itwin/core-common';
 import { LoggingMetaData } from '@itwin/core-bentley';
 import { LogLevel } from '@itwin/core-bentley';
 import { Loop } from '@itwin/core-geometry';
@@ -1725,8 +1727,10 @@ export interface BlankConnectionProps {
 
 // @public
 export class BriefcaseConnection extends IModelConnection {
-    protected constructor(props: IModelConnectionProps, openMode: OpenMode);
+    protected constructor(props: BriefcaseConnectionProps, openMode: OpenMode);
     abandonChanges(): Promise<void>;
+    // @beta
+    readonly briefcaseId?: number;
     close(): Promise<void>;
     get editingScope(): GraphicalEditingScope | undefined;
     // @beta
@@ -1740,9 +1744,13 @@ export class BriefcaseConnection extends IModelConnection {
     // (undocumented)
     protected _isClosed?: boolean;
     get iTwinId(): GuidString;
+    // @alpha
+    get locks(): LockService | undefined;
     // @internal
     readonly onBufferedModelChanges: BeEvent<(changedModelIds: Set<string>) => void>;
     static openFile(briefcaseProps: OpenBriefcaseProps): Promise<BriefcaseConnection>;
+    // @alpha
+    static openFile(briefcaseProps: OpenBriefcaseProps, lockServiceFactory?: LockServiceFactory): Promise<BriefcaseConnection>;
     static openStandalone(filePath: string, openMode?: OpenMode, opts?: StandaloneOpenOptions): Promise<BriefcaseConnection>;
     pullChanges(toIndex?: ChangesetIndex, options?: PullChangesOptions): Promise<void>;
     pushChanges(description: string): Promise<ChangesetIndexAndId>;
@@ -5786,6 +5794,16 @@ export enum LockedStates {
     Y_BM = 2
 }
 
+// @alpha
+export interface LockService {
+    checkElementLockAvailability(elementId: Id64String, lock: LockState): Promise<boolean>;
+    getExclusiveForeignLocks(): Promise<Id64Set>;
+    getSharedForeignLocks(): Promise<Id64Set>;
+}
+
+// @alpha
+export type LockServiceFactory = (iModel: BriefcaseConnection) => Promise<LockService>;
+
 // @internal
 export class LogoDecoration implements CanvasDecoration {
     // (undocumented)

common/api/summary/core-common.exports.csv

@@ -76,6 +76,7 @@ alpha;interface;BRepOffsetProps
 public;interface;BRepPrimitive
 alpha;interface;BRepRoundProps
 alpha;interface;BRepThickenProps
+public;interface;BriefcaseConnectionProps
 public;interface;BriefcaseDownloader
 public;type;BriefcaseId
 public;enum;BriefcaseIdValue

common/api/summary/core-frontend.exports.csv

@@ -352,6 +352,8 @@ public;enum;LocateFilterStatus
 public;class;LocateOptions
 public;class;LocateResponse
 internal;enum;LockedStates
+alpha;interface;LockService
+alpha;type;LockServiceFactory
 internal;class;LogoDecoration
 public;class;LookAndMoveTool
 public;interface;LookAtArgs

common/changes/@itwin/core-backend/gytis-frontend-api-for-locks_2026-03-05-11-40.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-backend",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-backend"
+}

common/changes/@itwin/core-common/gytis-frontend-api-for-locks_2026-03-05-11-40.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-common",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-common"
+}

common/changes/@itwin/core-frontend/gytis-frontend-api-for-locks_2026-03-05-11-40.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-frontend",
+      "comment": "New LockService interface and new BriefcaseConnection.locks property",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-frontend"
+}

core/backend/src/IModelDb.ts

@@ -15,7 +15,7 @@ import {
   Guid, GuidString, Id64, Id64Arg, Id64Array, Id64Set, Id64String, IModelStatus, JsonUtils, Logger, LogLevel, LRUMap, OpenMode
 } from "@itwin/core-bentley";
 import {
-  AxisAlignedBox3d, BRepGeometryCreate, BriefcaseId, BriefcaseIdValue, CategorySelectorProps, ChangesetHealthStats, ChangesetIdWithIndex, ChangesetIndexAndId, Code,
+  AxisAlignedBox3d, BRepGeometryCreate, BriefcaseConnectionProps, BriefcaseId, BriefcaseIdValue, CategorySelectorProps, ChangesetHealthStats, ChangesetIdWithIndex, ChangesetIndexAndId, Code,
   CodeProps, CreateEmptySnapshotIModelProps, CreateEmptyStandaloneIModelProps, CreateSnapshotIModelProps, DbQueryRequest, DisplayStyleProps,
   DomainOptions, EcefLocation, ECJsNames, ECSchemaProps, ECSqlReader, ElementAspectProps, ElementGeometryCacheOperationRequestProps, ElementGeometryCacheRequestProps, ElementGeometryCacheResponseProps, ElementGeometryRequest, ElementGraphicsRequestProps, ElementLoadProps, ElementProps, EntityMetaData, EntityProps, EntityQueryParams, FilePropertyProps, FontMap,
   GeoCoordinatesRequestProps, GeoCoordinatesResponseProps, GeometryContainmentRequestProps, GeometryContainmentResponseProps, IModel,
@@ -4126,6 +4126,11 @@ export class BriefcaseDb extends IModelDb {
     super.close(options);
     this.onClosed.raiseEvent();
   }
+
+  /** Convert this briefcase to a JSON representation. */
+  public override toJSON(): BriefcaseConnectionProps {
+    return { ...super.toJSON(), briefcaseId: this.briefcaseId };
+  }
 }
 
 /** Used to reattach Daemon from a user's accessToken for V2 checkpoints.

core/backend/src/IpcHost.ts

@@ -9,6 +9,7 @@
 import { IModelJsNative } from "@bentley/imodeljs-native";
 import { assert, BentleyError, IModelStatus, JsonUtils, Logger, LogLevel, OpenMode } from "@itwin/core-bentley";
 import {
+  BriefcaseConnectionProps,
   ChangesetIndex, ChangesetIndexAndId, EditingScopeNotifications, getPullChangesIpcChannel, IModelConnectionProps, IModelError, IModelNotFoundResponse, IModelRpcProps,
   ipcAppChannels, IpcAppFunctions, IpcAppNotifications, IpcInvokeReturn, IpcListener, IpcSocketBackend, iTwinChannel,
   OpenBriefcaseProps, OpenCheckpointArgs, PullChangesOptions, RemoveFunction, SnapshotOpenOptions, StandaloneOpenOptions, TileTreeContentIds, TxnNotifications,
@@ -225,7 +226,7 @@ class IpcAppHandler extends IpcHandler implements IpcAppFunctions {
   public async cancelElementGraphicsRequests(key: string, requestIds: string[]): Promise<void> {
     return IModelDb.findByKey(key)[_nativeDb].cancelElementGraphicsRequests(requestIds);
   }
-  public async openBriefcase(args: OpenBriefcaseProps): Promise<IModelConnectionProps> {
+  public async openBriefcase(args: OpenBriefcaseProps): Promise<BriefcaseConnectionProps> {
     const db = await BriefcaseDb.open(args);
     return db.toJSON();
   }

core/backend/src/test/standalone/iModelDb.test.ts

@@ -0,0 +1,43 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+
+import { GuidString } from "@itwin/core-bentley";
+import { BriefcaseConnectionProps } from "@itwin/core-common";
+import { assert } from "chai";
+import { BriefcaseDb, BriefcaseManager } from "../../core-backend";
+import { HubMock } from "../../internal/HubMock";
+import { KnownTestLocations } from "../KnownTestLocations";
+
+describe("BriefcaseDb", () => {
+  let iTwinId: GuidString;
+
+  before(() => {
+    HubMock.startup("BriefcaseDbTest", KnownTestLocations.outputDir);
+    iTwinId = HubMock.iTwinId;
+  });
+
+  after(() => HubMock.shutdown());
+
+  describe("toJSON", () => {
+    it("should include briefcaseId in the returned BriefcaseConnectionProps", async () => {
+      const iModelId = await HubMock.createNewIModel({ iModelName: "ToJsonTest", iTwinId });
+      const briefcaseProps = await BriefcaseManager.downloadBriefcase({ accessToken: "test token", iTwinId, iModelId });
+      const db = await BriefcaseDb.open({ fileName: briefcaseProps.fileName });
+
+      try {
+        const json: BriefcaseConnectionProps = db.toJSON();
+
+        assert.isDefined(json.briefcaseId);
+        assert.equal(json.briefcaseId, db.briefcaseId);
+
+        assert.isDefined(json.rootSubject);
+        assert.isDefined(json.key);
+        assert.isDefined(json.projectExtents);
+      } finally {
+        db.close();
+      }
+    });
+  });
+});

core/common/src/IModel.ts

@@ -111,6 +111,18 @@ export interface IModelProps {
  */
 export type IModelConnectionProps = IModelProps & IModelRpcProps;
 
+/** The properties returned by the backend when creating a new [[BriefcaseConnection]] from the frontend with Ipc.
+ * These properties describe the iModel held on the backend for thew newly formed connection and are used to construct a new
+ * [[BriefcaseConnection]] instance on the frontend to access it.
+ * @public
+ */
+export interface BriefcaseConnectionProps extends IModelConnectionProps {
+  /** The ID of the briefcase.
+   * @beta
+   */
+  readonly briefcaseId?: number;
+}
+
 /** The properties that can be supplied when creating a *new* iModel.
  * @public
  */

core/common/src/IpcAppProps.ts

@@ -12,7 +12,7 @@ import { OpenBriefcaseProps, OpenCheckpointArgs } from "./BriefcaseTypes";
 import { ChangedEntities } from "./ChangedEntities";
 import { ChangesetIdWithIndex, ChangesetIndex, ChangesetIndexAndId, ChangesetProps } from "./ChangesetProps";
 import { GeographicCRSProps } from "./geometry/CoordinateReferenceSystem";
-import { EcefLocationProps, IModelConnectionProps, IModelRpcProps, RootSubjectProps, SnapshotOpenOptions, StandaloneOpenOptions } from "./IModel";
+import { BriefcaseConnectionProps, EcefLocationProps, IModelConnectionProps, IModelRpcProps, RootSubjectProps, SnapshotOpenOptions, StandaloneOpenOptions } from "./IModel";
 import { ModelGeometryChangesProps } from "./ModelGeometryChanges";
 import { TxnProps } from "./TxnProps";
 
@@ -159,7 +159,7 @@ export interface IpcAppFunctions {
   log: (_timestamp: number, _level: LogLevel, _category: string, _message: string, _metaData?: any) => Promise<void>;
 
   /** see BriefcaseConnection.openFile */
-  openBriefcase: (args: OpenBriefcaseProps) => Promise<IModelConnectionProps>;
+  openBriefcase: (args: OpenBriefcaseProps) => Promise<BriefcaseConnectionProps>;
   /** see BriefcaseConnection.openStandalone */
   openCheckpoint: (args: OpenCheckpointArgs) => Promise<IModelConnectionProps>;
   /** see BriefcaseConnection.openStandalone */

core/frontend/src/BriefcaseConnection.ts

@@ -6,10 +6,10 @@
  * @module IModelConnection
  */
 
-import { assert, BeEvent, CompressedId64Set, Guid, GuidString, Id64String, IModelStatus, OpenMode } from "@itwin/core-bentley";
+import { assert, BeEvent, CompressedId64Set, Guid, GuidString, Id64Set, Id64String, IModelStatus, OpenMode } from "@itwin/core-bentley";
 import {
-  ChangesetIndex, ChangesetIndexAndId, getPullChangesIpcChannel, IModelConnectionProps, IModelError,
-  PullChangesOptions as IpcAppPullChangesOptions, OpenBriefcaseProps, StandaloneOpenOptions,
+  BriefcaseConnectionProps, ChangesetIndex, ChangesetIndexAndId, getPullChangesIpcChannel, IModelError,
+  PullChangesOptions as IpcAppPullChangesOptions, LockState, OpenBriefcaseProps, StandaloneOpenOptions,
 } from "@itwin/core-common";
 import { BriefcaseTxns } from "./BriefcaseTxns";
 import { GraphicalEditingScope } from "./GraphicalEditingScope";
@@ -191,6 +191,25 @@ class ModelChangeMonitor {
   }
 }
 
+/**
+ * Provides access to lock information in the iModel.
+ * @see [[BriefcaseConnection.locks]]
+ * @alpha
+ */
+export interface LockService {
+  /** Get all elements with exclusive locks owned by other briefcases. */
+  getExclusiveForeignLocks(): Promise<Id64Set>;
+  /** Get all elements with shared locks owned by other briefcases. */
+  getSharedForeignLocks(): Promise<Id64Set>;
+  /** Check whether it's possible to acquire a lock for the element. */
+  checkElementLockAvailability(elementId: Id64String, lock: LockState): Promise<boolean>;
+}
+
+/** Function for creating a [[LockService]] for a [[BriefcaseConnection]].
+ * @alpha
+ */
+export type LockServiceFactory = (iModel: BriefcaseConnection) => Promise<LockService>;
+
 /** Settings that can be used to control the behavior of [[Tool]]s that modify a [[BriefcaseConnection]].
  * For example, tools that want to create new elements can consult the briefcase's editor tool settings to
  * determine into which model and category to insert the elements.
@@ -249,6 +268,13 @@ export class BriefcaseEditorToolSettings {
 export class BriefcaseConnection extends IModelConnection {
   protected _isClosed?: boolean;
   private readonly _modelsMonitor: ModelChangeMonitor;
+  private _locks?: LockService;
+
+  /** The ID of the briefcase.
+   * @beta
+   */
+  public readonly briefcaseId?: number;
+
   /** Default settings that can be used to control the behavior of [[Tool]]s that modify this briefcase.
    * @beta
    */
@@ -257,6 +283,12 @@ export class BriefcaseConnection extends IModelConnection {
   /** Manages local changes to the briefcase via [Txns]($docs/learning/InteractiveEditing.md). */
   public readonly txns: BriefcaseTxns;
 
+  /** Information about locks held on this iModel.
+   * @note This is intended to be used by tools and other UI elements, to provide information about the current lock state. Implementations are expected to cache lock information and so may not reflect changes to locks immediately.
+   * @alpha
+   */
+  public get locks(): LockService | undefined { return this._locks; }
+
   public override isBriefcaseConnection(): this is BriefcaseConnection { return true; }
 
   /** The Guid that identifies the iTwin that owns this iModel. */
@@ -265,9 +297,10 @@ export class BriefcaseConnection extends IModelConnection {
   /** The Guid that identifies this iModel. */
   public override get iModelId(): GuidString { return super.iModelId ?? Guid.empty; } // GuidString | undefined for IModelConnection, but required for BriefcaseConnection
 
-  protected constructor(props: IModelConnectionProps, openMode: OpenMode) {
+  protected constructor(props: BriefcaseConnectionProps, openMode: OpenMode) {
     super(props);
     this._openMode = openMode;
+    this.briefcaseId = props.briefcaseId;
     this.txns = new BriefcaseTxns(this);
     this._modelsMonitor = new ModelChangeMonitor(this);
     if (OpenMode.ReadWrite === this._openMode)
@@ -277,9 +310,19 @@ export class BriefcaseConnection extends IModelConnection {
   }
 
   /** Open a BriefcaseConnection to a [BriefcaseDb]($backend). */
-  public static async openFile(briefcaseProps: OpenBriefcaseProps): Promise<BriefcaseConnection> {
+  public static async openFile(briefcaseProps: OpenBriefcaseProps): Promise<BriefcaseConnection>;
+
+  /** Open a BriefcaseConnection to a [BriefcaseDb]($backend).
+   * @alpha
+   */
+  public static async openFile(briefcaseProps: OpenBriefcaseProps, lockServiceFactory?: LockServiceFactory): Promise<BriefcaseConnection>
+
+  public static async openFile(briefcaseProps: OpenBriefcaseProps, lockServiceFactory?: LockServiceFactory): Promise<BriefcaseConnection> {
     const iModelProps = await IpcApp.appFunctionIpc.openBriefcase(briefcaseProps);
     const connection = new this({ ...briefcaseProps, ...iModelProps }, briefcaseProps.readonly ? OpenMode.Readonly : OpenMode.ReadWrite);
+    if (lockServiceFactory)
+      connection._locks = await lockServiceFactory(connection);
+
     IModelConnection.onOpen.raiseEvent(connection);
     return connection;
   }