Common Methods Object

From Hubitat Documentation
Revision as of 20:56, 31 December 2019 by Cschwer (talk | contribs)
Jump to: navigation, search

These methods can be used in both Apps and Drivers

getLocation

Signature
Location getLocation()

getSunriseAndSunset

Returns the sunset and sunrise values for the current day. (Common method since 2.1.0)
Signature
Map getSunriseAndSunset()
Map getSunriseAndSunset(Map options)
Parameters
options - Map with optional offset for sunrise or sunset, possible values are sunriseOffset and sunsetOffset and can either be a number of minutes or a String of the format Hours:Minutes
Returns
Map with with key values 'sunrise' and 'sunset' of type Date
Examples
// get today's sunrise and sunset
def riseAndSet = getSunriseAndSunset()
log.debug riseAndSet.sunrise
log.debug riseAndSet.sunset

// get sunrise time offset by 1 minute early, and get sunset offset by 1 hour, 5 minutes later
def offsetRiseAndSet = getSunriseAndSunset(sunriseOffset: -1, sunsetOffset: "1:05")

getTemperatureScale

Get the current temperature scale set for the hub.
Signature
String getTemperatureScale()
Parameters
none
Returns
String - "F" or "C" based on the setting in the hub.

now

Signature
long now()

timeToday

Get a Date object with today's date and the time specified
Signature
Date timeToday(String timeString, TimeZone timeZone = null)
Parameters
timeString - The time to use, can be either "HH:mm" or and ISO8601 date/time string
timeZone - (Optional) The timezone to use for the new Date.
Returns
Date - A Date object with today's date and the time that was passed as timeString


timeOfDayIsBetween

Check if a date is between two dates.
Signature
boolean timeOfDayIsBetween(Date start, Date stop, Date value[, TimeZone timeZone])
Parameters
start - The date to start comparison against.
stop - The date to stop comparison against.
value - The date to compare
timezone - (Optional) The timezone to use for the comparison
Returns
boolean - true if the value date is between the start and stop dates, otherwise returns false.


unschedule

Remove any scheduled tasks. If method is called without paramters, all schedules will be removed.
Signature
void unschedule()
void unschedule(handlerMethod)
Parameters
handlerMethod - Only remove schedules for this handlerMethod

asynchttpGet

Send an http GET request and return control to the calling code. Any response from the call will be passed to the callback method.
Signature
void asynchttpGet(callbackMethod, Map params, Map data = null)
Parameters
callbackMethod - The name of a callback method to send the response to. Can be null if the response can be ignored.
params - the parameters to use to build the http GET call. Possible values:
uri - The uri to send the request to
queryString - The raw, already-escaped query string.
query - Add these parameters to the existing query string. If any of the parameters already exist in the query, these values will not replace them. Multiple values for the same query parameter may be added by putting them in a list.
headers - Request headers
path - The path component of this request. The value may be absolute or relative to the current path.
contentType - The content-type used for any data in the request body, as well as the Accept content-type that will be used for parsing the response.
requestContentType - Assign a different content-type for the request than is expected for the response.
timeout (since 2.0.9) - timeout in seconds for the request, max timeout is 300
ignoreSSLIssues (since 2.1.8) - possible values: true, false. Ignores certificate issues for SSL connections. Cert does not have to be from a trusted authority and the hostname does not need to be verified. This is primarily for dev situations that make use of localhost, build, and test servers. Defaults to false.
data - optional data to be passed to the callback method.

asynchttpPost

Signature
void asynchttpPost(String callbackMethod = null, Map params, Map data = null)
Parameters
callbackMethod - The name of a callback method to send the response to. Can be null if the response can be ignored.
params - the parameters to use to build the http GET call. Possible values:
uri - The uri to send the request to
queryString - The raw, already-escaped query string.
query - Add these parameters to the existing query string. If any of the parameters already exist in the query, these values will not replace them. Multiple values for the same query parameter may be added by putting them in a list.
headers - Request headers
path - The path component of this request. The value may be absolute or relative to the current path.
contentType - The content-type used for any data in the request body, as well as the Accept content-type that will be used for parsing the response.
requestContentType - Assign a different content-type for the request than is expected for the response.
body - The request body. If this is a Map or Array, the system will take care of encoding it based on the requestContentType.
timeout (since 2.0.9) - timeout in seconds for the request, max timeout is 300
ignoreSSLIssues (since 2.1.8) - possible values: true, false. Ignores certificate issues for SSL connections. Cert does not have to be from a trusted authority and the hostname does not need to be verified. This is primarily for dev situations that make use of localhost, build, and test servers. Defaults to false.
data - optional data to be passed to the callback method.

asynchttpPatch

Signature
void asynchttpPatch(String callbackMethod = null, Map params, Map data = null)
Parameters
callbackMethod - The name of a callback method to send the response to. Can be null if the response can be ignored.
params - the parameters to use to build the http PATCH call. Possible values:
uri - The uri to send the request to
queryString - The raw, already-escaped query string.
query - Add these parameters to the existing query string. If any of the parameters already exist in the query, these values will not replace them. Multiple values for the same query parameter may be added by putting them in a list.
headers - Request headers
path - The path component of this request. The value may be absolute or relative to the current path.
contentType - The content-type used for any data in the request body, as well as the Accept content-type that will be used for parsing the response.
requestContentType - Assign a different content-type for the request than is expected for the response.
body - The request body. If this is a Map or Array, the system will take care of encoding it based on the requestContentType.
timeout (since 2.0.9) - timeout in seconds for the request, max timeout is 300
ignoreSSLIssues (since 2.1.8) - possible values: true, false. Ignores certificate issues for SSL connections. Cert does not have to be from a trusted authority and the hostname does not need to be verified. This is primarily for dev situations that make use of localhost, build, and test servers. Defaults to false.
data - optional data to be passed to the callback method.

httpGet

Send an http GET request. Any response from the call will be passed to the closure.
Signature
void httpGet(String uri, Closure closure)
void httpGet(Map params, Closure closure)
Parameters
uri - The full uri to send the request to.
params - the parameters to use to build the http GET call. Possible values:
uri - The uri to send the request to
queryString - The raw, already-escaped query string.
query - Add these parameters to the existing query string. If any of the parameters already exist in the query, these values will not replace them. Multiple values for the same query parameter may be added by putting them in a list.
headers - Request headers
path - The path component of this request. The value may be absolute or relative to the current path.
contentType - The content-type used for any data in the request body, as well as the Accept content-type that will be used for parsing the response.
requestContentType - Assign a different content-type for the request than is expected for the response.
timeout (since 2.0.9) - timeout in seconds for the request, max timeout is 300
textParser (since 2.1.1) - possible values: true, false. If set to true, the response will be parsed as plain text, if false the system will attempt to determine the content type and parse the response into an object. Defaults to false.
ignoreSSLIssues (since 2.1.8) - possible values: true, false. Ignores certificate issues for SSL connections. Cert does not have to be from a trusted authority and the hostname does not need to be verified. This is primarily for dev situations that make use of localhost, build, and test servers. Defaults to false.
closure - code to handle a successful HTTP response. an object of type HttpResponseDecorator is passed to this code.

httpPost

Signature
void httpPost(String uri, String body, Closure closure)
void httpPost(Map params, Closure closure)
Parameters
uri - The full uri to send the request to.
body - The body of the request as a String. Any encoding should be done before passing to the system.
params - the parameters to use to build the http call. Possible values:
uri - The uri to send the request to
queryString - The raw, already-escaped query string.
query - Add these parameters to the existing query string. If any of the parameters already exist in the query, these values will not replace them. Multiple values for the same query parameter may be added by putting them in a list.
headers - Request headers
path - The path component of this request. The value may be absolute or relative to the current path.
contentType - The content-type used for any data in the request body, as well as the Accept content-type that will be used for parsing the response.
requestContentType - Assign a different content-type for the request than is expected for the response.
body - The request body. If this is a Map or Array, the system will take care of encoding it based on the requestContentType.
timeout (since 2.0.9) - timeout in seconds for the request, max timeout is 300
textParser (since 2.1.1) - possible values: true, false. If set to true, the response will be parsed as plain text, if false the system will attempt to determine the content type and parse the response into an object. Defaults to false.
ignoreSSLIssues (since 2.1.8) - possible values: true, false. Ignores certificate issues for SSL connections. Cert does not have to be from a trusted authority and the hostname does not need to be verified. This is primarily for dev situations that make use of localhost, build, and test servers. Defaults to false.
closure - code to handle a successful HTTP response. an object of type HttpResponseDecorator is passed to this code.

httpPostJson

Similar to httpPost except that the contentType parameter is set to "application/json"
Signature
void httpPostJson(String uri, String stringBody, Closure closure)
void httpPostJson(String uri, Map mapBody, Closure closure)
void httpPostJson(Map params, Closure closure)
Parameters
uri - The full uri to send the request to.
stringBody - The body of the request as a String. Any encoding should be done before passing to the system.
mapBody - The body of the request as a Map.
params - the parameters to use to build the http call. Possible values:
uri - The uri to send the request to
queryString - The raw, already-escaped query string.
query - Add these parameters to the existing query string. If any of the parameters already exist in the query, these values will not replace them. Multiple values for the same query parameter may be added by putting them in a list.
headers - Request headers
path - The path component of this request. The value may be absolute or relative to the current path.
requestContentType - Assign a different content-type for the request than is expected for the response.
body - The request body. If this is a Map or Array, the system will take care of encoding it as JSON.
timeout (since 2.0.9) - timeout in seconds for the request, max timeout is 300
textParser (since 2.1.8) - possible values: true, false. If set to true, the response will be parsed as plain text, if false the system will attempt to determine the content type and parse the response into an object. Defaults to false.
ignoreSSLIssues (since 2.1.8) - possible values: true, false. Ignores certificate issues for SSL connections. Cert does not have to be from a trusted authority and the hostname does not need to be verified. This is primarily for dev situations that make use of localhost, build, and test servers. Defaults to false.
closure - code to handle a successful HTTP response. an object of type HttpResponseDecorator is passed to this code.

httpPut

Signature
void httpPut(String uri, String body, Closure closure)
void httpPut(Map params, Closure closure)
Parameters
uri - The full uri to send the request to.
body - The body of the request as a String. Any encoding should be done before passing to the system.
params - the parameters to use to build the http call. Possible values:
uri - The uri to send the request to
queryString - The raw, already-escaped query string.
query - Add these parameters to the existing query string. If any of the parameters already exist in the query, these values will not replace them. Multiple values for the same query parameter may be added by putting them in a list.
headers - Request headers
path - The path component of this request. The value may be absolute or relative to the current path.
contentType - The content-type used for any data in the request body, as well as the Accept content-type that will be used for parsing the response.
requestContentType - Assign a different content-type for the request than is expected for the response.
body - The request body. If this is a Map or Array, the system will take care of encoding it based on the requestContentType.
timeout (since 2.0.9) - timeout in seconds for the request, max timeout is 300
textParser (since 2.1.1) - possible values: true, false. If set to true, the response will be parsed as plain text, if false the system will attempt to determine the content type and parse the response into an object. Defaults to false.
ignoreSSLIssues (since 2.1.8) - possible values: true, false. Ignores certificate issues for SSL connections. Cert does not have to be from a trusted authority and the hostname does not need to be verified. This is primarily for dev situations that make use of localhost, build, and test servers. Defaults to false.
closure - code to handle a successful HTTP response. an object of type HttpResponseDecorator is passed to this code.

httpPatch (Since 2.1.7)

Signature
void httpPatch(String uri, String body, Closure closure)
void httpPatch(Map params, Closure closure)
Parameters
uri - The full uri to send the request to.
body - The body of the request as a String. Any encoding should be done before passing to the system.
params - the parameters to use to build the http call. Possible values:
uri - The uri to send the request to
queryString - The raw, already-escaped query string.
query - Add these parameters to the existing query string. If any of the parameters already exist in the query, these values will not replace them. Multiple values for the same query parameter may be added by putting them in a list.
headers - Request headers
path - The path component of this request. The value may be absolute or relative to the current path.
contentType - The content-type used for any data in the request body, as well as the Accept content-type that will be used for parsing the response.
requestContentType - Assign a different content-type for the request than is expected for the response.
body - The request body. If this is a Map or Array, the system will take care of encoding it based on the requestContentType.
timeout - timeout in seconds for the request, max timeout is 300
textParser - possible values: true, false. If set to true, the response will be parsed as plain text, if false the system will attempt to determine the content type and parse the response into an object. Defaults to false.
ignoreSSLIssues (since 2.1.8) - possible values: true, false. Ignores certificate issues for SSL connections. Cert does not have to be from a trusted authority and the hostname does not need to be verified. This is primarily for dev situations that make use of localhost, build, and test servers. Defaults to false.
closure - code to handle a successful HTTP response. an object of type HttpResponseDecorator is passed to this code.

runIn

Signature
void runIn(Long delayInSeconds, String handlerMethod, Map options = null)
Parameters
delayInSeconds - How long to wait in seconds until the handler should be called, don't expect that it will be called in exactly that time.
handlerMethod - The name of a handler method in your driver or app. The method name should not contain parentheses.
options - Optional values to control the scheduling of this method
overwrite - defaults to true which cancels the previous scheduled running of the handler method and schedules new, if set to false this will create a duplicate schedule.
data - optional data to be passed to the handler method.
misfire - If set to "ignore" then the scheduler will simply try to fire it as soon as it can. NOTE: if a scheduler uses this instruction, and it has missed several of its scheduled firings, then several rapid firings may occur as the scheduler attempts to catch back up to where it would have been.
Example
    runIn(50, 'myMethod', [data: ["myKey":"myValue"]])

runInMillis

Signature
void runInMillis(Long delayInMilliSeconds, String handlerMethod, Map options = null)
Parameters
delayInMilliseconds - How long to wait until the handler should be called, don't expect that it will be called in exactly that time.
handlerMethod - the name of a handler method in your driver or app. The method name should not contain parentheses.
options - Optional values to control the scheduling of this method
overwrite - defaults to true which cancels the previous scheduled running of the handler method and schedules new, if set to false this will create a duplicate schedule.
data - optional data to be passed to the handler method.
misfire - If set to "ignore" then the scheduler will simply try to fire it as soon as it can. NOTE: if a schduler uses this instruction, and it has missed several of its scheduled firings, then several rapid firings may occur as the scheduler attempts to catch back up to where it would have been.
Example
    private processQueue(Map queue) {
      if (isQueueEmpty(queue)) {
          sendEvent name: 'lifxdiscovery', value: 'complete'
          return
      }
      def data = getNext(queue)
      sendPacket data.ipAddress, data.packet
      runInMillis(queue.delay, 'processQueue', [data: queue])
    }
  
    runInMillis(50, 'processQueue', [data: queue])

pauseExecution

Signature
void pauseExecution(Long millisecs)
Parameters
millisecs - The amount of time in milliseconds to pause.

toDateTime

Signature
Date toDateTime(String dateTimeString)
Parameters
dateTimeString - A date/time string in ISO8601 format. ("yyyy-MM-dd", "yyyyMMdd'T'HHmmssX", "yyyy-MM-dd'T'HH:mm:ssX", "yyyy-MM-dd'T'HH:mm:ss.SSSX")

Additional to be documented

Signature: 

BigDecimal celsiusToFahrenheit(BigDecimal val)
BigDecimal fahrenheitToCelsius(BigDecimal val)
void httpPutJson(String uri, String body, Closure closure)
void httpPutJson(String uri, Map body, Closure closure)
void httpPutJson(Map params, Closure closure)
void httpDelete(Map params, Closure closure)
String getMACFromIP(String ipAddr)
String convertTemperatureIfNeeded(BigDecimal value, String scale, Integer precision)
Object parseJson(String stringToParse)
GPathResult parseXML(String stringToParse)
Map parseLanMessage(String stringToParse)
void runEvery1Minute(String handlerMethod, Map options = null)
void runEvery5Minutes(String handlerMethod, Map options = null)
void runEvery10Minutes(String handlerMethod, Map options = null)
void runEvery15Minutes(String handlerMethod, Map options = null)
void runEvery30Minutes(String handlerMethod, Map options = null)
void runEvery1Hour(String handlerMethod, Map options = null)
void runEvery3Hours(String handlerMethod, Map options = null)
void runOnce(Date dateTime, String handlerMethod, Map options = null)
void runOnce(String dateTime, String handlerMethod, Map options = null)
void schedule(Date dateTime, String handlerMethod, Map options = null)
void schedule(String expression, String handlerMethod, Map options = null)
void asynchttpPut(String callbackMethod = null, Map params, Map data = null)
void asynchttpDelete(String callbackMethod = null, Map params, Map data = null)
void asynchttpHead(String callbackMethod = null, Map params, Map data = null)
Map textToSpeech(String stringToBeSynthesized, String voice = null)
String encrypt(String value)
String decrypt(String value)
void sendLocationEvent(Map properties)
Date timeTodayAfter(String startTimeString, String timeString, TimeZone timeZone = null) (Common method since 2.1.0)
Long timeOffset(Number minutes) (Common method since 2.1.0)
Long timeOffset(String hoursAndMinutesString) (Common method since 2.1.0)
Retrieved from "https://docs.hubitat.com/index.php?title=Common_Methods_Object&oldid=2436"