macos_sandbox.lcb

library community.livecode.trevordevore.macossandbox

  use com.livecode.foreign
  use com.livecode.objc
  use com.livecode.engine

  metadata title is "macOS Sandbox"
  metadata author is "Trevor DeVore"
  metadata version is "1.0.0"

  private foreign handler ObjC_NSURLAlloc() \
        returns ObjcRetainedId binds to "objc:NSURL.+alloc"
  private foreign handler ObjC_NSURLInitFileURLWithPath(in pObj as ObjcRetainedId, in pFilename as ObjcId) \
        returns optional ObjcRetainedId binds to "objc:NSURL.-initFileURLWithPath:"
  private foreign handler ObjC_NSURLBookMarkDataWithOptions(in pNSURL as ObjcId, in pOptions as CULong, in pValuesForKeys as optional ObjcId, in pRelativeUrl as optional ObjcId, out pError as ObjcRetainedId) \
        returns optional ObjcId binds to "objc:NSURL.-bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error:"
  private foreign handler ObjC_NSURLStartAccessingSecurityScopedResource(in pNSURL as ObjcId) \
        returns CBool binds to "objc:NSURL.-startAccessingSecurityScopedResource"
  private foreign handler ObjC_NSURLStopAccessingSecurityScopedResource(in pNSURL as ObjcId) \
        returns nothing binds to "objc:NSURL.stopAccessingSecurityScopedResource"
  private foreign handler ObjC_NSURLInitByResolvingBookmarkData(in pNSURL as ObjcId, in pBookmarkData as ObjcId, in pOptions as CULong, in pRelativeURL as optional ObjcId, out pBookmarkDataIsStale as CBool, out pError as ObjcRetainedId) \
        returns optional ObjcRetainedId binds to "objc:NSURL.-initByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error:"
  private foreign handler ObjC_NSURLAbsoluteString(in pNSURL as ObjcId) \
        returns ObjcId binds to "objc:NSURL.-absoluteString"


  /**
  Summary: Returns app scoped bookmark data for a file.

  Parameters:
  pFilename: The target filename.
  pReadOnly: Pass in true if you only need read only access to the file.
  rErrorMsg: Any errors will be reported in this variable.

  Description:
  This function is used for accessing files across sessions in a sandbox environment. The binary data that
  is returned can be stored and passed to `macsandStartAccessingFile()` the next time your
  application runs. Your application will then have access to the file without having to prompt the user again.

  As an example, take an application that that opens documents and wants to restore any documents
  that were open when the application was last closed. After the user selects the file to open you
  pass the filename to this function and store the bookmark data that is returned (e.g. in a preference).
  If the user manually closes the file then you can dispose of the binary data.

  If, however, the user quits your application then the next time the application is launched you pass
  the bookmark data to `macsandStartAccessingFile()`. The security-scoped filename that is returned should
  be stored by your application until the user closes the file at which point you should call
  `macsandStopAccessingFile()`. If the user quits the application with the document still open you should
  still call `macsandStopAccessingFile()`. You can use the bookmark data to restore access again the next
  time. You would only delete the bookmark data if the user manually closes the file.

  Returns: Bookmark data (binary)
  */
  public handler macsandGetFileBookmarkData(in pFilename as String, in pReadOnly as Boolean, out rErrorMsg as String) returns Data
    variable tData as Data
    variable tNSURL as optional ObjcObject
    variable tNSData as optional ObjcObject
    variable tNSError as optional ObjcObject

    unsafe
      put ObjC_NSURLAlloc() into tNSURL
      put ObjC_NSURLInitFileURLWithPath(tNSURL, StringToNSString(pFilename)) into tNSURL
    end unsafe

    if tNSURL is nothing then
      put "unable to resolve" && pFilename into rErrorMsg
    else
      put _getFileBookmarkData(tNSURL, pReadOnly, tNSError) into tNSData

      if tNSError is not nothing then
        put NSErrorGetString(tNSError) into rErrorMsg
      else if tNSData is not nothing then
        put DataFromNSData(tNSData) into tData
      end if
    end if

    return tData
  end handler


  private handler _getFileBookmarkData(in pNSURL as ObjcObject, in pReadOnly as Boolean, out rNSError as optional ObjcObject) returns optional ObjcObject
    variable tResourceKeys as List
    variable tBookmarkOptions as Integer

    variable tRelativeToURL as optional ObjcObject
    variable tNSData as optional ObjcObject

    // NSURLBookmarkCreationWithSecurityScope
    put tBookmarkOptions bitwise or (1 shifted left by 11 bitwise) into tBookmarkOptions
    if pReadOnly then
      // NSURLBookmarkCreationSecurityScopeAllowOnlyReadAccess
      put tBookmarkOptions bitwise or (1 shifted left by 12 bitwise) into tBookmarkOptions
    end if

    unsafe
      put ObjC_NSURLBookMarkDataWithOptions(pNSURL, tBookmarkOptions, ListToNSArray(tResourceKeys), tRelativeToURL, rNSError) into tNSData
    end unsafe

    return tNSData
  end handler


  /**
  Summary: Uses data from `macsandGetFileBookmarkData()` to create a security-scoped url

  Parameters:
  pBookmarkData: The binary data returned by `macsandGetFileBookmarkData()`.
  rBookmarkDataIsStale: Set to true if the bookmark data is stale.
  rErrorMsg: Any errors will be reported in this variable.

  Description:
  If you store data returned from `macsandGetFileBookmarkData()` between sessions you can use this
  handler to gain access to a file when your application starts up without having to prompt the user
  again.

  The filename returned by this handler is a security-scoped filename that you will use if you want to remove access
  to the file from your application. This should be done when your application no longer needs access to the file.

  If the bookmark data is stale the error will be "bookmark data is stale". This can happen if the file no longer
  exists at the same location as it was at when the bookmark was created.

  Returns: Security-scoped filename
  */
  public handler macsandStartAccessingFile(in pBookmarkData as Data, out rBookmarkDataIsStale as Boolean, out rErrorMsg as String) returns String
    variable tBookmarkOptions as Integer
    variable tGainedAccess as Boolean

    variable tNSURL as optional ObjcObject
    variable tRelativeToURL as optional ObjcObject
    variable tNSData as optional ObjcObject
    variable tNSError as optional ObjcObject
    variable tFilename as optional ObjcObject

    put DataToNSData(pBookmarkData) into tNSData

    // NSURLBookmarkResolutionWithSecurityScope
    put tBookmarkOptions bitwise or (1 shifted left by 10 bitwise) into tBookmarkOptions

    if tNSData is not nothing then
      unsafe
        put ObjC_NSURLAlloc() into tNSURL
        put ObjC_NSURLInitByResolvingBookmarkData(tNSURL, tNSData, tBookmarkOptions, tRelativeToURL, rBookmarkDataIsStale, tNSError) into tNSURL

        if tNSError is not nothing then
          put NSErrorGetString(tNSError) into rErrorMsg
        else if tNSURL is not nothing then
          put ObjC_NSURLStartAccessingSecurityScopedResource(tNSURL) into tGainedAccess
          if tGainedAccess then
            put ObjC_NSURLAbsoluteString(tNSURL) into tFilename
          else
            put "unable to gain access to file" into rErrorMsg
          end if
        end if
      end unsafe
    end if

    if tFilename is not nothing then
      return StringFromNSString(tFilename)
    else
      return ""
    end if
  end handler


  /**
  Summary: Revokes your application's access to the filename pointed to by a security-scoped filename.

  Parameters:
  pFilename: A filename returned by `macsandStartAccessingFile()`.

  Description:
  When your application no longer needs access to a file or directy that you requested access to using
  `macsandStartAccessingFile()` then you must revoke the access using this handler.

  Returns: Empty
  */
  public handler macsandStopAccessingFile(in pFilename as String)
    variable tNSURL as optional ObjcObject

    unsafe
      put ObjC_NSURLAlloc() into tNSURL
      put ObjC_NSURLInitFileURLWithPath(tNSURL, StringToNSString(pFilename)) into tNSURL
      if tNSURL is not nothing then
        ObjC_NSURLStopAccessingSecurityScopedResource(tNSURL)
      end if
    end unsafe
  end handler


  private foreign handler ObjC_NSErrorLocalizedFailureReason(in pObj as ObjcRetainedId) \
        returns ObjcId binds to "objc:NSError.-localizedFailureReason"
  private foreign handler ObjC_NSErrorLocalizedDescription(in pObj as ObjcRetainedId) \
        returns ObjcId binds to "objc:NSError.-localizedDescription"


  public handler NSErrorGetString(in pErrorObj as ObjcObject) returns String
    variable tErrorString as optional ObjcObject

    unsafe
      put ObjC_NSErrorLocalizedFailureReason(pErrorObj) into tErrorString
      if tErrorString is nothing then
        put ObjC_NSErrorLocalizedDescription(pErrorObj) into tErrorString
      end if
    end unsafe

    if tErrorString is not nothing then
      return StringFromNSString(tErrorString)
    else
      return ""
    end if
  end handler

end library