xref: /interface/sdk-js/api/@ohos.data.DataShareResultSet.d.ts

/*
 * Copyright (c) 2022 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @file
 * @kit ArkData
 */

/**
 * Indicates the {@code DataType}.
 * <p>{@code DataType} is obtained based on the value.
 *
 * @enum { number }
 * @syscap SystemCapability.DistributedDataManager.DataShare.Core
 * @systemapi
 * @StageModelOnly
 * @since 9
 */
export enum DataType {
  /**
   * Indicates that the data type is null.
   *
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  TYPE_NULL = 0,

  /**
   * Indicates that the data type is long.
   *
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  TYPE_LONG = 1,

  /**
   * Indicates that the data type is double.
   *
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  TYPE_DOUBLE = 2,

  /**
   * Indicates that the data type is byte string.
   *
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  TYPE_STRING = 3,

  /**
   * Indicates that the data type is blob.
   *
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  TYPE_BLOB = 4
}

/**
 * Provides methods for accessing a datashare result set generated by querying the database.
 *
 * @interface DataShareResultSet
 * @syscap SystemCapability.DistributedDataManager.DataShare.Core
 * @systemapi
 * @StageModelOnly
 * @since 9
 */
export default interface DataShareResultSet {
  /**
   * Obtains the names of all columns or keys in a result set.
   * The column or key names are returned as a string array, in which the strings are in the same order
   * as the columns or keys in the result set.
   *
   * @type { Array<string> }
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  columnNames: Array<string>;

  /**
   * Obtains the number of columns or keys in the result set.
   * The returned number is equal to the length of the string array returned by the columnCount method.
   *
   * @type { number }
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  columnCount: number;

  /**
   * Obtains the number of rows in the result set.
   *
   * @type { number }
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  rowCount: number;

  /**
   * Checks whether the current result set is closed.
   * If the result set is closed by calling the close method, true will be returned.
   *
   * @type { boolean }
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  isClosed: boolean;

  /**
   * Go to the first row of the result set.
   *
   * @returns { boolean } Returns true if the result set is moved successfully;
   * returns false otherwise, for example, if the result set is empty.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  goToFirstRow(): boolean;

  /**
   * Go to the last row of the result set.
   *
   * @returns { boolean } Returns true if the result set is moved successfully;
   * returns false otherwise, for example, if the result set is empty.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  goToLastRow(): boolean;

  /**
   * Go to the next row of the result set.
   *
   * @returns { boolean } Returns true if the result set is moved successfully;
   * returns false otherwise, for example, if the result set is already in the last row.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  goToNextRow(): boolean;

  /**
   * Go to the previous row of the result set.
   *
   * @returns { boolean } Returns true if the result set is moved successfully;
   * returns false otherwise, for example, if the result set is already in the first row.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  goToPreviousRow(): boolean;

  /**
   * Go to the specified row of the result set forwards or backwards by an offset relative to its current position.
   * A positive offset indicates moving backwards, and a negative offset indicates moving forwards.
   *
   * @param { number } offset - Indicates the offset relative to the current position.
   * @returns { boolean } Returns true if the result set is moved successfully and does not go beyond the range;
   * returns false otherwise.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  goTo(offset: number): boolean;

  /**
   * Go to the specified row of the result set.
   *
   * @param { number } position - Indicates the index of the specified row, which starts from 0.
   * @returns { boolean } Returns true if the result set is moved successfully; returns false otherwise.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  goToRow(position: number): boolean;

  /**
   * Obtains the value of the specified column or key in the current row as a byte array.
   * The implementation class determines whether to throw an exception if the value of the specified
   * column or key in the current row is null or the specified column or key is not of the Blob type.
   *
   * @param { number } columnIndex - Indicates the specified column index or key index, which starts from 0.
   * @returns { Uint8Array } Returns the value of the specified column or key as a byte array.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  getBlob(columnIndex: number): Uint8Array;

  /**
   * Obtains the value of the specified column or key in the current row as string.
   * The implementation class determines whether to throw an exception if the value of the specified
   * column or key in the current row is null or the specified column or key is not of the string type.
   *
   * @param { number } columnIndex - Indicates the specified column index or key index, which starts from 0.
   * @returns { string } Returns the value of the specified column or key as a string.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  getString(columnIndex: number): string;

  /**
   * Obtains the value of the specified column or key in the current row as long.
   * The implementation class determines whether to throw an exception if the value of the specified
   * column or key in the current row is null, the specified column or key is not of the long type.
   *
   * @param { number } columnIndex - Indicates the specified column index or key index, which starts from 0.
   * @returns { number } Returns the value of the specified column or key as a long.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  getLong(columnIndex: number): number;

  /**
   * Obtains the value of the specified column or key in the current row as double.
   * The implementation class determines whether to throw an exception if the value of the specified
   * column or key in the current row is null, the specified column or key is not of the double type.
   *
   * @param { number } columnIndex - Indicates the specified column index or key index, which starts from 0.
   * @returns { number } Returns the value of the specified column or key as a double.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  getDouble(columnIndex: number): number;

  /**
   * Closes the result set.
   * Calling this method on the result set will release all of its resources and makes it ineffective.
   *
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  close(): void;

  /**
   * Obtains the column index or key index based on the specified column name or key name.
   * The column name or key name is passed as an input parameter.
   *
   * @param { string } columnName - Indicates the name of the specified column or key in the result set.
   * @returns { number } Returns the index of the specified column or key.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  getColumnIndex(columnName: string): number;

  /**
   * Obtains the column name or key name based on the specified column index or key index.
   * The column index or key index is passed as an input parameter.
   *
   * @param { number } columnIndex - Indicates the index of the specified column or key in the result set.
   * @returns { string } Returns the name of the specified column or key.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  getColumnName(columnIndex: number): string;

  /**
   * Obtains the dataType of the specified column or key.
   * The implementation class determines whether to throw an exception if the value of the specified
   * column or key in the current row is null, the specified column or key is not in the data type.
   *
   * @param { number } columnIndex - Indicates the specified column index or key index, which starts from 0.
   * @returns { DataType } Returns the dataType of the specified column or key.
   * @syscap SystemCapability.DistributedDataManager.DataShare.Core
   * @systemapi
   * @StageModelOnly
   * @since 9
   */
  getDataType(columnIndex: number): DataType;
}