Skip to content

[office-js][office-js-preview] (DevicePermission) Clarify values returned by requestPermissions and requestPermissionsAsync #69854

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ElizabethSamuel-MSFT merged 2 commits into from
Jun 25, 2024
Merged

[office-js][office-js-preview] (DevicePermission) Clarify values returned by requestPermissions and requestPermissionsAsync #69854

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
754cc71
Clarify return values
samantharamon Jun 19, 2024
154d6db
Apply suggestions from review
samantharamon Jun 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 17 additions & 11 deletions types/office-js-preview/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5307,6 +5307,13 @@ declare namespace Office {
*
* This method returns a promise. Use it with Excel, PowerPoint, and Word add-ins.
*
* If a user grants access to a device capability for the first time, the promise resolves with `true`.
* You must then reload the add-in before you can run code that uses the device capability.
* For example, you can call `window.location.reload()` to reload your add-in.
* If a user had previously granted access to a device capability, the promise resolves with `false`.
* You don't need to reload your add-in to run code that uses the device capability, as the permission is already set.
* If a user denies access to a device capability, the promise rejects with a "User denied the permission request" error message.
*
* @remarks
*
* **Important**:
Expand All @@ -5317,9 +5324,6 @@ declare namespace Office {
* Use {@link https://learn.microsoft.com/javascript/api/office/office.context#office-office-context-platform-member | Office.context.platform} and verify that it returns
* `Office.PlatformType.OfficeOnline`. Otherwise, the `requestPermissions` call will return an error.
*
* - If the user allows access to their camera or microphone, the add-in must be reloaded in the browser for the permissions to take effect.
* For example, you can call `window.location.reload()` to reload your add-in.
*
* - If a user selects **Allow** from the dialog, the permission persists until the add-in is uninstalled or until the
* cache of the browser on which the add-in is running is cleared. If a user wants to change an add-in’s access to their camera or microphone,
* they must uninstall the add-in or clear their browser cache.
Expand Down Expand Up @@ -5347,9 +5351,6 @@ declare namespace Office {
*
* - For Excel, PowerPoint, and Word add-ins, use the `requestPermissions` method instead.
*
* - If the user allows access to their camera, geolocation, or microphone, the add-in must be reloaded in the browser for the permissions to take effect.
* For example, you can call `window.location.reload()` to reload your add-in.
*
* - If your add-in uses the same code for both Office on the web and Office desktop clients, verify the platform on which the add-in is running before calling `requestPermissionsAsync`.
* Use {@link https://learn.microsoft.com/javascript/api/outlook/office.diagnostics#outlook-office-diagnostics-hostname-member | Office.context.mailbox.diagnostics.hostName}
* and verify that it returns `OutlookWebApp`. Otherwise, the `requestPermissionsAsync` call will return an error.
Expand All @@ -5369,7 +5370,11 @@ declare namespace Office {
* In Outlook on the web, an add-in can request access to a user's camera, geolocation, and microphone.
* @param options An object literal that contains the `asyncContext` property. Assign any object you wish to access in the callback function to the `asyncContext` property.
* @param callback When the method completes, the function passed in the `callback` parameter is called with a single parameter, `asyncResult`, which is an `Office.AsyncResult` object.
* If the user grants permission to access the requested device capabilities, `true` is returned in the `asyncResult.value` property.
* If the user grants permission to access the requested device capabilities, `true` is returned in the `asyncResult.value` property. You must then reload the add-in before you can
* run code that uses the device capabilities. For example, you can call `window.location.reload()` to reload your add-in.
* If the user had previously granted permission to access the requested device capabilities, `false` is returned in the `asyncResult.value` property. You don't need to
* reload your add-in to run code that uses the device capability, as the permission is already set.
* If a user denies access to the requested device capabilities, `Office.AsyncResultStatus.Failed` is returned in the `asyncResult.status` property.
*/
requestPermissionsAsync(permissions: Office.DevicePermissionType[], options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;
/**
Expand All @@ -5386,9 +5391,6 @@ declare namespace Office {
*
* - For Excel, PowerPoint, and Word add-ins, use the `requestPermissions` method instead.
*
* - If the user allows access to their camera, geolocation, or microphone, the add-in must be reloaded in the browser for the permissions to take effect.
* For example, you can call `window.location.reload()` to reload your add-in.
*
* - If your add-in uses the same code for both Office on the web and Office desktop clients, verify the platform on which the add-in is running before calling `requestPermissionsAsync`.
* Use {@link https://learn.microsoft.com/javascript/api/outlook/office.diagnostics#outlook-office-diagnostics-hostname-member | Office.context.mailbox.diagnostics.hostName}
* and verify that it returns `OutlookWebApp`. Otherwise, the `requestPermissionsAsync` call will return an error.
Expand All @@ -5407,7 +5409,11 @@ declare namespace Office {
* @param permissions An array of device capabilities to which an add-in is requesting access.
* In Outlook on the web, an add-in can request access to a user's camera, geolocation, and microphone.
* @param callback When the method completes, the function passed in the `callback` parameter is called with a single parameter, `asyncResult`, which is an `Office.AsyncResult` object.
* If the user grants permission to access the requested device capabilities, `true` is returned in the `asyncResult.value` property.
* If the user grants permission to access the requested device capabilities, `true` is returned in the `asyncResult.value` property. You must then reload the add-in before you can
* run code that uses the device capabilities. For example, you can call `window.location.reload()` to reload your add-in.
* If the user had previously granted permission to access the requested device capabilities, `false` is returned in the `asyncResult.value` property. You don't need to
* reload your add-in to run code that uses the device capability, as the permission is already set.
* If a user denies access to the requested device capabilities, `Office.AsyncResultStatus.Failed` is returned in the `asyncResult.status` property.
*/
requestPermissionsAsync(permissions: Office.DevicePermissionType[], callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;
}
Expand Down
28 changes: 17 additions & 11 deletions types/office-js/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5297,6 +5297,13 @@ declare namespace Office {
*
* This method returns a promise. Use it with Excel, PowerPoint, and Word add-ins.
*
* If a user grants access to a device capability for the first time, the promise resolves with `true`.
* You must then reload the add-in before you can run code that uses the device capability.
* For example, you can call `window.location.reload()` to reload your add-in.
* If a user had previously granted access to a device capability, the promise resolves with `false`.
* You don't need to reload your add-in to run code that uses the device capability, as the permission is already set.
* If a user denies access to a device capability, the promise rejects with a "User denied the permission request" error message.
*
* @remarks
*
* **Important**:
Expand All @@ -5307,9 +5314,6 @@ declare namespace Office {
* Use {@link https://learn.microsoft.com/javascript/api/office/office.context#office-office-context-platform-member | Office.context.platform} and verify that it returns
* `Office.PlatformType.OfficeOnline`. Otherwise, the `requestPermissions` call will return an error.
*
* - If the user allows access to their camera or microphone, the add-in must be reloaded in the browser for the permissions to take effect.
* For example, you can call `window.location.reload()` to reload your add-in.
*
* - If a user selects **Allow** from the dialog, the permission persists until the add-in is uninstalled or until the
* cache of the browser on which the add-in is running is cleared. If a user wants to change an add-in’s access to their camera or microphone,
* they must uninstall the add-in or clear their browser cache.
Expand Down Expand Up @@ -5337,9 +5341,6 @@ declare namespace Office {
*
* - For Excel, PowerPoint, and Word add-ins, use the `requestPermissions` method instead.
*
* - If the user allows access to their camera, geolocation, or microphone, the add-in must be reloaded in the browser for the permissions to take effect.
* For example, you can call `window.location.reload()` to reload your add-in.
*
* - If your add-in uses the same code for both Office on the web and Office desktop clients, verify the platform on which the add-in is running before calling `requestPermissionsAsync`.
* Use {@link https://learn.microsoft.com/javascript/api/outlook/office.diagnostics#outlook-office-diagnostics-hostname-member | Office.context.mailbox.diagnostics.hostName}
* and verify that it returns `OutlookWebApp`. Otherwise, the `requestPermissionsAsync` call will return an error.
Expand All @@ -5359,7 +5360,11 @@ declare namespace Office {
* In Outlook on the web, an add-in can request access to a user's camera, geolocation, and microphone.
* @param options An object literal that contains the `asyncContext` property. Assign any object you wish to access in the callback function to the `asyncContext` property.
* @param callback When the method completes, the function passed in the `callback` parameter is called with a single parameter, `asyncResult`, which is an `Office.AsyncResult` object.
* If the user grants permission to access the requested device capabilities, `true` is returned in the `asyncResult.value` property.
* If the user grants permission to access the requested device capabilities, `true` is returned in the `asyncResult.value` property. You must then reload the add-in before you can
* run code that uses the device capabilities. For example, you can call `window.location.reload()` to reload your add-in.
* If the user had previously granted permission to access the requested device capabilities, `false` is returned in the `asyncResult.value` property. You don't need to
* reload your add-in to run code that uses the device capability, as the permission is already set.
* If a user denies access to the requested device capabilities, `Office.AsyncResultStatus.Failed` is returned in the `asyncResult.status` property.
*/
requestPermissionsAsync(permissions: Office.DevicePermissionType[], options: Office.AsyncContextOptions, callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;
/**
Expand All @@ -5376,9 +5381,6 @@ declare namespace Office {
*
* - For Excel, PowerPoint, and Word add-ins, use the `requestPermissions` method instead.
*
* - If the user allows access to their camera, geolocation, or microphone, the add-in must be reloaded in the browser for the permissions to take effect.
* For example, you can call `window.location.reload()` to reload your add-in.
*
* - If your add-in uses the same code for both Office on the web and Office desktop clients, verify the platform on which the add-in is running before calling `requestPermissionsAsync`.
* Use {@link https://learn.microsoft.com/javascript/api/outlook/office.diagnostics#outlook-office-diagnostics-hostname-member | Office.context.mailbox.diagnostics.hostName}
* and verify that it returns `OutlookWebApp`. Otherwise, the `requestPermissionsAsync` call will return an error.
Expand All @@ -5397,7 +5399,11 @@ declare namespace Office {
* @param permissions An array of device capabilities to which an add-in is requesting access.
* In Outlook on the web, an add-in can request access to a user's camera, geolocation, and microphone.
* @param callback When the method completes, the function passed in the `callback` parameter is called with a single parameter, `asyncResult`, which is an `Office.AsyncResult` object.
* If the user grants permission to access the requested device capabilities, `true` is returned in the `asyncResult.value` property.
* If the user grants permission to access the requested device capabilities, `true` is returned in the `asyncResult.value` property. You must then reload the add-in before you can
* run code that uses the device capabilities. For example, you can call `window.location.reload()` to reload your add-in.
* If the user had previously granted permission to access the requested device capabilities, `false` is returned in the `asyncResult.value` property. You don't need to
* reload your add-in to run code that uses the device capability, as the permission is already set.
* If a user denies access to the requested device capabilities, `Office.AsyncResultStatus.Failed` is returned in the `asyncResult.status` property.
*/
requestPermissionsAsync(permissions: Office.DevicePermissionType[], callback: (asyncResult: Office.AsyncResult<boolean>) => void): void;
}
Expand Down