1# @ohos.telephony.vcard (VCard) (System API) 2 3VCard is a file format standard for electronic business cards. It contains information such as names, addresses, phone numbers, URLs, logos, and photos. The VCard module provides the VCard management functions, including importing VCard files to the contact database and exporting contact data to VCard files. 4 5>**NOTE** 6> 7>The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version.<br> 8>The APIs provided by this module are system APIs. 9 10## Modules to Import 11 12```ts 13import { vcard } from '@kit.TelephonyKit'; 14``` 15 16## vcard.importVCard<sup>11+</sup> 17 18importVCard\(context: Context, filePath: string, callback: AsyncCallback\<void\>\): void 19 20Imports a VCard file (that is, **.vcf** file) to the contact database. This API uses an asynchronous callback to return the result. 21 22**Required permissions**: ohos.permission.WRITE_CONTACTS and ohos.permission.READ_CONTACTS 23 24**System API**: This is a system API. 25 26**System capability**: SystemCapability.Telephony.CoreService 27 28**Parameters** 29 30| Name | Type | Mandatory| Description | 31| -------- | --------------------------- | ---- | -------------------------------------- | 32| context | Context | Yes | Application context.| 33| filePath | string | Yes | Address of the **.vcf** file.| 34| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 35 36**Error codes** 37 38For details about the error codes, see [ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 39 40| ID| Error Message | 41| -------- | -------------------------------------------- | 42| 201 | Permission denied. | 43| 202 | Non-system applications use system APIs. | 44| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 45| 8300001 | Invalid parameter value. | 46| 8300003 | System internal error. | 47| 8300999 | Unknown error. | 48 49**Example** 50 51```ts 52import { window } from '@kit.ArkUI'; 53import { UIAbility } from '@kit.AbilityKit'; 54import { BusinessError } from '@kit.BasicServicesKit'; 55import { vcard } from '@kit.TelephonyKit'; 56 57class EntryAbility extends UIAbility { 58 onWindowStageCreate(windowStage: window.WindowStage) { 59 let filePath: string = "/data/storage/vcf/contacts.vcf"; 60 vcard.importVCard(this.context, filePath, (err: BusinessError) => { 61 console.log(`callback: err->${JSON.stringify(err)}`); 62 }); 63 } 64} 65 66``` 67 68## vcard.importVCard<sup>11+</sup> 69 70importVCard\(context: Context,filePath: string, accountId: number, callback: AsyncCallback\<void\>\): void 71 72Imports a VCard file (that is, **.vcf** file) to the contact database. This API uses an asynchronous callback to return the result. 73 74**Required permissions**: ohos.permission.WRITE_CONTACTS and ohos.permission.READ_CONTACTS 75 76**System API**: This is a system API. 77 78**System capability**: SystemCapability.Telephony.CoreService 79 80**Parameters** 81 82| Name | Type | Mandatory| Description | 83| -------- | --------------------------- | ---- | -------------------------------------- | 84| context | Context | Yes | Application context.| 85| filePath | string | Yes | Address of the **.vcf** file.| 86| accountId | number | Yes | Contact account ID.| 87| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 88 89**Error codes** 90 91For details about the error codes, see [ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 92 93| ID| Error Message | 94| -------- | -------------------------------------------- | 95| 201 | Permission denied. | 96| 202 | Non-system applications use system APIs. | 97| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 98| 8300001 | Invalid parameter value. | 99| 8300003 | System internal error. | 100| 8300999 | Unknown error. | 101 102**Example** 103 104```ts 105import { window } from '@kit.ArkUI'; 106import { UIAbility } from '@kit.AbilityKit'; 107import { BusinessError } from '@kit.BasicServicesKit'; 108import { vcard } from '@kit.TelephonyKit'; 109 110class EntryAbility extends UIAbility { 111 onWindowStageCreate(windowStage: window.WindowStage) { 112 let filePath: string = "/data/storage/vcf/contacts.vcf"; 113 let accountId: number = 0; 114 vcard.importVCard(this.context, filePath, accountId, (err: BusinessError) => { 115 console.log(`callback: err->${JSON.stringify(err)}`); 116 }); 117 } 118} 119 120``` 121 122## vcard.importVCard<sup>11+</sup> 123 124importVCard\(context: Context, filePath: string, accountId?: number\): Promise\<void\> 125 126Imports a VCard file (that is, **.vcf** file) to the contact database. This API uses a promise to return the result. 127 128**Required permissions**: ohos.permission.WRITE_CONTACTS and ohos.permission.READ_CONTACTS 129 130**System API**: This is a system API. 131 132**System capability**: SystemCapability.Telephony.CoreService 133 134**Parameters** 135 136| Name| Type | Mandatory| Description | 137| ------ | ------ | ---- | -------------------------------------- | 138| context | Context | Yes | Application context.| 139| filePath | string | Yes | Address of the **.vcf** file.| 140| accountId | number | No | Contact account ID.| 141 142**Return value** 143 144| Type | Description | 145| --------------- | ------------------------------- | 146| Promise\<void\> | Promise used to return the result.| 147 148**Error codes** 149 150For details about the error codes, see [ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 151 152| ID| Error Message | 153| -------- | -------------------------------------------- | 154| 201 | Permission denied. | 155| 202 | Non-system applications use system APIs. | 156| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 157| 8300001 | Invalid parameter value. | 158| 8300003 | System internal error. | 159| 8300999 | Unknown error. | 160 161**Example** 162 163```ts 164import { window } from '@kit.ArkUI'; 165import { UIAbility } from '@kit.AbilityKit'; 166import { BusinessError } from '@kit.BasicServicesKit'; 167import { vcard } from '@kit.TelephonyKit'; 168 169class EntryAbility extends UIAbility { 170 onWindowStageCreate(windowStage: window.WindowStage) { 171 let filePath: string = "/data/storage/vcf/contacts.vcf"; 172 let accountId: number = 0; 173 vcard.importVCard(this.context, filePath, accountId).then(() => { 174 console.log(`importVCard success.`); 175 }).catch((err: BusinessError) => { 176 console.log(`importVCard failed, promise: err->${JSON.stringify(err)}`); 177 }); 178 } 179} 180``` 181 182## vcard.exportVCard<sup>11+</sup> 183 184exportVCard\(context: Context, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback\<string\>\): void 185 186Exports contacts to a **.vcf** file. This API uses an asynchronous callback to return the result. 187 188**Required permissions**: ohos.permission.WRITE_CONTACTS and ohos.permission.READ_CONTACTS 189 190**System API**: This is a system API. 191 192**System capability**: SystemCapability.Telephony.CoreService 193 194**Parameters** 195 196| Name | Type | Mandatory| Description | 197| -------- | --------------------------- | ---- | -------------------------------------- | 198| context | Context | Yes | Application context.| 199| predicates | dataSharePredicates.DataSharePredicates | Yes | Query statement.| 200| callback | AsyncCallback<string> | Yes | Callback used to return the result, which is the address of the **.vcf** file. | 201 202**Error codes** 203 204For details about the error codes, see [ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 205 206| ID| Error Message | 207| -------- | -------------------------------------------- | 208| 201 | Permission denied. | 209| 202 | Non-system applications use system APIs. | 210| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 211| 8300001 | Invalid parameter value. | 212| 8300003 | System internal error. | 213| 8300999 | Unknown error. | 214 215**Example** 216 217```ts 218import { window } from '@kit.ArkUI'; 219import { UIAbility } from '@kit.AbilityKit'; 220import { BusinessError } from '@kit.BasicServicesKit'; 221import { vcard } from '@kit.TelephonyKit'; 222import { dataSharePredicates } from '@kit.ArkData'; 223 224class EntryAbility extends UIAbility { 225 onWindowStageCreate(windowStage: window.WindowStage) { 226 let predicates = new dataSharePredicates.DataSharePredicates(); 227 predicates.equalTo("NAME", "Rose"); 228 229 vcard.exportVCard(this.context, predicates, (err: BusinessError, data: string) => { 230 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 231 }); 232 } 233} 234 235``` 236 237## vcard.exportVCard<sup>11+</sup> 238 239exportVCard\(context: Context, predicates: dataSharePredicates.DataSharePredicates, options: VCardBuilderOptions, callback: AsyncCallback\<string\>\): void 240 241Exports contacts to a **.vcf** file. This API uses an asynchronous callback to return the result. 242 243**Required permissions**: ohos.permission.WRITE_CONTACTS and ohos.permission.READ_CONTACTS 244 245**System API**: This is a system API. 246 247**System capability**: SystemCapability.Telephony.CoreService 248 249**Parameters** 250 251| Name | Type | Mandatory| Description | 252| -------- | --------------------------- | ---- | -------------------------------------- | 253| context | Context | Yes | Application context.| 254| predicates | dataSharePredicates.DataSharePredicates | Yes | Query statement.| 255| options | [VCardBuilderOptions](#vcardbuilderoptions11) | Yes | VCard version and encoding type.| 256| callback | AsyncCallback<string> | Yes | Callback used to return the result, which is the address of the **.vcf** file. | 257 258**Error codes** 259 260For details about the error codes, see [ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 261 262| ID| Error Message | 263| -------- | -------------------------------------------- | 264| 201 | Permission denied. | 265| 202 | Non-system applications use system APIs. | 266| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 267| 8300001 | Invalid parameter value. | 268| 8300003 | System internal error. | 269| 8300999 | Unknown error. | 270 271**Example** 272 273```ts 274import { window } from '@kit.ArkUI'; 275import { UIAbility } from '@kit.AbilityKit'; 276import { BusinessError } from '@kit.BasicServicesKit'; 277import { vcard } from '@kit.TelephonyKit'; 278import { dataSharePredicates } from '@kit.ArkData'; 279 280class EntryAbility extends UIAbility { 281 onWindowStageCreate(windowStage: window.WindowStage) { 282 let predicates = new dataSharePredicates.DataSharePredicates(); 283 predicates.equalTo("NAME", "Rose"); 284 let options: vcard.VCardBuilderOptions = { 285 cardType: vcard.VCardType.VERSION_21, 286 charset: "UTF-8" 287 }; 288 vcard.exportVCard(this.context, predicates, options, (err: BusinessError, data: string) => { 289 console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); 290 }); 291 } 292} 293``` 294 295## vcard.exportVCard<sup>11+</sup> 296 297exportVCard\(context: Context, predicates: dataSharePredicates.DataSharePredicates, options?: VCardBuilderOptions\): Promise\<string\> 298 299Exports contacts to a **.vcf** file. This API uses a promise to return the result. 300 301**Required permissions**: ohos.permission.WRITE_CONTACTS and ohos.permission.READ_CONTACTS 302 303**System API**: This is a system API. 304 305**System capability**: SystemCapability.Telephony.CoreService 306 307**Parameters** 308 309| Name| Type | Mandatory| Description | 310| ------ | ------ | ---- | -------------------------------------- | 311| context | Context | Yes | Application context.| 312| predicates | dataSharePredicates.DataSharePredicates | Yes | Query statement.| 313| options | [VCardBuilderOptions](#vcardbuilderoptions11) | No | VCard version and encoding type.| 314 315**Return value** 316 317| Type | Description | 318| --------------- | ------------------------------- | 319| Promise\<string\> | Promise used to return the result, which is the address of the **.vcf** file.| 320 321**Error codes** 322 323For details about the error codes, see [ohos.telephony (Telephony) Error Codes](errorcode-telephony.md). 324 325| ID| Error Message | 326| -------- | -------------------------------------------- | 327| 201 | Permission denied. | 328| 202 | Non-system applications use system APIs. | 329| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 330| 8300001 | Invalid parameter value. | 331| 8300003 | System internal error. | 332| 8300999 | Unknown error. | 333 334**Example** 335 336```ts 337import { window } from '@kit.ArkUI'; 338import { UIAbility } from '@kit.AbilityKit'; 339import { BusinessError } from '@kit.BasicServicesKit'; 340import { vcard } from '@kit.TelephonyKit'; 341import { dataSharePredicates } from '@kit.ArkData'; 342 343class EntryAbility extends UIAbility { 344 onWindowStageCreate(windowStage: window.WindowStage) { 345 let predicates = new dataSharePredicates.DataSharePredicates(); 346 predicates.equalTo("NAME", "Rose"); 347 let options: vcard.VCardBuilderOptions = { 348 cardType: vcard.VCardType.VERSION_21, 349 charset: "UTF-8" 350 }; 351 vcard.exportVCard(this.context, predicates, options).then(() => { 352 console.log(`exportVCard success.`); 353 }).catch((err: BusinessError) => { 354 console.log(`exportVCard failed, promise: err->${JSON.stringify(err)}`); 355 }); 356 } 357} 358 359``` 360 361## VCardBuilderOptions<sup>11+</sup> 362 363Defines the VCard information. 364 365**System API**: This is a system API. 366 367**System capability**: SystemCapability.Telephony.CoreService 368 369| Name | Type | Mandatory| Description | 370| ------------ | ------ | ---- | ---------- | 371| cardType | [VCardType](#vcardtype11) | No | VCard version. The default value is **VERSION_21**. | 372| charset | string | No | VCard encoding type. The default value is **UTF-8**. | 373 374## VCardType<sup>11+</sup> 375 376Enumerates VCard versions. 377 378**System API**: This is a system API. 379 380**System capability**: SystemCapability.Telephony.CoreService 381 382| Name | Value | Description | 383| --------------- | ---- | ---------- | 384| VERSION_21 | 0 | VCard 2.1.| 385| VERSION_30 | 1 | VCard 3.0.| 386| VERSION_40 | 2 | VCard 4.0.| 387