@microsoft/teams-js 2.30.0 → 2.31.0-beta.0

package/dist/esm/packages/teams-js/dts/public/media.d.ts

@@ -0,0 +1,440 @@
+import { SdkError } from './interfaces';
+/**
+ * Interact with media, including capturing and viewing images.
+ */
+export declare namespace media {
+    /**
+     * Function callback type used when calling {@link media.captureImage}.
+     *
+     * @param error - Error encountered during the API call, if any, {@link SdkError}
+     * @param files - Collection of File objects (images) captured by the user. Will be an empty array in the case of an error.
+     * */
+    export type captureImageCallbackFunctionType = (error: SdkError, files: File[]) => void;
+    /**
+     * Function callback type used when calling {@link media.selectMedia}.
+     *
+     * @param error - Error encountered during the API call, if any, {@link SdkError}
+     * @param attachments - Collection of {@link Media} objects selected by the user. Will be an empty array in the case of an error.
+     * */
+    export type selectMediaCallbackFunctionType = (error: SdkError, attachments: Media[]) => void;
+    /** Error callback function type. */
+    export type errorCallbackFunctionType = (error?: SdkError) => void;
+    /**
+     * Function callback type used when calling {@link media.scanBarCode}.
+     *
+     * @param error - Error encountered during the API call, if any, {@link SdkError}
+     * @param decodedText - Decoded text from the barcode, if any. In the case of an error, this will be the empty string.
+     * */
+    export type scanBarCodeCallbackFunctionType = (error: SdkError, decodedText: string) => void;
+    /**
+     * Function callback type used when calling {@link media.Media.getMedia}
+     *
+     * @param error - Error encountered during the API call, if any, {@link SdkError}
+     * @param blob - Blob of media returned. Will be a blob with no BlobParts, in the case of an error.
+     * */
+    export type getMediaCallbackFunctionType = (error: SdkError, blob: Blob) => void;
+    /**
+     * Enum for file formats supported
+     */
+    export enum FileFormat {
+        /** Base64 encoding */
+        Base64 = "base64",
+        /** File id */
+        ID = "id"
+    }
+    /**
+     * File object that can be used to represent image or video or audio
+     */
+    export class File {
+        /**
+         * Content of the file. When format is Base64, this is the base64 content
+         * When format is ID, this is id mapping to the URI
+         * When format is base64 and app needs to use this directly in HTML tags, it should convert this to dataUrl.
+         */
+        content: string;
+        /**
+         * Format of the content
+         */
+        format: FileFormat;
+        /**
+         * Size of the file in KB
+         */
+        size: number;
+        /**
+         * MIME type. This can be used for constructing a dataUrl, if needed.
+         */
+        mimeType: string;
+        /**
+         * Optional: Name of the file
+         */
+        name?: string;
+    }
+    /**
+     * Launch camera, capture image or choose image from gallery and return the images as a File[] object to the callback.
+     *
+     * @params callback - Callback will be called with an @see SdkError if there are any.
+     * If error is null or undefined, the callback will be called with a collection of @see File objects
+     * @remarks
+     * Note: Currently we support getting one File through this API, i.e. the file arrays size will be one.
+     * Note: For desktop, this API is not supported. Callback will be resolved with ErrorCode.NotSupported.
+     *
+     */
+    export function captureImage(callback: captureImageCallbackFunctionType): void;
+    /**
+     * Checks whether or not media has user permission
+     *
+     * @returns Promise that will resolve with true if the user had granted the app permission to media information, or with false otherwise,
+     * In case of an error, promise will reject with the error. Function can also throw a NOT_SUPPORTED_ON_PLATFORM error
+     *
+     * @beta
+     */
+    export function hasPermission(): Promise<boolean>;
+    /**
+     * Requests user permission for media
+     *
+     * @returns Promise that will resolve with true if the user consented permission for media, or with false otherwise,
+     * In case of an error, promise will reject with the error. Function can also throw a NOT_SUPPORTED_ON_PLATFORM error
+     *
+     * @beta
+     */
+    export function requestPermission(): Promise<boolean>;
+    /**
+     * Media object returned by the select Media API
+     */
+    export class Media extends File {
+        constructor(that?: Media);
+        /**
+         * A preview of the file which is a lightweight representation.
+         * In case of images this will be a thumbnail/compressed image in base64 encoding.
+         */
+        preview: string;
+        /**
+         * Gets the media in chunks irrespective of size, these chunks are assembled and sent back to the webapp as file/blob
+         * @param callback - callback is called with the @see SdkError if there is an error
+         * If error is null or undefined, the callback will be called with @see Blob.
+         */
+        getMedia(callback: getMediaCallbackFunctionType): void;
+        /** Function to retrieve media content, such as images or videos, via callback. */
+        private getMediaViaCallback;
+        /** Function to retrieve media content, such as images or videos, via handler. */
+        private getMediaViaHandler;
+    }
+    /**
+     * Input parameter supplied to the select Media API
+     */
+    export interface MediaInputs {
+        /**
+         * Only one media type can be selected at a time
+         */
+        mediaType: MediaType;
+        /**
+         * max limit of media allowed to be selected in one go, current max limit is 10 set by office lens.
+         */
+        maxMediaCount: number;
+        /**
+         * Additional properties for customization of select media - Image in mobile devices
+         */
+        imageProps?: ImageProps;
+        /**
+         * Additional properties for customization of select media - Video in mobile devices
+         */
+        videoProps?: VideoProps;
+        /**
+         * Additional properties for customization of select media - VideoAndImage in mobile devices
+         */
+        videoAndImageProps?: VideoAndImageProps;
+        /**
+         * Additional properties for audio capture flows.
+         */
+        audioProps?: AudioProps;
+    }
+    /**
+     * @hidden
+     * Hide from docs
+     * --------
+     * All properties common to Image and Video Props
+     */
+    interface MediaProps {
+        /**
+         * @hidden
+         * Optional; Lets the developer specify the media source, more than one can be specified.
+         * Default value is both camera and gallery
+         */
+        sources?: Source[];
+        /**
+         * @hidden
+         * Optional; Specify in which mode the camera will be opened.
+         * Default value is Photo
+         */
+        startMode?: CameraStartMode;
+        /**
+         * @hidden
+         * Optional; indicate if user is allowed to move between front and back camera
+         * Default value is true
+         */
+        cameraSwitcher?: boolean;
+    }
+    /**
+     *  All properties in ImageProps are optional and have default values in the platform
+     */
+    export interface ImageProps extends MediaProps {
+        /**
+         * Optional; indicate if inking on the selected Image is allowed or not
+         * Default value is true
+         */
+        ink?: boolean;
+        /**
+         * Optional; indicate if putting text stickers on the selected Image is allowed or not
+         * Default value is true
+         */
+        textSticker?: boolean;
+        /**
+         * Optional; indicate if image filtering mode is enabled on the selected image
+         * Default value is false
+         */
+        enableFilter?: boolean;
+        /**
+         * Optional; Lets the developer specify the image output formats, more than one can be specified.
+         * Default value is Image.
+         */
+        imageOutputFormats?: ImageOutputFormats[];
+    }
+    /**
+     * All properties in VideoProps are optional and have default values in the platform
+     */
+    export interface VideoProps extends MediaProps {
+        /**
+         * Optional; the maximum duration in seconds after which the recording should terminate automatically.
+         * Default value is defined by the platform serving the API.
+         */
+        maxDuration?: number;
+        /**
+         * Optional; to determine if the video capturing flow needs to be launched
+         * in Full Screen Mode (Lens implementation) or PictureInPicture Mode (Native implementation).
+         * Default value is true, indicating video will always launch in Full Screen Mode via lens.
+         */
+        isFullScreenMode?: boolean;
+        /**
+         * Optional; controls the visibility of stop button in PictureInPicture Mode.
+         * Default value is true, indicating the user will be able to stop the video.
+         */
+        isStopButtonVisible?: boolean;
+        /**
+         * Optional; setting VideoController will register your app to listen to the lifecycle events during the video capture flow.
+         * Your app can also dynamically control the experience while capturing the video by notifying the host client.
+         */
+        videoController?: VideoController;
+    }
+    /**
+     * All properties in VideoAndImageProps are optional and have default values in the platform
+     */
+    export interface VideoAndImageProps extends ImageProps, VideoProps {
+    }
+    /**
+     *  All properties in AudioProps are optional and have default values in the platform
+     */
+    export interface AudioProps {
+        /**
+         * Optional; the maximum duration in minutes after which the recording should terminate automatically
+         * Default value is defined by the platform serving the API.
+         */
+        maxDuration?: number;
+    }
+    /**
+     * @hidden
+     * Hide from docs
+     * --------
+     * Base class which holds the callback and notifies events to the host client
+     */
+    abstract class MediaController<T> {
+        /** Callback that can be registered to handle events related to the playback and control of video content. */
+        protected controllerCallback?: T;
+        constructor(controllerCallback?: T);
+        protected abstract getMediaType(): MediaType;
+        /**
+         * @hidden
+         * Hide from docs
+         * --------
+         * This function will be implemented by the respective media class which holds the logic
+         * of specific events that needs to be notified to the app.
+         * @param mediaEvent indicates the event signed by the host client to the app
+         */
+        protected abstract notifyEventToApp(mediaEvent: MediaControllerEvent): void;
+        /**
+         * @hidden
+         * Hide from docs
+         * --------
+         * Function to notify the host client to programatically control the experience
+         * @param mediaEvent indicates what the event that needs to be signaled to the host client
+         * Optional; @param callback is used to send app if host client has successfully handled the notification event or not
+         */
+        protected notifyEventToHost(mediaEvent: MediaControllerEvent, callback?: errorCallbackFunctionType): void;
+        /**
+         * Function to programatically stop the ongoing media event
+         * Optional; @param callback is used to send app if host client has successfully stopped the event or not
+         */
+        stop(callback?: errorCallbackFunctionType): void;
+    }
+    /**
+     * Callback which will register your app to listen to lifecycle events during the video capture flow
+     */
+    export interface VideoControllerCallback {
+        /** The event is a type of callback that can be enlisted to handle various events linked to `onRecordingStarted`, which helps with playback of video content. */
+        onRecordingStarted?(): void;
+    }
+    /**
+     * VideoController class is used to communicate between the app and the host client during the video capture flow
+     */
+    export class VideoController extends MediaController<VideoControllerCallback> {
+        /** Gets media type video. */
+        protected getMediaType(): MediaType;
+        /** Notify or send an event related to the playback and control of video content to a registered application. */
+        notifyEventToApp(mediaEvent: MediaControllerEvent): void;
+    }
+    /**
+     * @beta
+     * Events which are used to communicate between the app and the host client during the media recording flow
+     */
+    export enum MediaControllerEvent {
+        /** Start recording. */
+        StartRecording = 1,
+        /** Stop recording. */
+        StopRecording = 2
+    }
+    /**
+     * The modes in which camera can be launched in select Media API
+     */
+    export enum CameraStartMode {
+        /** Photo mode. */
+        Photo = 1,
+        /** Document mode. */
+        Document = 2,
+        /** Whiteboard mode. */
+        Whiteboard = 3,
+        /** Business card mode. */
+        BusinessCard = 4
+    }
+    /**
+     * Specifies the image source
+     */
+    export enum Source {
+        /** Image source is camera. */
+        Camera = 1,
+        /** Image source is gallery. */
+        Gallery = 2
+    }
+    /**
+     * Specifies the type of Media
+     */
+    export enum MediaType {
+        /** Media type photo or image */
+        Image = 1,
+        /** Media type video. */
+        Video = 2,
+        /** Media type video and image. */
+        VideoAndImage = 3,
+        /** Media type audio. */
+        Audio = 4
+    }
+    /**
+     * Input for view images API
+     */
+    export interface ImageUri {
+        /** Image location */
+        value: string;
+        /** Image Uri type */
+        type: ImageUriType;
+    }
+    /**
+     * ID contains a mapping for content uri on platform's side, URL is generic
+     */
+    export enum ImageUriType {
+        /** Image Id. */
+        ID = 1,
+        /** Image URL. */
+        URL = 2
+    }
+    /**
+     * Specifies the image output formats.
+     */
+    export enum ImageOutputFormats {
+        /** Outputs image.  */
+        IMAGE = 1,
+        /** Outputs pdf. */
+        PDF = 2
+    }
+    /**
+     * Media chunks an output of getMedia API from platform
+     */
+    export interface MediaChunk {
+        /**
+         * Base 64 data for the requested uri
+         */
+        chunk: string;
+        /**
+         * chunk sequence number
+         */
+        chunkSequence: number;
+    }
+    /**
+     * Output of getMedia API from platform
+     */
+    export interface MediaResult {
+        /**
+         * error encountered in getMedia API
+         */
+        error: SdkError;
+        /**
+         * Media chunk which will be assemebled and converted into a blob
+         */
+        mediaChunk: MediaChunk;
+    }
+    /**
+     * Helper object to assembled media chunks
+     */
+    export interface AssembleAttachment {
+        /** A number representing the sequence of the attachment in the media chunks. */
+        sequence: number;
+        /** A Blob object representing the data of the media chunks. */
+        file: Blob;
+    }
+    /**
+     * Select an attachment using camera/gallery
+     *
+     * @param mediaInputs - The input params to customize the media to be selected
+     * @param callback - The callback to invoke after fetching the media
+     */
+    export function selectMedia(mediaInputs: MediaInputs, callback: selectMediaCallbackFunctionType): void;
+    /**
+     * View images using native image viewer
+     *
+     * @param uriList - list of URIs for images to be viewed - can be content URI or server URL. Supports up to 10 Images in a single call
+     * @param callback - returns back error if encountered, returns null in case of success
+     */
+    export function viewImages(uriList: ImageUri[], callback: errorCallbackFunctionType): void;
+    /**
+     * Barcode configuration supplied to scanBarCode API to customize barcode scanning experience in mobile
+     * All properties in BarCodeConfig are optional and have default values in the platform
+     */
+    export interface BarCodeConfig {
+        /**
+         * Optional; Lets the developer specify the scan timeout interval in seconds
+         * Default value is 30 seconds and max allowed value is 60 seconds
+         */
+        timeOutIntervalInSec?: number;
+    }
+    /**
+     * @deprecated
+     * As of 2.1.0, please use {@link barCode.scanBarCode barCode.scanBarCode(config?: BarCodeConfig): Promise\<string\>} instead.
+  
+     * Scan Barcode/QRcode using camera
+     *
+     * @remarks
+     * Note: For desktop and web, this API is not supported. Callback will be resolved with ErrorCode.NotSupported.
+     *
+     * @param callback - callback to invoke after scanning the barcode
+     * @param config - optional input configuration to customize the barcode scanning experience
+     */
+    export function scanBarCode(callback: scanBarCodeCallbackFunctionType, config?: BarCodeConfig): void;
+    export {};
+}