-
Notifications
You must be signed in to change notification settings - Fork 64
/
office.roamingsettings.yml
254 lines (181 loc) · 8.89 KB
/
office.roamingsettings.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
### YamlMime:TSType
name: Office.RoamingSettings
uid: 'outlook!Office.RoamingSettings:interface'
package: outlook!
fullName: Office.RoamingSettings
summary: >-
The settings created by using the methods of the `RoamingSettings` object are saved per add-in and per user. That is,
they are available only to the add-in that created them, and only from the user's mailbox in which they are saved.
While the Outlook add-in API limits access to these settings to only the add-in that created them, these settings
shouldn't be considered secure storage. They can be accessed by Exchange Web Services or Extended MAPI. They shouldn't
be used to store sensitive information, such as user credentials or security tokens.
The name of a setting is a String, while the value can be a String, Number, Boolean, null, Object, or Array.
The `RoamingSettings` object is accessible via the `roamingSettings` property in the `Office.context` namespace.
To learn more about `RoamingSettings`<!-- -->, see [Get and set add-in metadata for an Outlook
add-in](https://learn.microsoft.com/office/dev/add-ins/outlook/metadata-for-an-outlook-add-in)<!-- -->.
remarks: >-
\[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**Important**:
- The `RoamingSettings` object is initialized from the persisted storage only when the add-in is first loaded. For
task panes, this means that it's only initialized when the task pane first opens. If the task pane navigates to
another page or reloads the current page, the in-memory object is reset to its initial values, even if your add-in has
persisted changes. The persisted changes will not be available until the task pane (or item in the case of UI-less
add-ins) is closed and reopened.
- When set and saved through Outlook on Windows
([new](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627) or classic) or on Mac, these
settings are reflected in Outlook on the web only after a browser refresh.
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!-- -->**:
**restricted**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!-- -->**:
Compose or Read
isPreview: false
isDeprecated: false
type: interface
methods:
- name: get(name)
uid: 'outlook!Office.RoamingSettings#get:member(1)'
package: outlook!
fullName: get(name)
summary: Retrieves the specified setting.
remarks: >-
\[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **restricted**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
#### Examples
```TypeScript
// Link to full sample:
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml
const settingName = $("#settingName").val();
const settingValue = Office.context.roamingSettings.get(settingName);
$("#settingValue").val(settingValue);
console.log(`The value of setting "${settingName}" is "${settingValue}".`);
```
isPreview: false
isDeprecated: false
syntax:
content: 'get(name: string): any;'
parameters:
- id: name
description: The case-sensitive name of the setting to retrieve.
type: string
return:
type: any
description: 'Type: String \| Number \| Boolean \| Object \| Array'
- name: remove(name)
uid: 'outlook!Office.RoamingSettings#remove:member(1)'
package: outlook!
fullName: remove(name)
summary: Removes the specified setting.
remarks: >-
\[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **restricted**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
isPreview: false
isDeprecated: false
syntax:
content: 'remove(name: string): void;'
parameters:
- id: name
description: The case-sensitive name of the setting to remove.
type: string
return:
type: void
description: ''
- name: saveAsync(callback)
uid: 'outlook!Office.RoamingSettings#saveAsync:member(1)'
package: outlook!
fullName: saveAsync(callback)
summary: >-
Saves the settings.
Any settings previously saved by an add-in are loaded when it's initialized, so during the lifetime of the session
you can just use the set and get methods to work with the in-memory copy of the settings property bag. When you
want to persist the settings so that they're available the next time the add-in is used, use the `saveAsync`
method.
remarks: >-
\[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **restricted**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
#### Examples
```TypeScript
// Link to full sample:
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml
// Save settings in the mailbox to make it available in future sessions.
Office.context.roamingSettings.saveAsync(function(result) {
if (result.status !== Office.AsyncResultStatus.Succeeded) {
console.error(`Action failed with message ${result.error.message}`);
} else {
console.log(`Settings saved with status: ${result.status}`);
}
});
```
isPreview: false
isDeprecated: false
syntax:
content: 'saveAsync(callback?: (asyncResult: Office.AsyncResult<void>) => void): void;'
parameters:
- id: callback
description: >-
Optional. When the method completes, the function passed in the `callback` parameter is called with a single
parameter of type `Office.AsyncResult`<!-- -->.
type: '(asyncResult: <xref uid="office!Office.AsyncResult:interface" /><void>) => void'
return:
type: void
description: ''
- name: 'set(name, value)'
uid: 'outlook!Office.RoamingSettings#set:member(1)'
package: outlook!
fullName: 'set(name, value)'
summary: >-
Sets or creates the specified setting.
The `set` method creates a new setting of the specified name if it doesn't already exist, or sets an existing
setting of the specified name. The value is stored in the document as the serialized JSON representation of its
data type.
A maximum of 32KB is available for the settings of each add-in. An error with code 9057 is thrown when that size
limit is exceeded.
Any changes made to settings using the `set` method will not be saved to the server until the `saveAsync` method
is called.
remarks: >-
\[ [API set: Mailbox 1.1](/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets) \]
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!--
-->**: **restricted**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!--
-->**: Compose or Read
#### Examples
```TypeScript
// Link to full sample:
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml
const settingName = $("#settingName").val();
const settingValue = $("#settingValue").val();
Office.context.roamingSettings.set(settingName, settingValue);
console.log(`Setting "${settingName}" set to value "${settingValue}".`);
```
isPreview: false
isDeprecated: false
syntax:
content: 'set(name: string, value: any): void;'
parameters:
- id: name
description: The case-sensitive name of the setting to set or create.
type: string
- id: value
description: Specifies the value to be stored.
type: any
return:
type: void
description: ''