hs.location

Определите местоположение машины и полезную информацию об этом местоположении

Этот модуль предоставляет функции для получения текущей информации о местоположении и отслеживания изменений местоположения. Он расширяет предыдущую версию модуля, добавив возможность создания независимых locationObjects, которые могут включать/отключать отслеживание местоположения независимо от других использований Служб местоположения Hammerspoon, добавляет мониторинг регионов для выхода и входа и добавляет возможность получения информации о геокодировании через подмодуль hs.location.geocoder.

Этот модуль совместим с предшественником со следующими изменениями:

hs.location.get - больше не требует вызова hs.location.start перед использованием этой функции. Возвращаемая информация будет последним кэшированным значением, которое обновляется внутренне всякий раз, когда обнаруживаются или теряются дополнительные сети Wi-Fi (не обязательно подключенные). При включенном отслеживании обновлений с помощью функции hs.location.start, расчеты, основанные на RSSI всех текущих видимых сетей, выполняются чаще для получения более точного результата, но он все равно основан на сетях Wi-Fi рядом с вами. Во многих случаях значение, полученное при изменении состояния Wi-Fi, должно быть достаточно точным.
hs.location.servicesEnabled - заменяет hs.location.services_enabled. Хотя предыдущая функция включена для обратной совместимости, она будет отображать предупреждение об устаревании в консоли при первом вызове и может быть полностью удалена в будущем.

В этом модуле и в hs.location.geocoder используются следующие метки для описания таблиц, которые используются в качестве параметров или возвращаемых значений функций и методов. Эти таблицы описываются следующим образом:

locationTable - таблица, определяющая координаты местоположения, содержащая одну или несколько из следующих пар ключ-значение:
- latitude - число, определяющее широту в градусах. Положительные значения указывают на широты севернее экватора. Отрицательные значения указывают на широты южнее экватора. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно 0,0.
- longitude - число, определяющее долготу в градусах. Измерения относятся к нулевому меридиану, при этом положительные значения простираются к востоку от меридиана, а отрицательные - к западу от меридиана. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно 0,0.
- altitude - число, указывающее высоту над (положительное) или ниже (отрицательное) уровня моря. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно 0,0.
- horizontalAccuracy - число, определяющее радиус неопределенности местоположения, измеренный в метрах. Если отрицательное, ключи latitude и longitude недопустимы и не должны использоваться. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно 0,0.
- verticalAccuracy - число, определяющее точность значения высоты в метрах. Если отрицательное, ключ altitude недопустим и не должен использоваться. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно -1,0.
- course - число, определяющее направление движения устройства. Если это значение отрицательное, то значение недействительно и не должно использоваться. На современных моделях Macintosh это значение почти всегда будет отрицательным числом. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно -1,0.
- speed - число, определяющее мгновенную скорость устройства в метрах в секунду. Если это значение отрицательное, то значение недействительно и не должно использоваться. На современных моделях Macintosh это значение почти всегда будет отрицательным числом. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно -1,0.
- timestamp - число, определяющее время, в которое было определено это местоположение. Это число представляет количество секунд с начала 1 января 1970 года в полночь по Гринвичу и является числом с плавающей точкой, поэтому вы должны использовать math.floor для этого числа перед использованием его в качестве аргумента для функции Lua os.date. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно текущему времени.
regionTable - таблица, определяющая круглую область, содержащую одну или несколько из следующих пар ключ-значение:
- identifier - строка для идентификации области. Если в таблице, используемой в качестве аргумента, это значение не указано, новое значение генерируется с помощью hs.host.uuid.
- latitude - число, определяющее широту в градусах. Положительные значения указывают на широты севернее экватора. Отрицательные значения указывают на широты южнее экватора. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно 0,0.
- longitude - число, определяющее широту в градусах. Положительные значения указывают на широты севернее экватора. Отрицательные значения указывают на широты южнее экватора. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно 0,0.
- radius - число, определяющее радиус (в метрах), который определяет внешнюю границу области. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно 0,0.
- notifyOnEntry - булево значение, определяющее, следует ли генерировать обратный вызов с сообщением "didEnterRegion", когда машина входит в область. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно true.
- notifyOnExit - булево значение, определяющее, следует ли генерировать обратный вызов с сообщением "didExitRegion", когда машина выходит из области. Если в таблице, используемой в качестве аргумента, это значение не указано, по умолчанию оно равно true.

Подмодули

hs.location.geocoder

Обзор API

Функции - вызовы API, предлагаемые непосредственно расширением

authorizationStatus
distance
dstOffset
get
register
servicesEnabled
start
stop
sunrise
sunset
unregister

Конструкторы - вызовы API, возвращающие объект, обычно тот, который предлагает методы API

Методы - вызовы API, которые могут быть выполнены только на объекте, возвращенном конструктором

addMonitoredRegion
callback
currentRegion
distanceFrom
location
monitoredRegions
removeMonitoredRegion
startTracking
stopTracking

Документация API

Функции

authorizationStatus

Подпись	`hs.location.authorizationStatus() -> string`
Тип	Функция
Описание	Возвращает строку, описывающую статус авторизации Hammerspoon для использования Служб местоположения.
Параметры	None
Возвращает	строка, соответствующая одному из следующих значений: "undefined" - Пользователь еще не выбрал, может ли Hammerspoon использовать службы местоположения. "restricted" - Hammerspoon не авторизован для использования служб местоположения. Пользователь не может изменить этот статус, возможно, из-за активных ограничений, таких как родительский контроль. "denied" - Пользователь явно запретил использование служб местоположения для Hammerspoon или службы местоположения в настоящее время отключены в Системных настройках. "authorized" - Hammerspoon авторизован для использования служб местоположения.
Примечания	При первом использовании функции, требующей Службы местоположения, вас попросят предоставить Hammerspoon доступ. Если вы хотите изменить это разрешение после первого запроса, вы можете сделать это в разделе Службы местоположения в разделе Безопасность и конфиденциальность в приложении Системные настройки.
Исходный код	extensions/location/liblocation.m строка 207

distance

Подпись	`hs.location.distance(from, to) -> meters`
Тип	Функция
Описание	Измеряет расстояние между двумя точками широты и долготы
Параметры	`from` - таблица местоположения, как описано в заголовке модуля `to` - таблица местоположения, как описано в заголовке модуля
Возвращает	Число, содержащее расстояние между `from` и `to` в метрах. Измерение выполняется путем построения линии, которая следует идеализированной кривизне Земли
Примечания	Для использования этой функции не требуется, чтобы Службы местоположения были включены для Hammerspoon.
Исходный код	extensions/location/liblocation.m строка 245

dstOffset

Подпись	`hs.location.dstOffset() -> number`
Тип	Функция
Описание	Возвращает число, представляющее текущий сдвиг летнего времени
Параметры	None
Возвращает	Количество минут сдвига летнего времени, ноль, если сдвига нет
Примечания	Это значение получено из текущих системных настроек часового пояса, оно не использует Службы местоположения
Исходный код	extensions/location/liblocation.m строка 307

get

Signature	`hs.location.get() -> locationTable or nil`
Type	Function
Description	Возвращает таблицу, представляющую текущее местоположение
Parameters	None
Returns	В случае успеха — locationTable, как описано в заголовке модуля, в противном случае — nil.
Notes	Эта функция активирует службы определения местоположения для Hammerspoon, поэтому при первом вызове может появиться запрос на разрешение Hammerspoon использовать службы определения местоположения. Если доступ к службам определения местоположения разрешен для Hammerspoon, эта функция вернёт последнюю кэшированную информацию о местоположении компьютера. Внутренне кэш служб определения местоположения обновляется всякий раз, когда обнаруживаются или теряются дополнительные сети Wi-Fi (не обязательно к которым подключен компьютер). При включении отслеживания обновлений с помощью функции hs.location.start, вычисления, основанные на RSSI всех видимых сетей, выполняются чаще для получения более точного местоположения, но всё равно основываются на сетях Wi-Fi поблизости.
Source	extensions/location/liblocation.m строка 282

register

Signature	`hs.location.register(tag, fn[, distance])`
Type	Function
Description	Регистрирует функцию обратного вызова, которая будет вызываться при обновлении системного местоположения
Parameters	`tag` - Строка, содержащая уникальный тег, используемый для идентификации обратного вызова позже `fn` - Функция, которая будет вызываться при обновлении системного местоположения. Функция должна принимать один аргумент — locationTable, как описано в заголовке модуля. `distance` - Необязательное число, содержащее минимальное расстояние в метрах, на которое должна переместиться система, прежде чем вызвать обратный вызов. По умолчанию 0
Returns	None
Source	extensions/location/location.lua строка 139

servicesEnabled

Signature	`hs.location.servicesEnabled() -> bool`
Type	Function
Description	Получает состояние служб определения местоположения OS X
Parameters	None
Returns	True, если службы определения местоположения включены, иначе false
Source	extensions/location/liblocation.m строка 192

start

Signature	`hs.location.start() -> boolean`
Type	Function
Description	Начинает отслеживание местоположения с помощью служб определения местоположения OS X, чтобы зарегистрированные функции обратного вызова вызывались при изменении местоположения компьютера.
Parameters	None
Returns	True, если операция выполнена успешно, иначе false
Notes	Эта функция активирует службы определения местоположения для Hammerspoon, поэтому при первом вызове может появиться запрос на разрешение Hammerspoon использовать службы определения местоположения.
Source	extensions/location/location.lua строка 179

stop

Signature	`hs.location.stop()`
Type	Function
Description	Останавливает отслеживание местоположения. Зарегистрированные функции обратного вызова перестанут получать уведомления об изменениях местоположения.
Parameters	None
Returns	None
Source	extensions/location/location.lua строка 201

sunrise

Signature	`hs.location.sunrise(latitude, longitude, offset[, date]) -> number or string`
Type	Function
Description	Возвращает время восхода солнца для заданного местоположения
Parameters	`latitude` - Число, содержащее широту `longitude` - Число, содержащее долготу `offset` - Число, содержащее смещение от UTC (в часах) для заданной широты/долготы. `date` - Необязательная таблица, содержащая информацию о дате (эквивалентная выводу `os.date("*t")`). По умолчанию — текущая дата
Returns	Число, содержащее время восхода солнца (в секундах с начала эпохи) для заданной даты. Если дата не задана, используется текущая дата. Если солнце не восходит в заданный день, возвращается строка "N/R".
Notes	Вы можете преобразовать возвращаемое значение в более полезную структуру с помощью `os.date("*t", returnvalue)` Для совместимости с объектом locationTable, возвращаемым hs.location.get, эту функцию также можно вызвать как `hs.location.sunrise(locationTable, offset[, date])`.
Source	extensions/location/liblocation.m строка 503

sunset

Signature	`hs.location.sunset(latitude, longitude, offset[, date]) -> number or string`
Type	Function
Description	Возвращает время захода солнца для заданного местоположения
Parameters	`latitude` - Число, содержащее широту `longitude` - Число, содержащее долготу `offset` - Число, содержащее смещение от UTC (в часах) для заданной широты/долготы. `date` - Необязательная таблица, содержащая информацию о дате (эквивалентная выводу `os.date("*t")`). По умолчанию — текущая дата
Returns	Число, содержащее время захода солнца (в секундах с начала эпохи) для заданной даты. Если дата не задана, используется текущая дата. Если солнце не заходит в заданный день, возвращается строка "N/S".
Notes	Вы можете преобразовать возвращаемое значение в более полезную структуру с помощью `os.date("*t", returnvalue)` Для совместимости с объектом locationTable, возвращаемым hs.location.get, эту функцию также можно вызвать как `hs.location.sunset(locationTable, offset[, date])`.
Source	extensions/location/liblocation.m строка 526

unregister

Signature	`hs.location.unregister(tag)`
Type	Function
Description	Отменяет регистрацию обратного вызова
Parameters	`tag` - Строка, содержащая уникальный тег, с которым был зарегистрирован обратный вызов
Returns	None
Source	extensions/location/location.lua строка 166

Constructors

new

Signature	`hs.location.new() -> locationObject`
Type	Constructor
Description	Создаёт новый объект location, который может получать обратные вызовы независимо от другого использования Hammerspoon служб определения местоположения.
Parameters	None
Returns	locationObject
Notes	Созданный locationObject будет получать обратные вызовы независимо от других locationObjects и устаревших функций обратного вызова, созданных с помощью hs.location.register. Он также может получать обратные вызовы для изменений области, недоступных через механизм устаревшего обратного вызова.
Source	extensions/location/location.lua строка 221

Methods

addMonitoredRegion

Signature	`hs.location:addMonitoredRegion(regionTable) -> locationObject \| nil`
Type	Method
Description	Добавляет область для мониторинга службами определения местоположения
Parameters	`regionTable` - таблица region, как описано в заголовке модуля
Returns	Если область была добавлена в службы определения местоположения для мониторинга, возвращает locationObject; в противном случае возвращает nil
Notes	Этот метод активирует службы определения местоположения для Hammerspoon, поэтому при первом вызове может появиться запрос на разрешение Hammerspoon использовать службы определения местоположения. Если ключ `identifier` не предоставлен, генерируется новая строка UUID и используется в качестве идентификатора. Если ключ `identifier` совпадает с уже отслеживаемой областью, эта область заменит существующую.
Source	extensions/location/location.lua строка 358

END_OF_DOCUMENT_MARKER

callback

Signature	`hs.location:callback(fn) -> locationObject`
Type	Method
Description	Устанавливает или удаляет функцию обратного вызова для этого объекта locationObject
Parameters	функция или nil для удаления текущей функции, которая будет вызвана в качестве обратного вызова для сообщений, сгенерированных этим объектом locationObject. Функция обратного вызова должна ожидать 3 или 4 аргумента следующим образом: сам объект locationObject строка, определяющая сообщение, сгенерированное объектом locationObject: * "didChangeAuthorizationStatus" - пользователь изменил статус авторизации для использования Hammerspoon в сервисах геолокации. Третий аргумент будет строкой, как описано в функции hs.location.authorizationStatus. * "didUpdateLocations" - текущее местоположение изменилось или уточнено. Это сообщение будет появляться только в том случае, если отслеживание местоположения было включено с помощью hs.location:startTracking. Третий аргумент будет таблицей, содержащей одну или несколько locationTables в качестве элементов массива. Последнее обновление местоположения содержится в последнем элементе массива. * "didFailWithError" - произошла ошибка при получении информации о местоположении. Третий аргумент будет строкой, описывающей произошедшую ошибку. * "didStartMonitoringForRegion" - новая область успешно добавлена в отслеживаемые области. Третий аргумент будет regionTable для области, которая была только что добавлена. * "monitoringDidFailForRegion" - произошла ошибка при попытке добавить новую область в список отслеживаемых областей. Третий аргумент будет regionTable для области, которая не могла быть добавлена, а четвертый аргумент — строка с сообщением об ошибке, описывающей причину неудачи отслеживания области. * "didEnterRegion" - текущее местоположение вошло в область, для которой поле `notifyOnEntry` установлено в значение true, указанное методом hs.location:addMonitoredRegion. Третий аргумент будет regionTable для входящей области. * "didExitRegion" - текущее местоположение покинуло область, для которой поле `notifyOnExit` установлено в значение true, указанное методом hs.location:addMonitoredRegion. Третий аргумент будет regionTable для покинутой области.
Returns	объект locationObject
Source	extensions/location/location.lua строка 461

currentRegion

Signature	`hs.location:currentRegion() -> identifier \| nil`
Type	Method
Description	Возвращает строковый идентификатор текущей области
Parameters	None
Returns	строковый идентификатор области, в которой находится текущее местоположение, или nil, если текущее местоположение не находится в текущей отслеживаемой области или сервисы геолокации не могут быть включены для Hammerspoon.
Notes	Этот метод активирует сервисы геолокации для Hammerspoon, поэтому при первом вызове вас могут попросить авторизовать Hammerspoon для использования сервисов геолокации.
Source	extensions/location/location.lua строка 436

distanceFrom

Signature	`hs.location:distanceFrom(locationTable) -> distance \| nil`
Type	Method
Description	Включить обратные вызовы для изменений/уточнений местоположения для этого объекта locationObject
Parameters	None
Returns	расстояние до указанного местоположения от текущего местоположения в метрах или nil, если сервисы геолокации не могут быть включены для Hammerspoon. Измерение производится путем построения линии, которая следует идеализированной кривизне Земли
Notes	Эта функция активирует сервисы геолокации для Hammerspoon, поэтому при первом её вызове вас могут попросить авторизовать Hammerspoon для использования сервисов геолокации.
Source	extensions/location/location.lua строка 300

location

Signature	`hs.location:location() -> locationTable \| nil`
Type	Method
Description	Возвращает текущее местоположение
Parameters	None
Returns	В случае успеха, locationTable, как описано в заголовке модуля, в противном случае nil.
Notes	Эта функция активирует сервисы геолокации для Hammerspoon, поэтому при первом её вызове вас могут попросить авторизовать Hammerspoon для использования сервисов геолокации. Если доступ к сервисам геолокации включён для Hammerspoon, эта функция вернёт последние сохранённые данные о местоположении компьютера. Внутренне кэш сервисов геолокации обновляется всякий раз, когда обнаруживаются или теряются дополнительные сети Wi-Fi (не обязательно подключенные). Когда отслеживание обновлений включено с помощью функции hs.location.start, вычисления, основанные на RSSI всех текущих видимых сетей, выполняются чаще, чтобы обеспечить более точное определение местоположения, но оно всё ещё основано на сетях Wi-Fi рядом с вами.
Source	extensions/location/location.lua строка 495

monitoredRegions

Signature	`hs.location:monitoredRegions() -> table \| nil`
Type	Method
Description	Возвращает таблицу, содержащую regionTables для областей, которые в данный момент отслеживаются для этого объекта locationObject
Parameters	None
Returns	если сервисы геолокации могут быть включены для Hammerspoon, возвращает таблицу, содержащую regionTables для каждой области, которая отслеживается для этого объекта locationObject; в противном случае nil
Notes	Этот метод активирует сервисы геолокации для Hammerspoon, поэтому при первом его вызове вас могут попросить авторизовать Hammerspoon для использования сервисов геолокации.
Source	extensions/location/location.lua строка 321

removeMonitoredRegion

Signature	`hs.location:removeMonitoredRegion(identifier) -> locationObject \| false \| nil`
Type	Method
Description	Удаляет отслеживаемую область из сервисов геолокации
Parameters	`identifier` - строка, которая должна содержать идентификатор области, которую нужно удалить из мониторинга
Returns	если идентификатор области соответствует текущей отслеживаемой области, возвращает объект locationObject; если он не соответствует ни одной из текущих отслеживаемых областей, возвращает false; возвращает nil, если произошла ошибка или если сервисы геолокации не активны (ни одна функция или метод, активирующая сервисы геолокации, ещё не вызваны) или не включены для Hammerspoon.
Notes	Этот метод активирует сервисы геолокации для Hammerspoon, поэтому при первом вызове вас могут попросить авторизовать Hammerspoon для использования сервисов геолокации. Если ключ `identifier` не указан, генерируется новая строка UUID и используется в качестве идентификатора. Если ключ `identifier` соответствует уже отслеживаемой области, эта область заменит существующую.
Source	extensions/location/location.lua строка 406

startTracking

Signature	`hs.location:startTracking() -> locationObject`
Type	Method
Description	Включить обратные вызовы для изменений/уточнений местоположения для этого объекта locationObject
Parameters	None
Returns	объект locationObject
Notes	Эта функция активирует сервисы геолокации для Hammerspoon, поэтому при первом её вызове вас могут попросить авторизовать Hammerspoon для использования сервисов геолокации.
Source	extensions/location/location.lua строка 260

stopTracking

Signature	`hs.location:stopTracking() -> locationObject`
Type	Method
Description	Отключить обратные вызовы для изменений/уточнений местоположения для этого объекта locationObject
Parameters	None
Returns	объект locationObject
Source	extensions/location/location.lua строка 281