Обработчик

Это - имя функции-обработчика. Функция должна быть экспортирована как точка входа в исполнимую программу.

ThreadSafe

OSA и AppleScript в Mac OS X v10.6 ориентированы на многопотоковое исполнение. Если сценарий будет выполняться на фоновом потоке и вызовет обработчик событий, который не ориентирован на многопотоковое исполнение, то его вызовут на основном потоке, который медленнее, чем прямой вызов его на вызывающем потоке и может сократить скорость отклика приложения до ввода данных пользователем. Идеально, все обработчики должны быть ориентированы на многопотоковое исполнение. Некоторые по сути не могут быть; например, почти что-либо, что выводит на экран UI, должно быть выполнено на основном потоке. Вы призваны или проверить, что Ваши обработчики событий ориентированы на многопотоковое исполнение или обновляют их для создания их ориентированными на многопотоковое исполнение.

Если значение этого ключа является истиной, то обработчик может быть выполнен на неосновном потоке, и это может быть выполнено одновременно от многократных потоков. Если ложь, это будет только выполняться на основном потоке. Этот ключ требуется для обработчиков событий и не должен присутствовать для обработчиков приведения, требующихся, чтобы быть ориентированными на многопотоковое исполнение. Если обработчик приведения не может быть сделан безопасным работать на фоновых потоках, обработчик должен расположить выполнить приведение на основном потоке, таком как использование при помощи libdispatch и основной очереди отгрузки.

Контекст

Для соображений безопасности Mac OS X v10.6 только выполнит дополнения сценариев в других процессах, если это будет необходимо, и в некоторых случаях сможет попросить авторизацию прежде, чем сделать так. Точно то, как дополнение сценариев обрабатывается, зависит от значения ключа «Context», описывающего, какой контекст выполнения обработчик зависит от того, для функционирования правильно. В сценарии дополнительная команда сценариев может быть внутри a tell блок для, скажем, Mail.app на удаленной машине, но если ее «контекст» ослабляется достаточно, это будет фактически выполняться в различном процессе, представляющем меньше угрозы безопасности, обычно приложение, выполняющее сценарий. Context ключ может иметь одно из четырех значений:

Любое значение Context подразумевает зависимости контекстов выше его, таким образом, User подразумевает Machine зависимости, и Process подразумевает User и Machine зависимости. Попытайтесь записать обработчики с как можно меньшим количеством зависимостей, начиная с большего количества средних значений зависимостей большая угроза безопасности.

Этот ключ требуется для обработчиков событий и не должен присутствовать для обработчиков приведения, всегда выполняющихся в том же процессе как сценарий.

Инициализация

Ваша подпрограмма инициализации дополнения сценариев ответственна за установку Ваших подпрограмм обработчика дополнения сценариев. Для реализации его дополнение сценариев должно экспортировать названную подпрограмму SAInitialize, который вызовет AppleScript и должен установить все событие и обработчики приведения. Перечисление 3 обеспечивает эскиз подпрограммы инициализации дополнения сценариев:

  Выборка перечисления 3 сценарии дополнительной подпрограммы инициализации.

OSErr SAInitialize(CFBundleRef additionBundle)
{
    OSErr err;

    Boolean isSysHandler = true;
    err = AEInstallEventHandler(theAEEventClass, theAEEventID, eventHandlerUPP, refcon, isSysHandler);
    err = AEInstallCoercionHandler(fromType, toType, coercionHandlerUPP, refcon, fromIsDesc, isSysHandler);

    return err;
}

Все дополнительные обработчики сценариев должны быть установлены в системной таблице отгрузки, как показано выше.

Ваше дополнение сценариев должно всегда устанавливать все свои обработчики, даже если функциональность, которой они требуют, не присутствует в системе. Тем путем у Вас есть возможность обеспечить значимое сообщение об ошибке, когда Ваше дополнение вызывается, а не обобщение «не понимает», или «не может принудить» сообщение.

Ваша функция инициализации может выполнить дополнительные операции установки, такие как выделение памяти или нахождение файлов, но это не рекомендуется: это создает дополнительную стоимость запуска и даже может не быть необходимо, так как Ваше дополнение сценариев никогда не может вызываться. Инициализация должна быть задержана, пока Ваше дополнение фактически не вызывается.

additionBundle параметр передал SAInitialize ссылка на пакет дополнения сценариев. Это только присутствует по историческим причинам. Если обработчику нужен доступ к ресурсам пакета дополнения сценариев, это может определить местоположение использования пакета CFBundleGetBundleWithIdentifier.

Информация о ссылках пакета и формате пакета может быть найдена в разделе References в конце этой статьи.

Завершение

Ваша подпрограмма завершения дополнения сценариев ответственна за удаление Ваших подпрограмм обработчика дополнения сценариев. Для реализации его дополнение сценариев должно экспортировать названную подпрограмму SATerminate, который вызовет AppleScript и должен удалить все событие и обработчики приведения. Перечисление 4 обеспечивает эскиз подпрограммы завершения дополнения сценариев:

  Выборка перечисления 4 сценарии дополнительной подпрограммы завершения.

void SATerminate(void) {     AERemoveEventHandler(theAEEventClass, theAEEventID, gTheHandler, true);     DisposeAEEventHandlerUPP(gTheHandler);      ...other cleanup operations... }

Подпрограмма завершения может выполнить другие операции очистки, такие как высвобождение средств. Однако функция завершения никогда не будет вызываться в Leopard. Если Ваше дополнение должно выполнить, работа во время завершения процесса, такое как высвобождение средств, использует atexit(3). Примите во внимание, что много ресурсов, таких как выделенная память, будут освобождены автоматически, когда выйдет процесс.

Подсчет ссылок

Эта подпрограмма существует по историческим причинам: в классическом Mac OS было возможно разрушить систему путем удаления дополнения сценариев, в то время как это все еще работало. Поэтому сценарии дополнений экспортировали названную функцию SAIsBusy указать, были ли они заняты, и поэтому не безопасны разгрузиться. Этот возможный катастрофический отказ был решен другими средними значениями в Mac OS X v10.2, представив SAIsBusy устаревший. Это все еще должно существовать, но может просто возвратиться false, как показано в Перечислении 5.

  Выборка перечисления 5 подпрограмма SAIsBusy для дополнения сценариев.

Boolean SAIsBusy(void) {     return false; }

Соображения во время выполнения

Ваше дополнение сценариев может быть загружено в процесс любого приложения и должно поэтому заботиться для не нарушения глобального состояния за пределами самого дополнительного обработчика, такого как цепочка ресурса Менеджера ресурсов, эффективный идентификатор пользователя, и т.д.

Пишущие сценарий дополнения загружаются отдельно в каждого порядка подачи заявки, использующего их. В результате необходимо разработать дополнение сценариев, имеющее в виду, что может быть много экземпляров дополнения сценариев, открытого во многих различных приложениях одновременно. Некоторые дополнения сценариев могут потребовать дополнительного кода, если они используют единственный совместно используемый ресурс, такой как принтер или последовательный порт.

Определение местоположения ресурсов пакета дополнения сценариев

Сценарии дополнений, возможно, должны получить доступ к ресурсам и файлам, расположенным в их пакете. Чтобы сделать это, получите a CFBundleRef использование CFBundleGetBundleWithIdentifier, передача его идентификатор пакета Вашего дополнения сценариев.

Информация о ссылках пакета и формате пакета может быть найдена в разделе References в конце этой статьи.

Локальные и удаленные запросы

Если выполнение Вашей дополнительной команды сценариев на удаленной машине не значимо или составило бы угрозу безопасности, Ваш обработчик команды должен обнаружить и отклонить события от удаленных машин. Обработчик может определить источник события путем исследования keyEventSourceAttr атрибут во входящем событии. Событие от удаленной системы будет иметь значение атрибута kAERemoteProcess.

DescType sourceAttr;

err = AEGetAttributePtr(eventPtr, keyEventSourceAttr, typeType, NULL, &sourceAttr, sizeof(sourceAttr), NULL);
if (err != noErr || sourceAttr == kAERemoteProcess)
{
    return errAELocalOnly;
}