From 08a876fdb177781b2fe28f4fd057a06d8421711a Mon Sep 17 00:00:00 2001 From: Nicholas Orr Date: Fri, 5 Jul 2024 15:01:57 +1000 Subject: [PATCH] Reapply "Merge branch 'development' of https://github.com/GoyaPtyLtd/BaseElements-Plugin into development" This reverts commit 50514f4553d65cc79e6e72a931ac084eae468b6f. --- docs/Compatiblity.md | 153 ---------- docs/Functions/BE_ArrayChangeValue.md | 2 +- docs/Functions/BE_ArrayDelete.md | 2 +- docs/Functions/BE_Base64_Decode.md | 0 docs/Functions/BE_Base64_Encode.md | 0 docs/Functions/BE_Base64_URL_Encode.md | 0 docs/Functions/BE_CipherDecrypt.md | 47 +++ docs/Functions/BE_CipherEncrypt.md | 49 +++ docs/Functions/BE_ClipboardFormats.md | 5 +- docs/Functions/BE_ClipboardGetFile.md | 2 +- docs/Functions/BE_ClipboardGetText.md | 2 +- docs/Functions/BE_ClipboardSetFile.md | 2 +- docs/Functions/BE_ClipboardSetText.md | 2 +- docs/Functions/BE_CurlSetOption.md | 279 ++++++++++++++++++ docs/Functions/BE_CurlTrace.md | 47 +++ docs/Functions/BE_DebugInformation.md | 36 +++ docs/Functions/BE_Decrypt_AES.md | 47 +++ docs/Functions/BE_DialogDisplay.md | 43 +++ docs/Functions/BE_DialogProgress.md | 50 ++++ docs/Functions/BE_DialogProgressUpdate.md | 51 ++++ docs/Functions/BE_Encrypt_AES.md | 47 +++ docs/Functions/BE_EvaluateJavaScript.md | 42 +++ docs/Functions/BE_ExecuteShellCommand.md | 0 docs/Functions/BE_ExecuteSystemCommand.md | 66 +++++ docs/Functions/BE_FTP_Delete.md | 89 ++++++ docs/Functions/BE_FTP_Upload.md | 83 ++++++ docs/Functions/BE_FTP_UploadFile.md | 83 ++++++ docs/Functions/BE_FileCopy.md | 46 +++ docs/Functions/BE_FileDelete.md | 47 +++ docs/Functions/BE_FileExists.md | 36 +++ docs/Functions/BE_FileListFolder.md | 66 +++++ docs/Functions/BE_FileMakerSQL.md | 43 +++ docs/Functions/BE_FileMaker_Fields.md | 0 docs/Functions/BE_FileMaker_Tables.md | 0 .../Functions/BE_FileModificationTimestamp.md | 39 +++ docs/Functions/BE_FileMove.md | 41 +++ docs/Functions/BE_FileOpen.md | 42 +++ docs/Functions/BE_FilePatternCount.md | 37 +++ docs/Functions/BE_FileReadText.md | 76 +++++ docs/Functions/BE_FileReplaceText.md | 50 ++++ docs/Functions/BE_FileSaveDialog.md | 42 +++ docs/Functions/BE_FileSelectDialog.md | 44 +++ docs/Functions/BE_FileSize.md | 36 +++ docs/Functions/BE_FileWriteText.md | 70 +++++ docs/Functions/BE_FolderCreate.md | 40 +++ docs/Functions/BE_FolderSelectDialog.md | 44 +++ docs/Functions/BE_GetLastDDLError.md | 36 +++ docs/Functions/BE_GetLastError.md | 53 ++++ docs/Functions/BE_GetMachineName.md | 36 +++ docs/Functions/BE_GetSystemDrive.md | 36 +++ docs/Functions/BE_Gzip.md | 37 +++ docs/Functions/BE_HMAC_Deprecated.md | 0 docs/Functions/BE_HTTP_DELETE.md | 48 +++ docs/Functions/BE_HTTP_GET.md | 50 ++++ docs/Functions/BE_HTTP_GET_File.md | 50 ++++ docs/Functions/BE_HTTP_PATCH.md | 63 ++++ docs/Functions/BE_HTTP_POST.md | 73 +++++ docs/Functions/BE_HTTP_PUTData.md | 64 ++++ docs/Functions/BE_HTTP_PUTFile.md | 57 ++++ docs/Functions/BE_HTTP_ResponseCode.md | 37 +++ docs/Functions/BE_HTTP_ResponseHeaders.md | 38 +++ docs/Functions/BE_HTTP_SetCustomHeader.md | 50 ++++ docs/Functions/BE_HTTP_Set_Proxy.md | 48 +++ docs/Functions/BE_JSONPath_Deprecated.md | 0 docs/Functions/BE_JSON_ArraySize.md | 40 +++ docs/Functions/BE_JSON_Encode_Deprecated.md | 0 .../BE_JSON_Error_Description_Deprecated.md | 0 docs/Functions/BE_MessageDigest.md | 44 +++ docs/Functions/BE_OpenURL.md | 37 +++ docs/Functions/BE_PDFAppend.md | 65 ++++ docs/Functions/BE_PDFGetPages.md | 41 +++ docs/Functions/BE_PDFPageCount.md | 37 +++ docs/Functions/BE_Pause.md | 36 +++ docs/Functions/BE_PreferenceDelete.md | 53 ++++ docs/Functions/BE_PreferenceGet.md | 53 ++++ docs/Functions/BE_SMTPAddAttachment.md | 53 ++++ docs/Functions/BE_SMTPSend.md | 91 ++++++ docs/Functions/BE_SMTPServer.md | 50 ++++ docs/Functions/BE_SMTPSetHeader.md | 50 ++++ docs/Functions/BE_ScriptExecute.md | 40 +++ docs/Functions/BE_ScriptStepInstall.md | 67 +++++ docs/Functions/BE_ScriptStepPerform.md | 36 +++ docs/Functions/BE_ScriptStepRemove.md | 36 +++ docs/Functions/BE_SetPreference.md | 54 ++++ docs/Functions/BE_SetTextEncoding.md | 58 ++++ docs/Functions/BE_SignatureGenerateRSA.md | 41 +++ docs/Functions/BE_SignatureVerifyRSA.md | 40 +++ docs/Functions/BE_TextExtractWords.md | 49 +++ docs/Functions/BE_TimeCurrentMilliseconds.md | 36 +++ docs/Functions/BE_TimeUTCMilliseconds.md | 37 +++ docs/Functions/BE_TimeZoneOffset.md | 36 +++ docs/Functions/BE_UnGzip.md | 37 +++ docs/Functions/BE_Unzip.md | 48 +++ docs/Functions/BE_ValuesUnique.md | 2 +- docs/Functions/BE_VariableGet.md | 9 +- docs/Functions/BE_VariableSet.md | 11 +- docs/Functions/BE_VectorDotProduct.md | 42 +++ docs/Functions/BE_VectorEuclideanDistance.md | 42 +++ docs/Functions/BE_Version.md | 40 +++ docs/Functions/BE_VersionAutoUpdate.md | 36 +++ docs/Functions/BE_XMLParse.md | 39 +++ .../Functions/BE_XMLStripInvalidCharacters.md | 37 +++ docs/Functions/BE_XMLStripNodes.md | 42 +++ docs/Functions/BE_XMLTidy.md | 36 +++ docs/Functions/BE_XMLValidate.md | 38 +++ docs/Functions/BE_XML_Canonical.md | 40 +++ docs/Functions/BE_XPath.md | 45 +++ docs/Functions/BE_XPathAll.md | 42 +++ docs/Functions/BE_XSLTApply.md | 45 +++ docs/Functions/BE_XSLT_ApplyInMemory.md | 37 +++ docs/Functions/BE_XeroSetTokens.md | 0 docs/Functions/BE_Zip.md | 58 ++++ docs/Functions/Deprecated/BE_Base64_Decode.md | 23 ++ docs/Functions/Deprecated/BE_Base64_Encode.md | 23 ++ .../Deprecated/BE_Base64_URL_Encode.md | 22 ++ .../Deprecated/BE_ExecuteShellCommand.md | 24 ++ .../Deprecated/BE_FileMaker_Fields.md | 22 ++ .../Deprecated/BE_FileMaker_Tables.md | 22 ++ docs/Functions/Deprecated/BE_HMAC.md | 26 ++ docs/Functions/Deprecated/BE_JSONPath.md | 22 ++ docs/Functions/Deprecated/BE_JSON_Encode.md | 26 ++ .../Deprecated/BE_JSON_Error_Description.md | 21 ++ docs/Functions/Deprecated/BE_XeroSetTokens.md | 23 ++ 123 files changed, 4793 insertions(+), 171 deletions(-) delete mode 100644 docs/Functions/BE_Base64_Decode.md delete mode 100644 docs/Functions/BE_Base64_Encode.md delete mode 100644 docs/Functions/BE_Base64_URL_Encode.md delete mode 100644 docs/Functions/BE_ExecuteShellCommand.md delete mode 100644 docs/Functions/BE_FileMaker_Fields.md delete mode 100644 docs/Functions/BE_FileMaker_Tables.md delete mode 100644 docs/Functions/BE_HMAC_Deprecated.md delete mode 100644 docs/Functions/BE_JSONPath_Deprecated.md delete mode 100644 docs/Functions/BE_JSON_Encode_Deprecated.md delete mode 100644 docs/Functions/BE_JSON_Error_Description_Deprecated.md delete mode 100644 docs/Functions/BE_XeroSetTokens.md create mode 100644 docs/Functions/Deprecated/BE_Base64_Decode.md create mode 100644 docs/Functions/Deprecated/BE_Base64_Encode.md create mode 100644 docs/Functions/Deprecated/BE_Base64_URL_Encode.md create mode 100644 docs/Functions/Deprecated/BE_ExecuteShellCommand.md create mode 100644 docs/Functions/Deprecated/BE_FileMaker_Fields.md create mode 100644 docs/Functions/Deprecated/BE_FileMaker_Tables.md create mode 100644 docs/Functions/Deprecated/BE_HMAC.md create mode 100644 docs/Functions/Deprecated/BE_JSONPath.md create mode 100644 docs/Functions/Deprecated/BE_JSON_Encode.md create mode 100644 docs/Functions/Deprecated/BE_JSON_Error_Description.md create mode 100644 docs/Functions/Deprecated/BE_XeroSetTokens.md diff --git a/docs/Compatiblity.md b/docs/Compatiblity.md index 41f43c4ce..cc6dd46ab 100644 --- a/docs/Compatiblity.md +++ b/docs/Compatiblity.md @@ -32,156 +32,3 @@ BE Plugins prior to 4.2.0 run just fine under Apple Silicon such as the M1 under Version 3.0.x was the last release to run under Windows XP. BE Plugin Version 1.2 and later requires FMP 11 or later because of the new SQL engine. BE 1.1 will run in ffm Pro 10 and earlier. - -## Function Compatibility - -Definitions for the table below : - -✔︎ : Tested and functional. -✕ : Does not work on this platform. -NA : Does not apply. -No value - untested or functionality is indeterminate. -Active : still in development and supported - -Also used : - -**Obsolete** : has been made redundant by native FMP functionality, but we haven't yet removed it from the plugin.  Some functions like the HTTP functions can be removed but are in use heavily so we recommend switching to native functions where you can. There are still some small uses cases that the BE function covers that the internal functions don't, so they will remain in the plugin for the foreseeable future.  However, other functions that have exact matching functionality might still have a use : eg the ValuesSort function in BE has shown to be faster in some situations than the internal one. - -**Deprecated** : has been made redundant or otherwise no longer supported, and will be removed in a future version, likely in the next major release.  These functions have native alternatives in the current BE release and will no longer appear in the function list, but do still work if used. - -**Beta** : new functionality with an as yet indeterminate feature set, so may change, or may even be removed.  Likely to change based on feedback. - -**Internal** : a very specific and custom function designed for use in BaseElements and likely not very applicable to the general public.  May not appear in function lists. - -Function Name Status Mac FMP Win FMP Mac FMS Win FMS Linux FMS iOS Thread Safe prior to 4.0.4 -ArrayChangeValue Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -ArrayDelete Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -ArrayFind Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -ArrayGetSize Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -ArrayGetValue Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -ArraySetFromValueList Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -ArrayDelete Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -CipherDecrypt Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -CipherEncrypt Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -ClipboardFormats Active ✔︎ ✔︎ ✕ ✕ ✕ ✕ NA -ClipboardGetText Active ✔︎ ✔︎ ✕ ✕ ✕ ✕ NA -ClipboardSetText Active ✔︎ ✔︎ ✕ ✕ ✕ ✕ NA -ClipboardGetFile Active ✔︎ ✔︎ ✕ ✕ ✕ ✕ NA -ClipboardSetFile Active ✔︎ ✔︎ ✕ ✕ ✕ ✕ NA -ContainerCompress Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ContainerIsCompressed Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ContainerUncompress Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ContainerConvert Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ContainerGetType Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ContainerListTypes Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -DialogDisplay Active ✔︎ ✔︎ ✕ ✕ ✕ ✕ NA -DialogProgress Active ✔︎ ✔︎ ✕ ✕ ✕ ✕ NA -DialogProgressUpdate Active ✔︎ ✔︎ ✕ ✕ ✕ ✕ NA -Decrypt_AES Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -Encrypt_AES Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -EvaluateJavaScript Beta ✔︎ ✔︎ ✕ ✕ ✔︎ ✔︎ NA -ExecuteSystemCommand Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ ✕ -ExportFieldContents Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FileCopy Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FileDelete Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FileExists Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FileImport Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FilesListInFolder Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FileMakerSQL Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -FileModificationTimestamp Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FileMove Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FileOpen Active ✔︎ ✔︎ ✔︎ ✔︎ ✕ ✕ ✔︎ -FileReadText Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FileSaveDialog Active ✔︎ ✔︎ ✕ ✕ ✕ ✕ NA -FileSelectDialog Active ✔︎ ✔︎ ✕ ✕ ✕ ✕ NA -FileSize Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FileWriteText Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FolderCreate Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FolderSelectDialog Active ✔︎ ✔︎ ✕ ✕ ✕ ✕ NA -GetLastDDLError Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ NA -GetLastError Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ NA -GetMachineName Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -GetSystemDrive Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -Gzip Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -JPEG_Recompress Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -OAuth_RequestAccessToken Beta ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -JSON_ArraySize Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -OpenURL Active ✔︎ ✔︎ ✕ ✕ ✕ ✔︎ NA -MessageDigest Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -Pause Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -PDFAppend Active ✔︎ ✔︎ ✕ ✕ ✔︎ NA -PDFPageCount Active ✔︎ ✔︎ ✕ ✕ ✔︎ NA -PDFGetPages Active ✔︎ ✔︎ ✕ ✕ ✔︎ NA -PreferenceGet Active ✔︎ ✔︎ ✔︎ ✔︎ ✕ ✔︎ ✔︎ -PreferenceSet Active ✔︎ ✔︎ ✔︎ ✔︎ ✕ ✔︎ ✔︎ -PreferenceDelete Active ✔︎ ✔︎ ✔︎ ✔︎ ✕ ✔︎ ✔︎ -RegularExpression Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ScriptExecute Active ✔︎ ✔︎ ✕ ✕ ✔︎ ✔︎ NA -ScriptStepInstall Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ScriptStepRemove Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ScriptStepPerform Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -SetTextEncoding Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -SignatureGenerate_RSA Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -SignatureVerify_RSA Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -StackPush Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ NA -StackPop Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ NA -StackCount Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ NA -StackDelete Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ NA -SMTP_AddAttachment Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -SMTP_Send Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -SMTP_Server Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -SMTP_SetHeader Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -TimeZoneOffset Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -TimeCurrentMilliseconds Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -UnGzip Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -Unzip Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -TimeUTCMilliseconds Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ValuesContainsDuplicates Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ValuesFilterOut Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ValuesSort Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ValuesTimesDuplicated Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ValuesTrim Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ValuesUnique Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -VariableGet Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ NA -VariableSet Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ NA -Vector_DotProduct Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -Vector_EuclideanDistance Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -Version Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -VersionAutoUpdate Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -Xero_GenerateKeys Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -Xero_SetTokens Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✕ -XML_Parse Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -XML_Validate Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -XOR Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -XPath Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -XPathAll Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -XSLTApply Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -XSLTApplyInMemory Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -Zip Active ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ - -SplitBEFileNodes Internal ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -StripXMLNodes Internal ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -ExtractScriptVariables Internal ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ - -FTP_Delete Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -FTP_Upload Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -JSONPath Deprecated ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -JSON_Encode Deprecated ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -JSON_Error_Description Deprecated ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -Curl_SetOption Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -Curl_Trace Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -HMAC Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -HTTP_DELETE Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -HTTP_GET Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -HTTP_GET_File Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -HTTP_PATCH Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -HTTP_POST Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -HTTP_PUT_DATA Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -HTTP_PUT_FILE Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -HTTP_Response_Code Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -HTTP_Response_Headers Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -HTTP_Set_Custom_Header Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -HTTP_Set_Proxy Obsolete ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -Base64_Decode Deprecated ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -Base64_Encode Deprecated ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ -Base64_URL_Encode Deprecated ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ ✔︎ diff --git a/docs/Functions/BE_ArrayChangeValue.md b/docs/Functions/BE_ArrayChangeValue.md index c935d06a0..7728cf1b5 100644 --- a/docs/Functions/BE_ArrayChangeValue.md +++ b/docs/Functions/BE_ArrayChangeValue.md @@ -4,7 +4,7 @@ **Description** -Changes the array item at valueNumber to newValue in array number array. +Changes the *array* item at *valueNumber* to *newValue*. **Parameters** diff --git a/docs/Functions/BE_ArrayDelete.md b/docs/Functions/BE_ArrayDelete.md index 6bfbbdf7f..3d97ce9f9 100644 --- a/docs/Functions/BE_ArrayDelete.md +++ b/docs/Functions/BE_ArrayDelete.md @@ -4,7 +4,7 @@ **Description** -Removes the array from memory. +Removes *array* from memory. **Parameters** diff --git a/docs/Functions/BE_Base64_Decode.md b/docs/Functions/BE_Base64_Decode.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/Functions/BE_Base64_Encode.md b/docs/Functions/BE_Base64_Encode.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/Functions/BE_Base64_URL_Encode.md b/docs/Functions/BE_Base64_URL_Encode.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/Functions/BE_CipherDecrypt.md b/docs/Functions/BE_CipherDecrypt.md index e69de29bb..4de09186d 100644 --- a/docs/Functions/BE_CipherDecrypt.md +++ b/docs/Functions/BE_CipherDecrypt.md @@ -0,0 +1,47 @@ +## BE_CipherDecrypt + + BE_CipherDecrypt ( cipher ; encryptedData ; key ; iv ; { paddingBoolean ; fileNameWithExtension } ) + +**Description** + +Decrypt *encryptedData* using *cipher*. + +**Parameters** + +* *cipher* ( default:AES-256-CBC ) : The cipher name to use. If the value is empty, "AES-256-CBC" will be used. +* *encryptedData* : The data to decrypt. It can be HEX encoded text or container field. +* *key* : The key to decrypt with. It can be HEX encoded text or container field. +* *iv* : The IV (initialization vector). It can be HEX encoded text or container field. +* *paddingBoolean* ( optional, default:True ) : Set false to disable padding. Padding is enabled if the parameter is true, empty or not specified. +* *fileNameWithExtension* : The filename and extension for the decrypted data if being set into a container field. + +**Keywords** + +Cipher Decrypt + +**Version History** + +* 4.0.0 : First Release + +**Notes** + +Modes that require authenticated encryption (e.g. GCM) are not supported. These ciphers return 'authentication tag' in addition to encrypted data. + +The max data length is limited to 2GB. + +The code uses OpenSSL for it's base library, so the list of ciphers and their details are here : https://www.openssl.org/docs/man1.0.2/man1/ciphers.html however not all available ciphers may work, and this list may change with future releases of openssl. + +Not all possible ciphers will work, and thorough testing on Encryption and Decryption should be done before putting code into production. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_CipherEncrypt.md b/docs/Functions/BE_CipherEncrypt.md index e69de29bb..f2326d3b3 100644 --- a/docs/Functions/BE_CipherEncrypt.md +++ b/docs/Functions/BE_CipherEncrypt.md @@ -0,0 +1,49 @@ +## BE_CipherEncrypt + + BE_CipherEncrypt ( cipher ; data ; key ; iv ; { paddingBoolean ; fileNameWithExtension } ) + +**Description** + +Decrypt *encryptedData* using *cipher*. + +**Parameters** + +* *cipher* ( default:AES-256-CBC ) : The cipher name to use. If the value is empty, "AES-256-CBC" will be used. +* *data* : The data to encrypt. It can be HEX encoded text or container field. +* *key* : The key to encrypt with. It can be HEX encoded text or container field. +* *iv* : The IV (initialization vector). It can be HEX encoded text or container field. +* *paddingBoolean* ( optional, default:True ) : Set false to disable padding. Padding is enabled if the parameter is true, empty or not specified. +* *fileNameWithExtension* : The filename and extension for the encrypt data. + +**Keywords** + +Cipher Encrypt + +**Version History** + +* 4.0.0 : First Release + +**Notes** + +Be careful, there is no undo. Modes that require authenticated encryption (e.g. GCM) are not supported. These ciphers return 'authentication tag' in addition to encrypted data. + +The max data length is limited to 2GB. + +The code uses OpenSSL for it's base library, so the list of ciphers and their details are here : https://www.openssl.org/docs/man1.0.2/man1/ciphers.html however not all available ciphers may work, and this list may change with future releases of openssl. + +Not all possible ciphers will work, and thorough testing on Encryption and Decryption should be done before putting code into production. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_CipherEncrypt ( "aes-256-cbc" ; HexEncode ( "Plain text" ) ; "603deb1015ca71be2b73aef0857d77811f352c073b6108d72d9810a30914dff4" ; "000102030405060708090a0b0c0d0e0f" ) \ No newline at end of file diff --git a/docs/Functions/BE_ClipboardFormats.md b/docs/Functions/BE_ClipboardFormats.md index ed56f6aad..70cdf68ae 100644 --- a/docs/Functions/BE_ClipboardFormats.md +++ b/docs/Functions/BE_ClipboardFormats.md @@ -43,7 +43,8 @@ or copying plain text from FileMaker on the Mac will give : So it's possible to utilise different types depending on your intended use. The different formats can be quite different, content wise, for example if you copied RichText with formatting, you clipboard may contain types of : - public.rtf public.utf8-plain-text + public.rtf + public.utf8-plain-text Only the first type would retain the format information. @@ -54,7 +55,7 @@ Only the first type would retain the format information. | Status | Active | | Mac FMP | Yes | | Win FMP | Yes | -| FMS | Yes | +| FMS | No | | iOS | No | | Linux | No | diff --git a/docs/Functions/BE_ClipboardGetFile.md b/docs/Functions/BE_ClipboardGetFile.md index 3665196f7..9702212ff 100644 --- a/docs/Functions/BE_ClipboardGetFile.md +++ b/docs/Functions/BE_ClipboardGetFile.md @@ -34,7 +34,7 @@ If the format is a binary file type, and has a filename, then that parameter is | Status | Active | | Mac FMP | Yes | | Win FMP | Yes | -| FMS | Yes | +| FMS | No | | iOS | No | | Linux | No | diff --git a/docs/Functions/BE_ClipboardGetText.md b/docs/Functions/BE_ClipboardGetText.md index ec49f7c3f..a5853c0ea 100644 --- a/docs/Functions/BE_ClipboardGetText.md +++ b/docs/Functions/BE_ClipboardGetText.md @@ -38,7 +38,7 @@ The *BE_SetTextEncoding* function does have an effect on how this result is used | Status | Active | | Mac FMP | Yes | | Win FMP | Yes | -| FMS | Yes | +| FMS | No | | iOS | No | | Linux | No | diff --git a/docs/Functions/BE_ClipboardSetFile.md b/docs/Functions/BE_ClipboardSetFile.md index 3ca8b54ad..1378826c6 100644 --- a/docs/Functions/BE_ClipboardSetFile.md +++ b/docs/Functions/BE_ClipboardSetFile.md @@ -36,7 +36,7 @@ You can only set a single format when setting the clipboard from BE, even though | Status | Active | | Mac FMP | Yes | | Win FMP | Yes | -| FMS | Yes | +| FMS | No | | iOS | No | | Linux | No | diff --git a/docs/Functions/BE_ClipboardSetText.md b/docs/Functions/BE_ClipboardSetText.md index b3ec81d72..60d110160 100644 --- a/docs/Functions/BE_ClipboardSetText.md +++ b/docs/Functions/BE_ClipboardSetText.md @@ -42,7 +42,7 @@ You can only set a single format when setting the clipboard from BE. | Status | Active | | Mac FMP | Yes | | Win FMP | Yes | -| FMS | Yes | +| FMS | No | | iOS | No | | Linux | No | diff --git a/docs/Functions/BE_CurlSetOption.md b/docs/Functions/BE_CurlSetOption.md index e69de29bb..32078214b 100644 --- a/docs/Functions/BE_CurlSetOption.md +++ b/docs/Functions/BE_CurlSetOption.md @@ -0,0 +1,279 @@ +## BE_CurlSetOption + + BE_CurlSetOption ( { option ; value } ) + +**Description** + +Sets one of the Curl library optional variables to be used in all subsequent calls to the HTTP/FTP/SMTP functions. + +The *value* depends on the type of *option*. Some require explicit values ( such as CURLOPT_USERAGENT ) and others require a boolean. + +The full list of options and their possible values is in the curl documentation : [http://curl.haxx.se/libcurl/c/curl_easy_setopt.html](http://curl.haxx.se/libcurl/c/curl_easy_setopt.html) + +**Parameters** + +* *option* ( optional ) : The option name as text from the list below. +* *value* ( optional ) : The value to pass to the option. + +* When the *value* parameter is left out then the *option* is cleared. +* When the *value* parameter is empty and the *option* supports an empty value the option will be set to the empty string. +* When no parameters are included or *option* is empty, then all values are cleared out and set back to defaults. + +**Keywords** + +HTTP Curl Option Set + +**Version History** + +* 2.1.0 : First Release. +* 3.1.0 : Made the *option* value optional and added named constants. +* 4.0.2 : Renamed from BE_Curl_Set_Option. + +**Notes** + + + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + +Restoring all values to their default can be done with : + + BE_CurlSetOption + +To return an option to it's default call the option name with no parameter : + + BE_CurlSetOption ( "CURLOPT_HTTPAUTH" ) + +The *CURLOPT_HTTPAUTH* and *CURLOPT_PROXYAUTH* options can also be set with these constants : + + CURLAUTH_BASIC + CURLAUTH_DIGEST + CURLAUTH_DIGEST_IE + CURLAUTH_NEGOTIATE + CURLAUTH_NTLM + CURLAUTH_NTLM_WB + CURLAUTH_ANY + CURLAUTH_ANYSAFE + CURLAUTH_ONLY + +**Common use cases** + +Use "Basic" Authentication + + BE_CurlSetOption ( "CURLOPT_HTTPAUTH" ; 1 ) + BE_CurlSetOption ( "CURLOPT_HTTPAUTH" ; "CURLAUTH_BASIC" ) + +**Certificate based Authentication** + +To use Certificate based Authentication for HTTP function calls you would do : + + BE_CurlSetOption ( "CURLOPT_SSLCERT" ; "/path/to/cert.pem" ) + BE_CurlSetOption ( "CURLOPT_SSLCERTTYPE" ; "PEM" ) + BE_CurlSetOption ( "CURLOPT_SSLKEY" ; "/path/to/key.pem" ) + BE_CurlSetOption ( "CURLOPT_SSLKEYTYPE" ; "PEM" ) + +With certificates, "PEM" is the default type, so can be left out. Other possible options for the types are + + PEM + DER + P12 + +P12 is for PKCS#12-encoded files. PEM files that will work with curl doing SFTP are **RSA PRIVATE KEY** files. You can open them in a text editor and you should see that the first line of the text has **RSA PRIVATE KEY** at the beginning. If it says **OPENSSH PRIVATE KEY** instead, it may not work. You can convert keys from one type to another using these instructions : + +[https://federicofr.wordpress.com/2019/01/02/how-to-convert-openssh-private-keys-to-rsa-pem/](https://federicofr.wordpress.com/2019/01/02/how-to-convert-openssh-private-keys-to-rsa-pem/) + +**Using Cookies** + +To allow curl to store and re-use cookies, set the cookie jar ( for where to store them ) and the cookie file ( for where to read them to send ). + + BE_CurlSetOption ( "CURLOPT_COOKIEFILE" ; "/path/to/cookieFile.txt" ) + BE_CurlSetOption ( "CURLOPT_COOKIEJAR" ; "/path/to/cookieFile.txt" ) + +You can use the temp folder for storing the cookie files, but make sure you're using a plugin path and not a FileMaker path created from any of the *Get* function calls. + +**Amazon Authentication** + +There's now a native option for the complex AWS authentication method using the **CURLOPT_AWS_SIGV4** option. It appears to require a string matching either "provider1:provider2" or "provider1:provider2:region:service" and you set the keys via the option values *CURLOPT_USERPWD* and "MY_ACCESS_KEY:MY_SECRET_KEY". See here for more detail : + +[https://curl.se/libcurl/c/CURLOPT_AWS_SIGV4.html](https://curl.se/libcurl/c/CURLOPT_AWS_SIGV4.html) + +Complete List of supported CURL options : + + CURLOPT_PROXY + CURLOPT_NOPROXY + CURLOPT_SOCKS5_GSSAPI_SERVICE + CURLOPT_INTERFACE + CURLOPT_NETRC_FILE + CURLOPT_USERPWD + CURLOPT_PROXYUSERPWD + CURLOPT_USERNAME + CURLOPT_PASSWORD + CURLOPT_PROXYUSERNAME + CURLOPT_PROXYPASSWORD + CURLOPT_TLSAUTH_USERNAME + CURLOPT_TLSAUTH_PASSWORD + CURLOPT_ACCEPT_ENCODING + CURLOPT_COPYPOSTFIELDS + CURLOPT_REFERER + CURLOPT_USERAGENT + CURLOPT_COOKIE + CURLOPT_COOKIEFILE + CURLOPT_COOKIEJAR + CURLOPT_COOKIELIST + CURLOPT_HTTPGET + CURLOPT_MAIL_FROM + CURLOPT_MAIL_AUTH + CURLOPT_FTPPORT + CURLOPT_FTP_ALTERNATIVE_TO_USER + CURLOPT_FTP_ACCOUNT + CURLOPT_RTSP_SESSION_ID + CURLOPT_RTSP_STREAM_URI + CURLOPT_RTSP_TRANSPORT + CURLOPT_RANGE + CURLOPT_CUSTOMREQUEST + CURLOPT_DNS_SERVERS + CURLOPT_SSLCERT + CURLOPT_SSLCERTTYPE + CURLOPT_SSLKEY + CURLOPT_SSLKEYTYPE + CURLOPT_KEYPASSWD + CURLOPT_SSLENGINE + CURLOPT_CAINFO + CURLOPT_ISSUERCERT + CURLOPT_CAPATH + CURLOPT_CRLFILE + CURLOPT_RANDOM_FILE + CURLOPT_EGDSOCKET + CURLOPT_SSL_CIPHER_LIST + CURLOPT_KRBLEVEL + CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 + CURLOPT_SSH_PUBLIC_KEYFILE + CURLOPT_SSH_PRIVATE_KEYFILE + CURLOPT_SSH_KNOWNHOSTS + CURLOPT_VERBOSE + CURLOPT_HEADER + CURLOPT_NOSIGNAL + CURLOPT_WILDCARDMATCH + CURLOPT_FAILONERROR + CURLOPT_PROXYPORT + CURLOPT_PROXYTYPE + CURLOPT_HTTPPROXYTUNNEL + CURLOPT_SOCKS5_GSSAPI_NEC + CURLOPT_LOCALPORT + CURLOPT_LOCALPORTRANGE + CURLOPT_DNS_CACHE_TIMEOUT // CURLOPT_DNS_USE_GLOBAL_CACHE - removed in 4.2.0 + CURLOPT_BUFFERSIZE + CURLOPT_PORT + CURLOPT_TCP_NODELAY + CURLOPT_ADDRESS_SCOPE + CURLOPT_TCP_KEEPALIVE + CURLOPT_TCP_KEEPIDLE + CURLOPT_TCP_KEEPINTVL + CURLOPT_NETRC + CURLOPT_HTTPAUTH + CURLOPT_TLSAUTH_TYPE + CURLOPT_PROXYAUTH + CURLOPT_AUTOREFERER + CURLOPT_TRANSFER_ENCODING + CURLOPT_FOLLOWLOCATION + CURLOPT_UNRESTRICTED_AUTH + CURLOPT_MAXREDIRS + CURLOPT_PUT + CURLOPT_POST + CURLOPT_POSTFIELDSIZE + CURLOPT_COOKIESESSION + CURLOPT_HTTP_VERSION + CURLOPT_IGNORE_CONTENT_LENGTH + CURLOPT_HTTP_CONTENT_DECODING + CURLOPT_HTTP_TRANSFER_DECODING + CURLOPT_TFTP_BLKSIZE + CURLOPT_FTPPORT + CURLOPT_DIRLISTONLY + CURLOPT_APPEND + CURLOPT_FTP_USE_EPRT + CURLOPT_FTP_USE_EPSV + CURLOPT_FTP_USE_PRET + CURLOPT_FTP_CREATE_MISSING_DIRS + CURLOPT_FTP_RESPONSE_TIMEOUT + CURLOPT_FTP_SKIP_PASV_IP + CURLOPT_FTPSSLAUTH + CURLOPT_FTP_SSL_CCC + CURLOPT_FTP_FILEMETHOD + CURLOPT_RTSP_REQUEST + CURLOPT_RTSP_CLIENT_CSEQ + CURLOPT_RTSP_SERVER_CSEQ + CURLOPT_TRANSFERTEXT + CURLOPT_PROXY_TRANSFER_MODE + CURLOPT_CRLF + CURLOPT_RESUME_FROM + CURLOPT_FILETIME + CURLOPT_NOBODY + CURLOPT_INFILESIZE + CURLOPT_UPLOAD + CURLOPT_MAXFILESIZE + CURLOPT_TIMECONDITION + CURLOPT_TIMEVALUE + CURLOPT_TIMEOUT + CURLOPT_TIMEOUT_MS + CURLOPT_LOW_SPEED_TIME + CURLOPT_MAXCONNECTS + CURLOPT_FRESH_CONNECT + CURLOPT_FORBID_REUSE + CURLOPT_CONNECTTIMEOUT + CURLOPT_CONNECTTIMEOUT_MS + CURLOPT_IPRESOLVE + CURLOPT_CONNECT_ONLY + CURLOPT_USE_SSL + CURLOPT_ACCEPTTIMEOUT_MS + CURLOPT_SSLENGINE_DEFAULT + CURLOPT_SSLVERSION + CURLOPT_SSL_VERIFYPEER + CURLOPT_SSL_VERIFYHOST + CURLOPT_CERTINFO + CURLOPT_SSL_SESSIONID_CACHE + CURLOPT_GSSAPI_DELEGATION + CURLOPT_SSH_AUTH_TYPES + CURLOPT_NEW_FILE_PERMS + CURLOPT_NEW_DIRECTORY_PERMS + CURLOPT_POSTFIELDSIZE_LARGE + CURLOPT_RESUME_FROM_LARGE + CURLOPT_INFILESIZE_LARGE + CURLOPT_MAXFILESIZE_LARGE + CURLOPT_MAX_SEND_SPEED_LARGE + CURLOPT_MAX_RECV_SPEED_LARGE + +Added in 4.2.0 : + + CURLOPT_CONNECT_TO + CURLOPT_TCP_FASTOPEN + CURLOPT_KEEP_SENDING_ON_ERROR + CURLOPT_SUPPRESS_CONNECT_HEADERS + CURLOPT_SOCKS5_AUTH + CURLOPT_REQUEST_TARGET + CURLOPT_SSH_COMPRESSION + CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS + CURLOPT_DNS_SHUFFLE_ADDRESSES + CURLOPT_HAPROXYPROTOCOL + CURLOPT_DISALLOW_USERNAME_IN_URL + CURLOPT_TLS13_CIPHERS + CURLOPT_PROXY_TLS13_CIPHERS + CURLOPT_UPLOAD_BUFFERSIZE + CURLOPT_DOH_URL + CURLOPT_MAXAGE_CONN + CURLOPT_MAIL_RCPT_ALLLOWFAILS + CURLOPT_PROXY_ISSUERCERT + CURLOPT_AWS_SIGV4 + + + + diff --git a/docs/Functions/BE_CurlTrace.md b/docs/Functions/BE_CurlTrace.md index e69de29bb..1574fe50e 100644 --- a/docs/Functions/BE_CurlTrace.md +++ b/docs/Functions/BE_CurlTrace.md @@ -0,0 +1,47 @@ +## BE_CurlTrace + + BE_CurlTrace + +**Description** + +Returns a complete trace of the HTTP, FTP, and SMTP details for the most recent function call. This is useful for debugging connection issues. + +**Parameters** + +None + +**Keywords** + +HTTP FTP SMTP Curl Trace + +**Version History** + +* 3.1.0 : First Release +* 4.0.2 : Renamed from BE_Curl_Trace + +**Notes** + +This is to get the HTTP, FTP or SMTP transcript of the connection so that you can more easily diagnose connections issues, especially for encrypted connections ( https or SMTP with SSL ) where you can't listen in to the connection. + +This behaves the same as the Error functions in that it only remembers the last HTTP/SMTP/FTP call. + +This functionality is enabled by default and can be disabled by setting the Curl Option CURLOPT_VERBOSE. + + BE_CurlSetOption ( "CURLOPT_VERBOSE" ; 0 ) + +Error codes encountered during curl operations come from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_DebugInformation.md b/docs/Functions/BE_DebugInformation.md index e69de29bb..f926833e6 100644 --- a/docs/Functions/BE_DebugInformation.md +++ b/docs/Functions/BE_DebugInformation.md @@ -0,0 +1,36 @@ +## BE_DebugInformation + + BE_DebugInformation + +**Description** + +Debugging information that is useful when reporting issues with the plugin. Will not contain any passwords but may contain sensitive information such as traces from previous HTTP function calls. + +**Parameters** + +NA + +**Keywords** + +Debug Information + +**Version History** + +* 4.1.0 : First Release + +**Notes** + +Please submit this information whenever you are reporting an issue or requesting support with a function not behaving as documented. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_Decrypt_AES.md b/docs/Functions/BE_Decrypt_AES.md index e69de29bb..a49c1372c 100644 --- a/docs/Functions/BE_Decrypt_AES.md +++ b/docs/Functions/BE_Decrypt_AES.md @@ -0,0 +1,47 @@ +## BE_Decrypt_AES + + BE_Decrypt_AES ( key ; text ) + +**Description** + +Decrypts the value in *text* encrypted with the BE_Encrypt_AES function and using the supplied *key*. + +Result is the original unencrypted text or ? for errors. Use the BE_GetLastError function to check for a successful result. + +**Parameters** + +* *key* : The secret key used in the BE_Encrypt_AES function when the text was encrypted. +* *text* : The text to be encrypted. + +**Keywords** + +Decrypt AES + +**Version History** + +* 2.3.0 : First Release +* 4.0.0 : Deprecated with a recommendation to use the FileMaker 16 function *CryptDecrypt* ( data ; key ) instead. +* 4.1.0 : Removed the deprecation. + +**Notes** + +We removed the deprecation as the native *CryptDecrypt* function doesn't quite do all the same things that our function does, so there is still room for both. We do recommend users use the native function where it's suitable. + +The intention of this is purely that anything encrypted by the plugin can only be decrypted by the plugin and there is no guarantee that the methods and code used is the same as any other external AES encryption. + +Although it is based on open standards, and you may find that you can encrypt/decrypt with software other than the BE plugin, it isn't guaranteed. + +Specific external compatibility testing would be useful to add. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_DialogDisplay.md b/docs/Functions/BE_DialogDisplay.md index e69de29bb..1a5d0e296 100644 --- a/docs/Functions/BE_DialogDisplay.md +++ b/docs/Functions/BE_DialogDisplay.md @@ -0,0 +1,43 @@ +## BE_DialogDisplay + + BE_DialogDisplay ( title ; message ; defaultButton ; { cancelButton ; alternateButton } ) + +**Description** + +Puts up a dialog almost exactly the same as the one that you can get with the Show Custom Dialog script step, minus the fields. Use this function when you want to display a dialog from a calculation instead of a script step. + +Result is the number of the button clicked - use the Constants as text replacements for button numbers. + +**Parameters** + +* *title* : The dialog title. +* *message* : The content of the dialog. +* *defaultButton* : Right most button text. +* *cancelButton* : Left most button text. +* *alternateButton* : Alternate button text. + +**Keywords** + +Dialog Display + +**Version History** + +* 1.0.0 : First Release +* 4.0.2 : Renamed from BE_DisplayDialog + +**Notes** + +The original intent of this function was that the built in step didn't allow you to customise some parts of the dialog, so this was critical for things like translated solutions. With newer changes to FileMaker's native script step, this isn't as necessary however as a function imstead of a script step you can have other options to display dialogs. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | No | +| iOS | No | +| Linux | No | + +**Example Code** diff --git a/docs/Functions/BE_DialogProgress.md b/docs/Functions/BE_DialogProgress.md index e69de29bb..406d3107f 100644 --- a/docs/Functions/BE_DialogProgress.md +++ b/docs/Functions/BE_DialogProgress.md @@ -0,0 +1,50 @@ +## BE_DialogProgress + + BE_DialogProgress ( title ; description ; { maximum } ) + +**Description** + +Shows either a barber pole progress dialog by leaving the *maximum* parameter out, or a regular start to finish progress dialog. + +**Parameters** + +* *title* : The dialog title. +* *description* : The content of the dialog. +* *maximum* ( optional ) : A positive integer for a progress dialog, or empty for barber pole. + +**Keywords** + +Dialog Progress + +**Version History** + +* 2.1.0 : First Release +* 4.0.0 : Return error 3, command not available on iOS, Linux and under FMS. +* 4.0.2 : Renamed from BE_ProgressDialog + +**Notes** + +You can disable the "Cancel" button by calling the Allow User Abort [Off] script step prior to calling this function. + +Barber pole dialogs are closed by calling BE_DialogProgressUpdate with a positive integer "number" parameter. Regular dialogs are closed with any value greater than maximum. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | No | +| iOS | No | +| Linux | No | + +**Example Code** + + BE_DialogProgress ( "title" ; "description" ) + +Will show the barber pole dialog. + + BE_DialogProgress ( "title" ; "description" ; 9 ) + +Will show a progress dialog with 10 steps ( 0 through 9 inclusive ). \ No newline at end of file diff --git a/docs/Functions/BE_DialogProgressUpdate.md b/docs/Functions/BE_DialogProgressUpdate.md index e69de29bb..a43d24790 100644 --- a/docs/Functions/BE_DialogProgressUpdate.md +++ b/docs/Functions/BE_DialogProgressUpdate.md @@ -0,0 +1,51 @@ +## BE_DialogProgressUpdate + + BE_DialogProgressUpdate ( number ; { description } ) + +**Description** + +Used to either close a *BE_DialogProgress* dialog, or advance a progress dialog to the next step. + +**Parameters** + +* *number* : The number to move the progress bar to. +* *description* ( optional, default:previous value ) : The text to put into the dialog description. If not included it will use the last value sent to this function, or will use the value that initially was set via *BE_DialogProgress*. + +**Keywords** + +Dialog Progress Update + +**Version History** + +* 2.1.0 : First Release +* 4.0.0 : Return error 3, command not available on iOS, Linux and under FMS. +* 4.0.2 : Renamed from BE_ProgressDialog_Update + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | No | +| iOS | No | +| Linux | No | + +**Example Code** + + BE_DialogProgressUpdate ( 1 ; "description" ) + +Will close a dialog if created with empty as the maximum - eg Barber Pole. + + BE_DialogProgressUpdate ( $nextValue ; "description" ) + +Move the progress dialog, along to the next value, while updating the description text. + + BE_DialogProgressUpdate ( 10 ) + +Close a progress dialog that started with maximum 9, and had 10 steps ( 0 through 9 ). diff --git a/docs/Functions/BE_Encrypt_AES.md b/docs/Functions/BE_Encrypt_AES.md index e69de29bb..b016fad51 100644 --- a/docs/Functions/BE_Encrypt_AES.md +++ b/docs/Functions/BE_Encrypt_AES.md @@ -0,0 +1,47 @@ +## BE_Decrypt_AES + + BE_Decrypt_AES ( key ; text ) + +**Description** + +Encrypts the value in *text* encrypted with AES encryption using the supplied *key*. + +Result is the encrypted text or ? for errors. Use the BE_GetLastError function to check for a successful result. + +**Parameters** + +* *key* : The secret key to use to encrypt the string. +* *text* : The text to be encrypted. + +**Keywords** + +Decrypt AES + +**Version History** + +* 2.3.0 : First Release +* 4.0.0 : Deprecated with a recommendation to use the FileMaker 16 function *CryptEncrypt* ( data ; key ) instead. +* 4.1.0 : Removed the deprecation. + +**Notes** + +We removed the deprecation as the native *CryptEncrypt* function doesn't quite do all the same things that our function does, so there is still room for both. We do recommend users use the native function where it's suitable. + +The intention of this is purely that anything encrypted by the plugin can only be decrypted by the plugin and there is no guarantee that the methods and code used is the same as any other external AES encryption. + +Although it is based on open standards, and you may find that you can encrypt/decrypt with software other than the BE plugin, it isn't guaranteed. + +Specific external compatibility testing would be useful to add. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_EvaluateJavaScript.md b/docs/Functions/BE_EvaluateJavaScript.md index e69de29bb..1c8164ac5 100644 --- a/docs/Functions/BE_EvaluateJavaScript.md +++ b/docs/Functions/BE_EvaluateJavaScript.md @@ -0,0 +1,42 @@ +## BE_EvaluateJavaScript + + BE_EvaluateJavaScript ( javaScript ) + +**Description** + +Evaluates the JavaScript passed to it as text and returns a result, if any. + +**Parameters** + +* *javaScript* : the JavaScript to evaluate. + +**Keywords** + +JavaScript + +**Version History** + +* 3.1.0 : First Release + +**Notes** + +There are also two callback functions, so you can call FileMaker calculations using BE_Evaluate_FileMaker_Calculation or run FileMaker Script using BE_ExecuteScript from within the JavaScript code. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Testing | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | No | +| iOS | No | +| Linux | No | + +Marked as **Testing** as it's not widely used, and functionality may change in the future, or even be removed. + +This function uses the [Duktape](https://duktape.org) library. We have not had many reports of people using this library in useful ways, so it may become deprecated in a future release. + +The other direction this library could go is that we use it to add new built in BE plugin functions, that are purely js run via Duktape - we're open to ideas and suggestions for options here. + +**Example Code** diff --git a/docs/Functions/BE_ExecuteShellCommand.md b/docs/Functions/BE_ExecuteShellCommand.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/Functions/BE_ExecuteSystemCommand.md b/docs/Functions/BE_ExecuteSystemCommand.md index e69de29bb..db2e7a46a 100644 --- a/docs/Functions/BE_ExecuteSystemCommand.md +++ b/docs/Functions/BE_ExecuteSystemCommand.md @@ -0,0 +1,66 @@ +## BE_ExecuteSystemCommand + + BE_ExecuteSystemCommand ( command ; { timeout ; executeUsingShell } ) + +**Description** + +Performs a command line script of the *command* parameter. Similar to using the same command using Terminal on the Mac, or CMD.exe on Windows, but with **lots of caveats** as to the differences ( see Notes below ). + +**Parameters** + +* *command* : The command to run. +* *timeout* ( optional, default:empty ) : A value, in milliseconds that the plugin should wait for a result before returning. No value specified will wait indefinitely ( not recommended ) and a value of 0 will return immediately. +* *executeUsingShell* ( optional, default:True ) : whether to execute the command directly or in a shell. + +**Keywords** + +Execute System Command Shell + +**Version History** + +* 2.0.0 : First Release +* 4.0.6 : Switched to a different library to perform the command, which broke a lot of things, and meant it could only run one command at a time +* 4.1.3 : Do not crash when attempting to execute an empty command. +* 4.1.3 : macOS, Linux and iOS enable multiple calls to shell like version 4.0.5 +* 4.2.0 : Reverted back to the 4.0.5 option and fixed the crash issue, and added executeUsingShell as an option + +**Notes** + +You can string multiple commands together in a single plugin function call by using Char ( 10 ) on Mac and Char ( 13 ) on Windows as command separators, but only when using *executeUsingShell* set to True. + +**This function call does not behave the same as when running the same command in Terminal or CMD.exe.** + +Some things to note : + +This function will not start with the same default location as a normal terminal command. + +This function will not always run as the same user as the normal shell, especially when running on Server where the process runs as the fmserver user, so permissions may be different between this command and the terminal. For example, you may have access to read the location to an executable, but not to run it. Or permission to run it but not to access the data you send to it. + +This function may not have access to default environment variables as a normal user, so things like paths to commands may not exist. Run the *printenv* command from the terminal and also from the BE plugin and compare the two, to see if there are differences. + +Escaping quotes on Windows is complex and fraught with issues. The most common issue people have with running commands is how to escape quotes so that they appear in the right place in the command you're running. However quotes on windows are not simple, and we recommend people read this for more info : + +[https://stackoverflow.com/questions/355988/how-do-i-deal-with-quote-characters-when-using-cmd-exe](https://stackoverflow.com/questions/355988/how-do-i-deal-with-quote-characters-when-using-cmd-exe) + +Using the | pipe character on windows is known to not work. + +This function returns anything send to stdout and everything else needs to be captured by the command you're running. + +--- + +Given all of that, if you're unable to get a command to run the issue is likely to do with what the command is trying to do, and the complexities of users, permissions, paths, errors, encoding, quoting, and not to do with the implementation of this function. It's unlikely that we can fix your function call. + +If you're copying and pasting a command from somewhere and expecting it to work without understanding the underlying intricacies of the operating system and it's shell, you'l have a hard time trying to debug your command. Especially if the command "works" when you run it manually outside of the plugin. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | No | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_FTP_Delete.md b/docs/Functions/BE_FTP_Delete.md index e69de29bb..967b208cf 100644 --- a/docs/Functions/BE_FTP_Delete.md +++ b/docs/Functions/BE_FTP_Delete.md @@ -0,0 +1,89 @@ +## BE_FTP_Delete + + BE_FTP_Delete ( url ; { username ; password } ) + +**Description** + +Deletes a file at a specific ftp or sftp url. + +**Parameters** + +* *url* : The url to connect to the server and the path to locate the file to delete. +* *username* ( optional ) : The username if the url requires authentication. +* *password* ( optional ) : The password if the url requires authentication. + +The url is both the server connection detail as : + + protocol://server:port/ + +and the path the file to delete, eg : + + protocol://server:port/path/to/file/to/delete.txt + +See the notes for more info about paths. + +**Keywords** + +FTP Delete Curl + +**Version History** + +* 3.2.0 : First Release + +**Notes about paths** + +Our limited testing seems to be that when using the *BE_FTP_Delete* function, the path is a relative path, not an absolute path. So when you login to the server, you often get put into a "home" folder, such that the current path at login time is : + + /home/nick + +So to delete a file at the path /home/nick/folder/file.txt you will need to use the url as : + + sftp://example.com:2000/folder/file.txt + +and leave out the current folder. This is the opposite to the *BE_FTP_Upload* and *BE_FTP_UploadFile* functions where the path is absolute. With an upload of the same file, you would use : + + sftp://example.com:2000/home/nick/folder/file.txt + +To upload the same file as the delete example. + +The simple way to check for paths and default folders is to use an FTP client with a graphical user interface which shows the current folder hierarchy. + +This may be an artefact of the particular server we test with, or may be a default with curl, or may be because of the way that we've implemented the functions with curl, and so may be different from other FTP clients. + +**Notes** + +This function supports ftp, sftp and ftps. The url prefix determines what type of connection it uses, see examples below. + +Headers can be set beforehand with *BE_HTTP_SetCustomHeader*. Authentication types and other options can be set beforehand with the *BE_CurlSetOption* function. + +Different servers may or may not respond with any data on this function call, so use *BE_GetLastError* to determine if the call was able to be made or not, and then the other HTTP functions for more information + +Error codes that you get from the *BE_GetLastError* function after this function call comes from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +Also use the *BE_CurlTrace* function to see the transcript of the connection to diagnose any other issues that may have come up and can't be determined from the error value alone. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +This function has been superseded by the Insert From URL script step, and may be deprecated in a future release. However the BE functions allow for a larger number of curl options, have a better response mechanism with the separate BE_HTTP_ResponseCode function, and have the advantage of not being a single script step. Whether or not to deprecate the BE functions depends on end user needs. + +**Example Code** + +Connecting to a standard FTP server to delete a file : + + BE_FTP_Delete ( "ftp://example.com/path/folder/file.txt" ) + +Connecting to an SFTP server : + + BE_FTP_Delete ( "sftp://example.com:2000/path/folder/file.txt" ; "account" ; "password" ) + diff --git a/docs/Functions/BE_FTP_Upload.md b/docs/Functions/BE_FTP_Upload.md index e69de29bb..2f241632f 100644 --- a/docs/Functions/BE_FTP_Upload.md +++ b/docs/Functions/BE_FTP_Upload.md @@ -0,0 +1,83 @@ +## BE_FTP_Upload + + BE_FTP_Upload ( url ; data ; { username ; password } ) + +**Description** + +Uploads the to the ftp/sftp/ftps *url* specified, using the *data* from a container field. + +**Parameters** + +* *url* : The url to connect to the server, with the path to locate the file to upload, and the filename to upload as. +* *data* : The container field file to upload. +* *username* ( optional ) : The username if the url requires authentication. +* *password* ( optional ) : The password if the url requires authentication. + +The url is both the server connection detail as : + + protocol://server:port/ + +and the path is both the location of the file to upload and the name of the file to upload, eg : + + protocol://server:port/path/to/file/to/upload.txt + +See the notes for more info about paths. + +**Keywords** + +FTP Upload Curl + +**Version History** + +* 3.0.0 : First Release + +**Notes about paths** + +Our limited testing seems to be that when using the *BE_FTP_Upload* function, the path is an absolute path, not an relative path to the users default. So when you login to the server, you often get put into a "home" folder, such that the current path at login time is : + + /home/nick + +So to upload a file at the path /home/nick/folder/file.txt you will need to use the url as : + + sftp://example.com:2000/home/nick/folder/file.txt + +So you need to use the full path to the location. Also note that you can't often get outside your own home folder, so any other path would fail. This is the opposite to the *BE_FTP_Delete* and function where the path is a relative path. So to delete the same file you uploaded above, you would use : + + sftp://example.com:2000/folder/file.txt + +The simple way to check for paths and default folders is to use an FTP client with a graphical user interface which shows the current folder hierarchy. + +This may be an artefact of the particular server we test with, or may be a default with curl, or may be because of the way that we've implemented the functions with curl, and so may be different from other FTP clients. + +**Notes** + +This function supports ftp, sftp and ftps. The url prefix determines what type of connection it uses, see examples below. + +Headers can be set beforehand with *BE_HTTP_SetCustomHeader*. Authentication types and other options can be set beforehand with the *BE_CurlSetOption* function. + +Different servers may or may not respond with any data on this function call, so use *BE_GetLastError* to determine if the call was able to be made or not, and then the other HTTP functions for more information afterwards. + +Error codes that you get from the *BE_GetLastError* function after this function call comes from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +Also use the *BE_CurlTrace* function to see the transcript of the connection to diagnose any other issues that may have come up and can't be determined from the error value alone. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +This function has been superseded by the Insert From URL script step, and may be deprecated in a future release. However the BE functions allow for a larger number of curl options, have a better response mechanism with the separate BE_HTTP_ResponseCode function, and have the advantage of not being a single script step. Whether or not to deprecate the BE functions depends on end user needs. + +**Example Code** + + BE_FTP_Upload ( "ftp://example.com/path/folder/" & GetContainerAttribute ( FTP::File ; "filename" ) ; FTP::File ) + + BE_FTP_Upload ( "sftp://example.com:2000/path/folder/" & GetContainerAttribute ( FTP::File ; "filename" ) ; FTPTest::File ; "account" ; "password" ) diff --git a/docs/Functions/BE_FTP_UploadFile.md b/docs/Functions/BE_FTP_UploadFile.md index e69de29bb..34551ec94 100644 --- a/docs/Functions/BE_FTP_UploadFile.md +++ b/docs/Functions/BE_FTP_UploadFile.md @@ -0,0 +1,83 @@ +## BE_FTP_UploadFile + + BE_FTP_UploadFile ( url ; pathToFile ; { username ; password } ) + +**Description** + +Uploads the to the ftp/sftp/ftps *url* specified, using the *pathToFile* as the location of the file to upload from disk. + +**Parameters** + +* *url* : The url to connect to the server, with the path to locate the file to upload, and the filename to upload as. +* *pathToFile* : A plugin path to the file on disk. +* *username* ( optional ) : The username if the url requires authentication. +* *password* ( optional ) : The password if the url requires authentication. + +The url is both the server connection detail as : + + protocol://server:port/ + +and the path is both the location of the file to upload and the name of the file to upload, eg : + + protocol://server:port/path/to/file/to/upload.txt + +See the notes for more info about paths. + +**Keywords** + +FTP Upload File Path Curl + +**Version History** + +* 4.2.0 : First Release + +**Notes about paths** + +Our limited testing seems to be that when using the *BE_FTP_UploadFile* function, the destination path is an absolute path, not an relative path to the users default. So when you login to the server, you often get put into a "home" folder, such that the current path at login time is : + + /home/nick + +So to upload a file at the path /home/nick/folder/file.txt you will need to use the url as : + + sftp://example.com:2000/home/nick/folder/file.txt + +So you need to use the full path to the location. Also note that you can't often get outside your own home folder, so any other path would fail. This is the opposite to the *BE_FTP_Delete* and function where the path is a relative path. So to delete the same file you uploaded above, you would use : + + sftp://example.com:2000/folder/file.txt + +The simple way to check for paths and default folders is to use an FTP client with a graphical user interface which shows the current folder hierarchy. + +This may be an artefact of the particular server we test with, or may be a default with curl, or may be because of the way that we've implemented the functions with curl, and so may be different from other FTP clients. + +**Notes** + +This function supports ftp, sftp and ftps. The url prefix determines what type of connection it uses, see examples below. + +Headers can be set beforehand with *BE_HTTP_SetCustomHeader*. Authentication types and other options can be set beforehand with the *BE_CurlSetOption* function. + +Different servers may or may not respond with any data on this function call, so use *BE_GetLastError* to determine if the call was able to be made or not, and then the other HTTP functions for more information afterwards. + +Error codes that you get from the *BE_GetLastError* function after this function call comes from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +Also use the *BE_CurlTrace* function to see the transcript of the connection to diagnose any other issues that may have come up and can't be determined from the error value alone. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +This function has been superseded by the Insert From URL script step, and may be deprecated in a future release. However the BE functions allow for a larger number of curl options, have a better response mechanism with the separate BE_HTTP_ResponseCode function, and have the advantage of not being a single script step. Whether or not to deprecate the BE functions depends on end user needs. + +**Example Code** + + BE_FTP_UploadFile ( "ftp://example.com/path/folder/myfilname.txt" ; "/Volumes/HD/Path/To/myfilname.txt" ) + + BE_FTP_UploadFile ( "sftp://example.com:2000/path/folder/myfilname.txt" ; "/Volumes/HD/Path/To/myfilname.txt" ; "account" ; "password" ) diff --git a/docs/Functions/BE_FileCopy.md b/docs/Functions/BE_FileCopy.md index e69de29bb..faa848277 100644 --- a/docs/Functions/BE_FileCopy.md +++ b/docs/Functions/BE_FileCopy.md @@ -0,0 +1,46 @@ +## BE_FileCopy + + BE_FileCopy ( fromFilePath ; toFilePath {; replaceDestinationFile } ) + +**Description** + +Deletes the file at location path. + +**Parameters** + +* *fromFilePath* : a plugin file path to copy from. +* *toFilePath* : a plugin file path destination, including filename. +* *replaceDestinationFile* : whether to overwrite an existing file. + +**Keywords** + +File Copy Path + +**Version History** + +* 1.1.0 : First Release +* 1.2.0 : Added support for copying directories +* 4.0.2 : Renamed from BE_CopyFiles + +**Notes** + +This function does not behave the same as /bin/cp. + +Important to note that the 'to' path needs to end with the desired name of the file. + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_FileCopy ( "/Users/username/Desktop/fileA.fp7" ; "/Users/username/path/to/file/fileA_copy.fp7" ) \ No newline at end of file diff --git a/docs/Functions/BE_FileDelete.md b/docs/Functions/BE_FileDelete.md index e69de29bb..91e14f83b 100644 --- a/docs/Functions/BE_FileDelete.md +++ b/docs/Functions/BE_FileDelete.md @@ -0,0 +1,47 @@ +## BE_FileDelete + + BE_FileDelete ( path ) + +**Description** + +Deletes the file at location path. + +**Parameters** + +* *path* : a plugin file path. + +**Keywords** + +File Delete Path + +**Version History** + +* 1.0.0 : First Release +* 4.0.2 : Renamed from BE_DeleteFile + +**Notes** + +This function doesn't send files to the trash or recycle bin, so use with caution. Files deleted are gone. + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_DeleteFile ( "/Users/username/Desktop/myNewFolder" ) + +deletes a folder and all of it's contents + + BE_DeleteFile ( "/Users/username/Desktop/fileA.fp7" ) + +deletes a file diff --git a/docs/Functions/BE_FileExists.md b/docs/Functions/BE_FileExists.md index e69de29bb..154b621a7 100644 --- a/docs/Functions/BE_FileExists.md +++ b/docs/Functions/BE_FileExists.md @@ -0,0 +1,36 @@ +## BE_FileExists + + BE_FileExists ( path ) + +**Description** + +Checks if the file or folder given in the *path* exists and returns True or False. For folders it accepts the name of the folder ( and reports existence correctly ) with or without a trailing /. + +**Parameters** + +* *path* : a plugin file path. + +**Keywords** + +File Exists Path + +**Version History** + +* 1.0.0 : First Release + +**Notes** + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_FileListFolder.md b/docs/Functions/BE_FileListFolder.md index e69de29bb..c00bae4cd 100644 --- a/docs/Functions/BE_FileListFolder.md +++ b/docs/Functions/BE_FileListFolder.md @@ -0,0 +1,66 @@ +## BE_FileListFolder + + BE_FileListFolder ( path { ; type ; includeSubdirBoolean ; useFullPathBoolean ; includeHiddenBoolean } ) + +**Description** + +Lists the contents of a folder at the *path*, both files and folders by default or use a *type* from *BE_FileTypeAll*, *BE_FileTypeFile*, or *BE_FileTypeFolder*. + +**Parameters** + +* *path* : description. +* *type* : description. +* *includeSubdirBoolean* ( optional, default:False ) : whether to scan sub directories. +* *useFullPathBoolean* ( optional, default:False ) : whether to include the full path in the output. +* *includeHiddenBoolean* ( optional, default:False ) : whether to include files or folder not normally visible. + +With the *includeSubdirectories* parameter set to true, it will recursively go into every sub folder and return all the results it finds. Be aware that this could go on for a long time, and is not recommended. + +With *useFullPath* set to True it will change the output to include full paths instead of just filenames. + +**Keywords** + +File Folder List Path + +**Version History** + +* 1.1.0 : First Release +* 1.2.0 : Added the optional type parameter +* 2.3.0 : Added the optional includeSubdirectories and useFullPath parameters +* 4.0.0 : Added the optional includeHidden parameter +* 4.1.3 : Correctly handle file names containing Unicode Characters on Windows + +**Notes** + +The includeSubdirectories option means that it will try every single subfolder. Be cautious when using this as it may take a long time to traverse all the sub folders. + +Also it is more than likely that at some point it will throw an error as it will come across a folder or file it doesn't have access to. Then the function will stop and return error 13, and no data. Managing individual errors like that amongst a potentially large set of files is beyond the scope of this function as implemented. + +If you're getting error 13 when using this flag, consider doing without it and traversing the sub folders via script or recursion and ignoring the access error codes instead. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_FileListFolder ( BE_FolderSelectDialog ( "" ) ) + + BE_FileListFolder ( "/Users/nick/Desktop" ) + + BE_FileListFolder ( $path ; BE_FileType_Folder ; False ; True ; True ) + +This last one will start at $path, but only return folders, and will not include subdirectories, will return a full path not just the folder names, and will include any hidden folders. : + + BE_FileListFolder ( $path ; BE_FileType_Folder ; + False ; //don't scan sub folders + True ; //include a full path + True ) //include hidden files + diff --git a/docs/Functions/BE_FileMakerSQL.md b/docs/Functions/BE_FileMakerSQL.md index e69de29bb..c2cd64739 100644 --- a/docs/Functions/BE_FileMakerSQL.md +++ b/docs/Functions/BE_FileMakerSQL.md @@ -0,0 +1,43 @@ +## BE_FileMakerSQL + + BE_FileMakerSQL ( sqlStatement ; { columnSeparator ; rowSeparator ; databaseName ; asText ; outputPath } ) + +**Description** + +Performs SQL commands on the tables inside FileMaker. + +**Parameters** + +* *sqlStatement* : the SQL command to perform. +* *columnSeparator* ( optional ) : the column separator for the output data - single characters only. +* *rowSeparator* ( optional ) : the row separator for the output data - single characters only. +* *databaseName* ( optional ) : allows you to specify an open database other than the current one +* *asText* ( optional, default:True ) : This is True by default as the SQL returns data from fields as text. Set this to false when retrieving a single container field. +* *outputPath* ( optional ) : Allows you to write the result of the SQL query to disk. + +**Keywords** + +SQL + +**Version History** + +* 1.2.0 : First Release +* 1.3.0 : added optional database parameter to allow operations on databases other than the current one +* 4.2.0 : return container/binary data in addition to text (new asText parameter) and outputPath parameter added + +**Notes** + +The new *asText* parameter when set to False allows you to return a single file, when running SQL on container fields. So although you can perform an SQL query that selects multiple container fields at once, writing them to a container field doesn't make sense, and writing to disk becomes complex when matched with a need to specify all the paths and filenames. So this function is, by design, limited to a single container field at a time. If you need multiple fields, use a loop script, or while function. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_FileMaker_Fields.md b/docs/Functions/BE_FileMaker_Fields.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/Functions/BE_FileMaker_Tables.md b/docs/Functions/BE_FileMaker_Tables.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/Functions/BE_FileModificationTimestamp.md b/docs/Functions/BE_FileModificationTimestamp.md index e69de29bb..bf07335a2 100644 --- a/docs/Functions/BE_FileModificationTimestamp.md +++ b/docs/Functions/BE_FileModificationTimestamp.md @@ -0,0 +1,39 @@ +## BE_FileModificationTimestamp + + BE_FileModificationTimestamp ( path ) + +**Description** + +Returns the OS file modification time of the file at *path*. + +**Parameters** + +* *path* : a system file path. + +**Keywords** + +File Modification Timestamp Path + +**Version History** + +* 3.1.2 : First Release +* 4.0.2 : Renamed from BE_File_Modification_Timestamp + +**Notes** + +It is up to the Operating system as to what time it returns, and some OS versions may be more precise ( down to the millisecond ) and so the result could be different in across OS versions, or change in future OS versions. + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_FileMove.md b/docs/Functions/BE_FileMove.md index e69de29bb..24449693f 100644 --- a/docs/Functions/BE_FileMove.md +++ b/docs/Functions/BE_FileMove.md @@ -0,0 +1,41 @@ +## BE_FileMove + + BE_FileMove ( fromFilePath ; toFilePath {; replaceDestinationFile } ) + +**Description** + +Moves the file specified in the *fromFilePath* parameter, to the location in the *toFilePath* parameter optionally replacing according to *replaceDestinationFile*. + +**Parameters** + +* *fromFilePath* : a plugin path to a file. +* *toFilePath* : a plugin path destination. +* *replaceDestinationFile* ( optional, default:False ) : boolean to replace the file or not. + +**Keywords** + +File Move Replace Path + +**Version History** + +* 1.1.0 : First Release +* 4.0.2 : Renamed from BE_MoveFile + +**Notes** + +On Mac OS X, the Move operation only works if the source and Destination are on the same volume. To move files across volumes, use a Copy and then Delete the original. + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_FileOpen.md b/docs/Functions/BE_FileOpen.md index e69de29bb..2f986326b 100644 --- a/docs/Functions/BE_FileOpen.md +++ b/docs/Functions/BE_FileOpen.md @@ -0,0 +1,42 @@ +## BE_FileOpen + + BE_FileOpen ( path ) + +**Description** + +Opens the file or folder at *path* using the default application chosen by the operating system. + +**Parameters** + +* *path* : the plugin path to the file. + +**Keywords** + +File Open Path + +**Version History** + +* 1.3.0 : First Release +* 4.0.0 : return error 3, command not available on iOS and Linux +* 4.0.2 : Renamed from BE_OpenFile + +**Notes** + +There are some quirks to the way this function works on Mac OS : it sends an open request to the file, which is either able to be sent or not, and the response/error only reflects whether or not the request was sent. So for example if the file doesn't exist, or if you don't have permissions to open it, you get an error. + +But whether the file actually opens or not is another thing, the OS will check things like apps for security and that can take some time. So whether or not the open is successful is different from whether or not the plugin tried to open the file. The two can be different, and the plugin only handles the sending of the open request, it doesn't poll to figure out if the open was successful or not. + +In technical terms, the two are asynchronous - meaning we get back the first "done and ok" response and would have to continuously query the OS to find out the final state. The plugin doesn't do that. You'd need to use some other function to work out if the open did what you were expecting. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | No | +| Linux | No | + +**Example Code** diff --git a/docs/Functions/BE_FilePatternCount.md b/docs/Functions/BE_FilePatternCount.md index e69de29bb..b63d459ba 100644 --- a/docs/Functions/BE_FilePatternCount.md +++ b/docs/Functions/BE_FilePatternCount.md @@ -0,0 +1,37 @@ +## BE_FilePatternCount + + BE_FilePatternCount ( path ; searchText ) + +**Description** + +Search inside files on disk. Much like the native *PatternCount* function, but within files on disk. + +**Parameters** + +* *path* : the plugin path to the file. +* *searchText* : the text to find in the text document - can be a value list, where it will count each of the values in turn. + +**Keywords** + +File Pattern Count Path + +**Version History** + +* 4.2.0 : First Release + +**Notes** + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_FileReadText.md b/docs/Functions/BE_FileReadText.md index e69de29bb..3a84d360e 100644 --- a/docs/Functions/BE_FileReadText.md +++ b/docs/Functions/BE_FileReadText.md @@ -0,0 +1,76 @@ +## BE_FileReadText + + BE_FileReadText ( pathOrContainer { ; start ; to ; eolChar } ) + +**Description** + +Reads the contents of the file at *pathOrContainer* as text and returns the content, optionall beginning at point *start*, ending at *to* and treating *eolChar* as line characters. + +**Parameters** + +* *pathOrContainer* : description. +* *start* ( optional ) : description. +* *to* ( optional ) : description. +* *eolChar* ( optional ) : description. + +Use *start*, *to* and *eolChar* to extract a portion of the file - the first character is at position 0 which is different from the native Position function. + +Pass *start* as empty or greater than *to* to read from the end of the file in reverse back to *to* - useful for getting the tail of log files for example. + +Pass an empty *eolChar* to use start and to as pure character counts. + +If you include a value for *eolChar* it will treat *eolChar* as a line break character, and will return lines of text instead of characters of the text. So *start* as the first line to start at, and *to* the last line. + +**Keywords** + +File Text Read Path + +**Version History** + +* 1.0.0 : First Release +* 4.0.0 : Allow reading text from a container file instead of a path +* 4.0.2 : Renamed from BE_ReadTextFromFile +* 4.2.0 : added start, to and eolChar parameters +* 5.0.0 : Fixed a bug in the way that the function works on container fields to match the external files behaviour +* 5.0.0 : Fixed a bug in the eolChar to allow multiple character eol values + +**Notes** + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +Note that *eolChar* doesn't have to be a normal end of line character such as a line feed or carriage return. You can use any character you want. This also means that text brought into FileMaker may not have multiple lines in the sense of what a FileMaker value list has. Or another way : the plugin doesn't modify the text to replace your *eolChar* with an end of line character. + +So you could use "," as the *eolChar* to get certain columns out of a csv file. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_FileReadText ( $path ) + +reads the entire file + + BE_FileReadText ( $path ; 1 ; 100 ) + +reads the first 100 characters + + BE_FileReadText ( $path ; 1 ; 10 ; char ( 10 ) ) + +reads the first 10 lines of the file + + BE_FileReadText ( $path ; 10 ; ; char ( 10 ) ) + +reads from line 10 to the end of the file + + BE_FileReadText ( $path ; ; 10 ; char ( 10 ) ) + +reads the last 10 lines of the file. \ No newline at end of file diff --git a/docs/Functions/BE_FileReplaceText.md b/docs/Functions/BE_FileReplaceText.md index e69de29bb..408f6812f 100644 --- a/docs/Functions/BE_FileReplaceText.md +++ b/docs/Functions/BE_FileReplaceText.md @@ -0,0 +1,50 @@ +## BE_FileReplaceText + + BE_FileReplaceText ( pathOrContainer ; expression ; replaceString { ; options } ) + +**Description** + +Much like the native Substitute function, but for a text file on disk or stored inside a container field. + +**Parameters** + +* *pathOrContainer* : either a full path to the file on disk, or a container field. +* *expression* : The text string to look for in the file. +* *replaceString* : The text string to replace it with in the file. +* *options* ( optional, defaut:gi ) : A string of characters from the options below , eg "igm". + +If the *pathOrContainer* is a container field which contains only text, then it will be read as a path, and that path will be used to locate the file. + +**Keywords** + +File Replace Text Path + +**Version History** + +* 4.2.0 : First Release + +**Notes** + +Options : +* i - case insensitive +* m - multiline +* s - dot matches all characters, including newline< +* x - ignore whitespace +* g - replace all + +For options: Default is "gi" which matches the native FileMaker substitute. These options work exactly the same as the RegularExpression function. + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_FileSaveDialog.md b/docs/Functions/BE_FileSaveDialog.md index e69de29bb..789f1b335 100644 --- a/docs/Functions/BE_FileSaveDialog.md +++ b/docs/Functions/BE_FileSaveDialog.md @@ -0,0 +1,42 @@ +## BE_FileSaveDialog + + BE_FileSaveDialog ( prompt ; { fileName ; inFolder } ) + +**Description** + +Displays the standard OS save file dialog. Changes the title of the dialog to the *prompt* specified, and defaults to *fileName* and sets the starting location as *inFolder*. + +Returns the file path and filename that the user selected. Check BE_GetLastError = -1 for when the user hits cancel or a value other than 0 for any other error. + +**Parameters** + +* *prompt* : The text to display in the dialog. +* *fileName* ( optional ) : The filename to start with. Leave empty to get the user to name the file. +* *inFolder* ( optional ) : The folder path to start in when opening the dialog. Defaults to the last used folder as determined by the operating system. + +**Keywords** + +Dialog File Save + +**Version History** + +* 2.3.0 : First Release +* 4.0.0 : Return error 3, command not available on iOS, Linux and under FMS +* 4.0.2 : Renamed from BE_SaveFileDialog + +**Notes** + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | No | +| iOS | No | +| Linux | No | + +**Example Code** diff --git a/docs/Functions/BE_FileSelectDialog.md b/docs/Functions/BE_FileSelectDialog.md index e69de29bb..6280918cd 100644 --- a/docs/Functions/BE_FileSelectDialog.md +++ b/docs/Functions/BE_FileSelectDialog.md @@ -0,0 +1,44 @@ +## BE_FileSelectDialog + + BE_FileSelectDialog ( prompt { ; inFolderPath } ) + +**Description** + +Displays the standard OS select file dialog with the title of the dialog to the *prompt* specified, and starting path of the *inFolderPath*. + +Result is the path to the file selected by the user. Check BE_GetLastError = -1 for when the user hits cancel or a value other than 0 for any other error. + +**Parameters** + +* *prompt* : The text to display in the dialog. +* *nainFolderPathme* ( optional ) : The folder to start in when opening the dialog. Defaults to the last used folder as determined by the operating system. + +**Keywords** + +File Select Dialog + +**Version History** + +* 1.0.0 : First Release +* 2.0.0 : Added the optional inFolderPath parameter. +* 2.2.0 : Added the ability to select multiple files. +* 2.2.0 : Update dialogs for new Windows OS versions +* 4.0.0 : Return error 3, command not available on iOS, Linux and under FMS +* 4.0.2 : Renamed from BE_SelectFile + +**Notes** + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | No | +| iOS | No | +| Linux | No | + +**Example Code** diff --git a/docs/Functions/BE_FileSize.md b/docs/Functions/BE_FileSize.md index e69de29bb..83e283ac6 100644 --- a/docs/Functions/BE_FileSize.md +++ b/docs/Functions/BE_FileSize.md @@ -0,0 +1,36 @@ +## BE_FileSize + + BE_FileSize ( path ) + +**Description** + +Returns the number of bytes in the file at *path*. + +**Parameters** + +* *path* : the plguin path to the file.. + +**Keywords** + +File Size Path + +**Version History** + +* 2.0.0 : First Release + +**Notes** + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_FileWriteText.md b/docs/Functions/BE_FileWriteText.md index e69de29bb..a67707887 100644 --- a/docs/Functions/BE_FileWriteText.md +++ b/docs/Functions/BE_FileWriteText.md @@ -0,0 +1,70 @@ +## BE_FileWriteText + + BE_FileWriteText ( pathOrContainer ; text ; { appendBoolean } ) + +**Description** + +Writes the contents specified in *text* to the file at the *pathOrContainer* or to a container field via Set Field. + +**Parameters** + +* *pathOrContainer* : either text which contains a path to a file, or binary data from a container field, or file set into a variable. +* *text* : the text to write to the file. +* *appendBoolean* ( optional, default:False ) : True will append to the file, False or no parameter will either write over an existing file or set the contents of a new file. + +Using the optional *appendBoolean* parameter you can choose to either write a new file ( or overwrite an existing one ), or to append the text to the end of the file. + +**Keywords** + +File Text Write Path Container + +**Version History** + +* 1.0.0 : First Release +* 1.1.0 : Adds appendBoolean option +* 3.3.0 : Recursively create any directories needed +* 4.0.2 : Renamed from BE_WriteTextToFile +* 4.0.2 : Allows writing to container fields as well as paths + +**Notes** + +Defaults to UTF-8 ( no BOM ) which can be changed using the BE_SetTextEncoding function. + +For writing files to containers, this function works a little differently. First you need to use this as a Set Field step, and the resulting output will then be set into the field that is the destination of the Set Field step. + +If you're appending to a file, and setting it into a field, the first parameter pathOrContainer can be either a field with an existing file, or a path to an existing file. The result will then be appended to the original. Set the appendBoolean parameter to True. + +If you're setting a field and not appending, the first parameter should contain just the name of the file you want as text. + +Obviously this first parameter can be many things, a path, a container field containing a file, or a text string ( from a field, or variable etc ) containing a file name. + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_FileWriteText ( $path ; "sometexthere" ) + +creates a new file at $path with the content "sometexthere" + + BE_FileWriteText ( $path ; "sometexthere" ; True ) + +appends to an existing file at $path and adds "sometexthere" to the end of the document + + SetField [ table::myField ; BE_FileWriteText ( $path ; "sometexthere" ; True ) + +sets myField with a file, that is the content of the existing file at $path with "sometexthere" appended. Filename will be as per the existing file at $path. + + SetField [ table::myField ; BE_FileWriteText ( "myfile.txt" ; "sometexthere" ) + +Creates a new file called "myfile.txt" and sets the content to "sometexthere" and puts it into the myField field. \ No newline at end of file diff --git a/docs/Functions/BE_FolderCreate.md b/docs/Functions/BE_FolderCreate.md index e69de29bb..409971c0e 100644 --- a/docs/Functions/BE_FolderCreate.md +++ b/docs/Functions/BE_FolderCreate.md @@ -0,0 +1,40 @@ +## BE_FolderCreate + + BE_FolderCreate ( path ) + +**Description** + +Creates a new folder at the location *path*, creating sub folders along the way as required. + +**Parameters** + +* *path* : A plugin file path ( not a FileMaker path ).. + +**Keywords** + +Path Create + +**Version History** + +* 1.0.0 : First Release +* 2.1.0 : changed the folder to be recursive, so any required subfolders are also created +* 4.0.2 : Renamed from BE_CreateFolder + +**Notes** + +PLUGIN PATHS ARE NOT FILEMAKER PATHS. The plugin uses the same path structure as your operating system, and you cannot pass to the plugin paths that start with file:/ or filewin:/ etc. Read the FAQ for more info about paths. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_FolderCreate ( "/Users/username/Desktop/myNewFolder" ) diff --git a/docs/Functions/BE_FolderSelectDialog.md b/docs/Functions/BE_FolderSelectDialog.md index e69de29bb..17847238b 100644 --- a/docs/Functions/BE_FolderSelectDialog.md +++ b/docs/Functions/BE_FolderSelectDialog.md @@ -0,0 +1,44 @@ +## BE_FolderSelectDialog + + BE_FolderSelectDialog ( prompt { ; inFolderPath } ) + +**Description** + +Displays the standard OS select folder dialog with the title of the dialog to the *prompt* specified, and starting path of the *inFolderPath*. + +Result is the path to the folder selected by the user. Check BE_GetLastError = -1 for when the user hits cancel or a value other than 0 for any other error. + +**Parameters** + +* *prompt* : The text to display in the dialog. +* *nainFolderPathme* ( optional ) : The folder to start in when opening the dialog. Defaults to the last used folder as determined by the operating system. + +**Keywords** + +File Select Dialog + +**Version History** + +* 1.0.0 : First Release +* 1.3.0 : Added the optional inFolderPath parameter. +* 2.0.0 : Add New Folder button. +* 2.2.0 : Update dialogs for new Windows OS versions +* 4.0.0 : Return error 3, command not available on iOS, Linux and under FMS +* 4.0.2 : Renamed from BE_SelectFolder + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | No | +| iOS | No | +| Linux | No | + +**Example Code** diff --git a/docs/Functions/BE_GetLastDDLError.md b/docs/Functions/BE_GetLastDDLError.md index e69de29bb..26513dd87 100644 --- a/docs/Functions/BE_GetLastDDLError.md +++ b/docs/Functions/BE_GetLastDDLError.md @@ -0,0 +1,36 @@ +## BE_GetLastDDLError + + BE_GetLastDDLError + +**Description** + +Returns the last DDL error generated by the plugin during the SQL function call. + +**Parameters** + +NA + +**Keywords** + +Error DDL + +**Version History** + +* 2.0.0 : First Release + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_GetLastError.md b/docs/Functions/BE_GetLastError.md index e69de29bb..21bc46751 100644 --- a/docs/Functions/BE_GetLastError.md +++ b/docs/Functions/BE_GetLastError.md @@ -0,0 +1,53 @@ +## BE_GetLastError + + BE_GetLastError + +**Description** + +Returns the last error generated by the most recent plugin function call. This value is overridden on every function call, except for calls to BE_GetLastError, BE_GetLastDDLError, and BE_DebugInformation. + +This function does not set many of the error results themselves, so there is no definitive list of possible values, and new codes are introduced with each updated library. Use the links below to lookup error codes for various values. + +The plugin does return 0 on successful function calls and 1 to match the "User canceled action" for dialog cancel buttons, and 3 for function calls where the operating system is known to be incompatible. + +**Parameters** + +NA + +**Keywords** + +Error Last Get + +**Version History** + +* 1.2.0 : First Release +* 2.0.0 : Changed the way this works so that successive calls to the BE_GetLastError function don't reset the value that is returned, it's only reset when performing any other function call. + +**Notes** + +Most of the error codes are returned by libraries we use or the OS itself, not by the plugin, so there are very few "plugin" error codes. Most error codes are either cURL related, file system related, or OS related. + +In the case of the *HTTP*, *FTP*, *SMTP* etc functions we're using the cURL libraries. There is a list of error codes here : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +When doing Windows file operations, common errors are : + +[https://docs.microsoft.com/en-us/windows/win32/debug/system-error-codes--0-499-](https://docs.microsoft.com/en-us/windows/win32/debug/system-error-codes--0-499-) + +For Mac OS, there is a somewhat useful list here : + +[https://krypted.com/lists/comprehensive-list-of-mac-os-x-error-codes/](https://krypted.com/lists/comprehensive-list-of-mac-os-x-error-codes/) + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_GetMachineName.md b/docs/Functions/BE_GetMachineName.md index e69de29bb..283d6b4d2 100644 --- a/docs/Functions/BE_GetMachineName.md +++ b/docs/Functions/BE_GetMachineName.md @@ -0,0 +1,36 @@ +## BE_GetMachineName + + BE_GetMachineName + +**Description** + +This function just returns the result of the %COMPUTERNAME% variable on Windows, or gets the computer hardware identifier if the operating system supports it. + +**Parameters** + +None + +**Keywords** + +MachineName Get + +**Version History** + +* 4.0.0 : First Release + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_GetSystemDrive.md b/docs/Functions/BE_GetSystemDrive.md index e69de29bb..ad7a1e738 100644 --- a/docs/Functions/BE_GetSystemDrive.md +++ b/docs/Functions/BE_GetSystemDrive.md @@ -0,0 +1,36 @@ +BE_GetSystemDrive + + BE_GetSystemDrive + +**Description** + +The same effect as the internal FileMaker function Get ( SystemDrive ) but because it's plugin based will also function on FileMaker Server where the internal function does not work. + +**Parameters** + +None + +**Keywords** + +SystemDrive Get + +**Version History** + +* 4.1.0 : First Release + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_Gzip.md b/docs/Functions/BE_Gzip.md index e69de29bb..b216bf9a9 100644 --- a/docs/Functions/BE_Gzip.md +++ b/docs/Functions/BE_Gzip.md @@ -0,0 +1,37 @@ +## BE_Gzip + + BE_Gzip ( data ; { filename } ) + +**Description** + +Compresses the file/text found in *data* and optionally applies the filename, otherwise uses the container data appended with the .gzip extension. + +**Parameters** + +* *data* : a container field with an unzipped file in it, or text data. +* *filename* : optional filename to use, appending the .gzip extension. + +**Keywords** + +Gzip zip + +**Version History** + +* 3.3.0 : First Release + +**Notes** + +This function should be used with a *Set Field* script step and the results stored as a container field. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_HMAC_Deprecated.md b/docs/Functions/BE_HMAC_Deprecated.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/Functions/BE_HTTP_DELETE.md b/docs/Functions/BE_HTTP_DELETE.md index e69de29bb..5273faae3 100644 --- a/docs/Functions/BE_HTTP_DELETE.md +++ b/docs/Functions/BE_HTTP_DELETE.md @@ -0,0 +1,48 @@ +## BE_HTTP_DELETE + + BE_HTTP_DELETE ( url ; { username ; password } ) + +**Description** + +Does a HTTP DELETE call at the *url* and returns the response if any. This uses the same curl library as the built in *Insert From URL* using "-X DELETE" in the curl options. + +**Parameters** + +* *url* : The url to use for the DELETE action. +* *username* ( optional ) : The username if the url requires authentication. +* *password* ( optional ) : The password if the url requires authentication. + +**Keywords** + +HTTP Delete Curl + +**Version History** + +* 2.0.0 : First Release + +**Notes** + +Headers can be set beforehand with *BE_HTTP_SetCustomHeader*. Authentication types and other options can be set beforehand with the *BE_CurlSetOption* function. + +Not all servers respond with data when doing curl operations so use *BE_GetLastError* after the function call to tell if the call was able to be made, and then *BE_HTTP_ResponseCode* to check for the appropriate response code, and *BE_HTTP_ResponseHeaders* to get the response headers to diagnose any issues. + +Error codes that you get from the *BE_GetLastError* function after this function call comes from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +Also use the *BE_CurlTrace* function to see the transcript of the connection to diagnose any other issues that may have come up and can't be determined from the error value alone. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +This function has been superseded by the Insert From URL script step, and may be deprecated in a future release. However the BE functions allow for a larger number of curl options, have a better response mechanism with the separate BE_HTTP_ResponseCode function, and have the advantage of not being a single script step. Whether or not to deprecate the BE functions depends on end user needs. + +**Example Code** diff --git a/docs/Functions/BE_HTTP_GET.md b/docs/Functions/BE_HTTP_GET.md index e69de29bb..b0494146b 100644 --- a/docs/Functions/BE_HTTP_GET.md +++ b/docs/Functions/BE_HTTP_GET.md @@ -0,0 +1,50 @@ +## BE_HTTP_GET + + BE_HTTP_GET ( url ; { filename ; username ; password } ) + +**Description** + +Does a http, https, ftp, ftps, or sftp GET / download and returns the results. This uses the same curl library as the built in *Insert From URL*. + +**Parameters** + +* *url* : The url to retrieve. +* *username* ( optional ) : The username if the url requires authentication. +* *username* ( optional ) : The username if the url requires authentication. +* *password* ( optional ) : The password if the url requires authentication. + +**Keywords** + +HTTP GET Curl FTP + +**Version History** + +* 1.2.0 : First Release +* 3.3.0 : Renamed to BE_HTTP_GET from BE_GetURL + +**Notes** + +Headers can be set beforehand with *BE_HTTP_SetCustomHeader*. Authentication types and other options can be set beforehand with the *BE_CurlSetOption* function. + +Not all servers respond with data when doing curl operations so use *BE_GetLastError* after the function call to tell if the call was able to be made, and then *BE_HTTP_ResponseCode* to check for the appropriate response code, and *BE_HTTP_ResponseHeaders* to get the response headers to diagnose any issues. + +Error codes that you get from the *BE_GetLastError* function after this function call comes from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +Also use the *BE_CurlTrace* function to see the transcript of the connection to diagnose any other issues that may have come up and can't be determined from the error value alone. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +This function has been superseded by the Insert From URL script step, and may be deprecated in a future release. However the BE functions allow for a larger number of curl options, have a better response mechanism with the separate BE_HTTP_ResponseCode function, and have the advantage of not being a single script step. Whether or not to deprecate the BE functions depends on end user needs. + +**Example Code** diff --git a/docs/Functions/BE_HTTP_GET_File.md b/docs/Functions/BE_HTTP_GET_File.md index e69de29bb..b0a6f4d22 100644 --- a/docs/Functions/BE_HTTP_GET_File.md +++ b/docs/Functions/BE_HTTP_GET_File.md @@ -0,0 +1,50 @@ +## BE_HTTP_GET + + BE_HTTP_GET ( url ; { path ; username ; password } ) + +**Description** + +Does a http, https, ftp, ftps, or sftp GET / download and saves the result to *path*. This uses the same curl library as the built in *Insert From URL*. + +**Parameters** + +* *url* : The url to retrieve. +* *path* ( optional ) : The path to save the file to. +* *username* ( optional ) : The username if the url requires authentication. +* *password* ( optional ) : The password if the url requires authentication. + +**Keywords** + +HTTP GET Curl FTP + +**Version History** + +* 1.2.0 : First Release +* 3.3.0 : Renamed to BE_HTTP_GET_File from BE_SaveURLToFile + +**Notes** + +Headers can be set beforehand with *BE_HTTP_SetCustomHeader*. Authentication types and other options can be set beforehand with the *BE_CurlSetOption* function. + +Not all servers respond with data when doing curl operations so use *BE_GetLastError* after the function call to tell if the call was able to be made, and then *BE_HTTP_ResponseCode* to check for the appropriate response code, and *BE_HTTP_ResponseHeaders* to get the response headers to diagnose any issues. + +Error codes that you get from the *BE_GetLastError* function after this function call comes from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +Also use the *BE_CurlTrace* function to see the transcript of the connection to diagnose any other issues that may have come up and can't be determined from the error value alone. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +This function has been superseded by the Insert From URL script step, and may be deprecated in a future release. However the BE functions allow for a larger number of curl options, have a better response mechanism with the separate BE_HTTP_ResponseCode function, and have the advantage of not being a single script step. Whether or not to deprecate the BE functions depends on end user needs. + +**Example Code** diff --git a/docs/Functions/BE_HTTP_PATCH.md b/docs/Functions/BE_HTTP_PATCH.md index e69de29bb..6978b9b6f 100644 --- a/docs/Functions/BE_HTTP_PATCH.md +++ b/docs/Functions/BE_HTTP_PATCH.md @@ -0,0 +1,63 @@ +## BE_HTTP_PATCH + + BE_HTTP_PATCH ( url ; parameters ; { username ; password } ) + +**Description** + +Does a HTTP PATCH call at the *url* and returns the response if any. This uses the same curl library as the built in *Insert From URL* using "-X PATCH" in the curl options. + +**Parameters** + +* *url* : The url to use for the PATCH action. +* *parameters* : The data to send to the url. +* *username* ( optional ) : The username if the url requires authentication. +* *password* ( optional ) : The password if the url requires authentication. + +**Keywords** + +HTTP Patch Curl + +**Version History** + +* 3.3.0 : First Release + +**Notes** + +Headers can be set beforehand with *BE_HTTP_SetCustomHeader*. Authentication types and other options can be set beforehand with the *BE_CurlSetOption* function. + +Not all servers respond with data when doing curl operations so use *BE_GetLastError* after the function call to tell if the call was able to be made, and then *BE_HTTP_ResponseCode* to check for the appropriate response code, and *BE_HTTP_ResponseHeaders* to get the response headers to diagnose any issues. + +Error codes that you get from the *BE_GetLastError* function after this function call comes from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +Also use the *BE_CurlTrace* function to see the transcript of the connection to diagnose any other issues that may have come up and can't be determined from the error value alone. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +This function has been superseded by the Insert From URL script step, and may be deprecated in a future release. However the BE functions allow for a larger number of curl options, have a better response mechanism with the separate BE_HTTP_ResponseCode function, and have the advantage of not being a single script step. Whether or not to deprecate the BE functions depends on end user needs. + +**Example Code** + +When doing basic url parameter values, *parameters* is a text string, which is a list of all of the parameters to send in name value pair format. Put an "=" between the name and value, and an ampersand "&" between each pair. URLEncode the names and values. + +Otherwise the type of data being sent is usually determined via a Content_Type header you set via *BE_HTTP_SetCustomHeader*. For example, JSON data : + + BE_HTTP_PATCH ( "http://Fictional.Server.com/service.js" ; + JSONSetElement ( "{}" ; "method" ; "Workgroup.projects.listActive" ; JSONString ) ; + "Administrator" ; "password123" ) + +To send a file from disk, use file=@path for external files. The path is a plugin path, not a FileMaker path. + + BE_HTTP_PATCH( $url ; "image=@/Users/nick/Desktop/test.jpg" ) + +The server must support the sending of files. \ No newline at end of file diff --git a/docs/Functions/BE_HTTP_POST.md b/docs/Functions/BE_HTTP_POST.md index e69de29bb..7d5c784f5 100644 --- a/docs/Functions/BE_HTTP_POST.md +++ b/docs/Functions/BE_HTTP_POST.md @@ -0,0 +1,73 @@ +## BE_HTTP_POST + + BE_HTTP_POST ( url ; parameters ; { username ; password ; fileName } ) + +**Description** + +Does a HTTP POST call at the *url* and returns the response if any. This uses the same curl library as the built in *Insert From URL* using "-X POST" in the curl options. + +**Parameters** + +* *url* : The url to use for the POST action. +* *parameters* : The data to send to the url. +* *username* ( optional ) : The username if the url requires authentication. +* *password* ( optional ) : The password if the url requires authentication. +* *fileName* ( optional ) : The filename to send when sending binary data. + +**Keywords** + +HTTP POST Curl + +**Version History** + +* 1.3.0 : First Release +* 2.0.0 : Added optional username and password parameters +* 3.1.0 : Allowed the use of file=@path for file parameters +* 4.0.0 : Added the optional filename parameter + +**Notes** + +Headers can be set beforehand with *BE_HTTP_SetCustomHeader*. Authentication types and other options can be set beforehand with the *BE_CurlSetOption* function. + +Not all servers respond with data when doing curl operations so use *BE_GetLastError* after the function call to tell if the call was able to be made, and then *BE_HTTP_ResponseCode* to check for the appropriate response code, and *BE_HTTP_ResponseHeaders* to get the response headers to diagnose any issues. + +Error codes that you get from the *BE_GetLastError* function after this function call comes from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +Also use the *BE_CurlTrace* function to see the transcript of the connection to diagnose any other issues that may have come up and can't be determined from the error value alone. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +This function has been superseded by the Insert From URL script step, and may be deprecated in a future release. However the BE functions allow for a larger number of curl options, have a better response mechanism with the separate BE_HTTP_ResponseCode function, and have the advantage of not being a single script step. Whether or not to deprecate the BE functions depends on end user needs. + +**Example Code** + +When doing basic url parameter values, *parameters* is a text string, which is a list of all of the parameters to send in name value pair format. Put an "=" between the name and value, and an ampersand "&" between each pair. URLEncode the names and values. + +Otherwise the type of data being sent is usually determined via a Content_Type header you set via *BE_HTTP_SetCustomHeader*. For example, JSON data : + + BE_HTTP_POST ( "http://Fictional.Server.com/service.js" ; + JSONSetElement ( "{}" ; "method" ; "Workgroup.projects.listActive" ; JSONString ) ; + "Administrator" ; "password123" ) + +To send a file from disk, use file=@path for external files. The path is a plugin path, not a FileMaker path. + + BE_HTTP_POST ( $url ; "image=@/Users/nick/Desktop/test.jpg" ) + +The server must support the sending of files. + +You can also do multipart/form data : + + BE_HTTP_SetCustomHeader ( "Content-type"; "multipart/mixed" ) + + BE_HTTP_POST ( $url ; "a=b&c=d&image=@" & BE_ExportFieldContents ( Table::File ) ; "Administrator" ; "password123" ; GetContainerAttribute ( Table::File ; "filename" ) ) \ No newline at end of file diff --git a/docs/Functions/BE_HTTP_PUTData.md b/docs/Functions/BE_HTTP_PUTData.md index e69de29bb..7d6b2609d 100644 --- a/docs/Functions/BE_HTTP_PUTData.md +++ b/docs/Functions/BE_HTTP_PUTData.md @@ -0,0 +1,64 @@ +## BE_HTTP_PUTData + + BE_HTTP_PUTData ( url ; data ; { username ; password } ) + +**Description** + +Does a HTTP PATCH PUT at the *url* and returns the response if any. This uses the same curl library as the built in *Insert From URL* using "-X PUT" in the curl options. + +**Parameters** + +* *url* : The url to use for the PUT action. +* *data* : The data to send to the url. +* *username* ( optional ) : The username if the url requires authentication. +* *password* ( optional ) : The password if the url requires authentication. + +**Keywords** + +HTTP PUT Curl + +**Version History** + +* 2.1.0 : First Release +* 4.0.2 : Renamed from BE_HTTP_PUT_DATA + +**Notes** + +Headers can be set beforehand with *BE_HTTP_SetCustomHeader*. Authentication types and other options can be set beforehand with the *BE_CurlSetOption* function. + +Not all servers respond with data when doing curl operations so use *BE_GetLastError* after the function call to tell if the call was able to be made, and then *BE_HTTP_ResponseCode* to check for the appropriate response code, and *BE_HTTP_ResponseHeaders* to get the response headers to diagnose any issues. + +Error codes that you get from the *BE_GetLastError* function after this function call comes from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +Also use the *BE_CurlTrace* function to see the transcript of the connection to diagnose any other issues that may have come up and can't be determined from the error value alone. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +This function has been superseded by the Insert From URL script step, and may be deprecated in a future release. However the BE functions allow for a larger number of curl options, have a better response mechanism with the separate BE_HTTP_ResponseCode function, and have the advantage of not being a single script step. Whether or not to deprecate the BE functions depends on end user needs. + +**Example Code** + +When doing basic url parameter values, *parameters* is a text string, which is a list of all of the parameters to send in name value pair format. Put an "=" between the name and value, and an ampersand "&" between each pair. URLEncode the names and values. + +Otherwise the type of data being sent is usually determined via a Content_Type header you set via *BE_HTTP_SetCustomHeader*. For example, JSON data : + + BE_HTTP_PUTData ( "http://Fictional.Server.com/service.js" ; + JSONSetElement ( "{}" ; "method" ; "Workgroup.projects.listActive" ; JSONString ) ; + "Administrator" ; "password123" ) + +To send a file from disk, use file=@path for external files. The path is a plugin path, not a FileMaker path. + + BE_HTTP_PUTData ( $url ; "image=@/Users/nick/Desktop/test.jpg" ) + +The server must support the sending of files. \ No newline at end of file diff --git a/docs/Functions/BE_HTTP_PUTFile.md b/docs/Functions/BE_HTTP_PUTFile.md index e69de29bb..dbd1fb40b 100644 --- a/docs/Functions/BE_HTTP_PUTFile.md +++ b/docs/Functions/BE_HTTP_PUTFile.md @@ -0,0 +1,57 @@ +## BE_HTTP_PUTData + + BE_HTTP_PUTData ( url ; path ; { username ; password } ) + +**Description** + +Does a HTTP PATCH PUT at the *url* and returns the response if any. This uses the same curl library as the built in *Insert From URL* using "-X PUT" in the curl options. + +**Parameters** + +* *url* : The url to use for the PUT action. +* *path* : The path to read the file to send to the url. +* *username* ( optional ) : The username if the url requires authentication. +* *password* ( optional ) : The password if the url requires authentication. + +**Keywords** + +HTTP PUT File Curl + +**Version History** + +* 2.0.0 : First Release +* 2.1.0 : Changed the name to BE_HTTP_PUT_DATA to reflect the actual use of the function parameters +* 4.0.2 : Renamed from BE_HTTP_PUTData + +**Notes** + +Headers can be set beforehand with *BE_HTTP_SetCustomHeader*. Authentication types and other options can be set beforehand with the *BE_CurlSetOption* function. + +Not all servers respond with data when doing curl operations so use *BE_GetLastError* after the function call to tell if the call was able to be made, and then *BE_HTTP_ResponseCode* to check for the appropriate response code, and *BE_HTTP_ResponseHeaders* to get the response headers to diagnose any issues. + +Error codes that you get from the *BE_GetLastError* function after this function call comes from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +Also use the *BE_CurlTrace* function to see the transcript of the connection to diagnose any other issues that may have come up and can't be determined from the error value alone. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +This function has been superseded by the Insert From URL script step, and may be deprecated in a future release. However the BE functions allow for a larger number of curl options, have a better response mechanism with the separate BE_HTTP_ResponseCode function, and have the advantage of not being a single script step. Whether or not to deprecate the BE functions depends on end user needs. + +**Example Code** + +The type of data being sent is usually determined via a Content_Type header you set via *BE_HTTP_SetCustomHeader*. Each file type will have it's own Content-Type and the web service will determine acceptable types. + + BE_HTTP_PUTData ( "http://Fictional.Server.com/service.js" ; + "/path/to/file.txt" ; + "Administrator" ; "password123" ) diff --git a/docs/Functions/BE_HTTP_ResponseCode.md b/docs/Functions/BE_HTTP_ResponseCode.md index e69de29bb..a2e227f34 100644 --- a/docs/Functions/BE_HTTP_ResponseCode.md +++ b/docs/Functions/BE_HTTP_ResponseCode.md @@ -0,0 +1,37 @@ +## BE_HTTP_ResponseCode + + BE_HTTP_ResponseCode + +**Description** + +Returns the value of the Response code from the previous call made via any of the BE curl functions. Eg 403 for not found. + +**Parameters** + +None + +**Keywords** + +HTTP Response Code Curl + +**Version History** + +* 1.3.0 : First Release +* 4.0.2 : Renamed from BE_HTTP_Response_Code + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_HTTP_ResponseHeaders.md b/docs/Functions/BE_HTTP_ResponseHeaders.md index e69de29bb..862b4a631 100644 --- a/docs/Functions/BE_HTTP_ResponseHeaders.md +++ b/docs/Functions/BE_HTTP_ResponseHeaders.md @@ -0,0 +1,38 @@ +## BE_HTTP_ResponseHeaders + + BE_HTTP_ResponseHeaders ( { header } ) + +**Description** + +Returns the headers set by the server as part of a response to the previous HTTP request made via any of the BE curl functions. + +**Parameters** + +* *header* ( optional ) : The header name to retrieve or all headers if blank or omitted. + +**Keywords** + +HTTP Response Headers Curl + +**Version History** + +* 1.3.0 : First Release +* 3.3.2 : Added the *header* parameter so that the named header only is returned +* 4.0.2 : Renamed BE_HTTP_Response_Code to BE_HTTP_ResponseCode + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_HTTP_SetCustomHeader.md b/docs/Functions/BE_HTTP_SetCustomHeader.md index e69de29bb..0310b1828 100644 --- a/docs/Functions/BE_HTTP_SetCustomHeader.md +++ b/docs/Functions/BE_HTTP_SetCustomHeader.md @@ -0,0 +1,50 @@ +## BE_HTTP_SetCustomHeader + + BE_HTTP_SetCustomHeader ( { header ; value } ) + +**Description** + +Used for setting a header value before a HTTP, FTP, or SMTP function call. You can call this function multiple times before the POST to set more than one header, and call it with empty parameters to clear them out. + +**Parameters** + +* *header* ( optional ) : the name of the header to set. +* *value* ( optional ) : the value to set it to. + +**Keywords** + +HTTP Header Set Custom Curl + +**Version History** + +* 1.3.0 : First Release +* 4.0.1 : Added option to call with no parameters to delete all Headers +* 4.0.2 : Renamed from BE_HTTP_Set_Custom_Header +* 4.1.3 : **Breaking Change** : Change the way empty string headers vs missing value parameters are used - see notes. + +**Notes** + +In versions from 4.1.3 or later, setting a header with + + BE_HTTP_SetCustomHeader ( "name" ; "" ) + +now sets the header to an empty header value, instead of removing that header. Some header options have a default value and there is an accepted header with the name, but an empty string as the value. To remove the header completely and revert to default call + + BE_HTTP_SetCustomHeader ( "name" ) + +with no value parameter, which is also the same behaviour as the previous versions. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_HTTP_SetCustomHeader ( "Content-Type" ; "text/xml;charset=utf-8" ) diff --git a/docs/Functions/BE_HTTP_Set_Proxy.md b/docs/Functions/BE_HTTP_Set_Proxy.md index e69de29bb..285f89149 100644 --- a/docs/Functions/BE_HTTP_Set_Proxy.md +++ b/docs/Functions/BE_HTTP_Set_Proxy.md @@ -0,0 +1,48 @@ +## BE_HTTP_SetProxy + + BE_HTTP_SetProxy ( proxy { ; port ; userName ; password } ) + +**Description** + +Used for setting the HTTP proxy values values before other curl based function calls. + +**Parameters** + +* *proxy* : The proxy url. +* *port* ( optional, default:80 ) : port number to use. +* *userName* ( optional ) : username for basic HTTP authentication. +* *password* ( optional ) : password for basic HTTP authentication. + +**Keywords** + +keyword keyword + +**Version History** + +* 2.0.0 : First Release +* 4.0.2 : Renamed from BE_HTTP_Set_Proxy + +**Notes** + +There is no standard way to retrieve the built in OS proxy settings, if they've been applied, so this can only be set manually via this function. + +Proxies are used in the HTTP, FTP, and SMTP functions despite the HTTP in the name of this function. + +Error codes that you get from the *BE_GetLastError* function after this function call comes from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +Also use the *BE_CurlTrace* function to see the transcript of the connection to diagnose any other issues that may have come up and can't be determined from the error value alone. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_JSONPath_Deprecated.md b/docs/Functions/BE_JSONPath_Deprecated.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/Functions/BE_JSON_ArraySize.md b/docs/Functions/BE_JSON_ArraySize.md index e69de29bb..24a5991b4 100644 --- a/docs/Functions/BE_JSON_ArraySize.md +++ b/docs/Functions/BE_JSON_ArraySize.md @@ -0,0 +1,40 @@ +## BE_JSON_ArraySize + + BE_JSON_ArraySize ( json { ; path } ) + +**Description** + +Will return the number of values in a JSON array. + +**Parameters** + +* *json* : the array to count. +* *name* ( optional ) : the path within the JSON to locate the array to count. + +**Keywords** + +JSON Array Size + +**Version History** + +* 2.1.0 : First Release +* 4.1.0 : Added the optional path parameter + +**Notes** + +If *path* is not included, it counts the array at the root of the JSON, and will return 1 for a non array type. + +If *path* is included, the format is as per the *BE_JSONPath* function, which is NOT the same as the internal FileMaker JSON functions introduced in version 16. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_JSON_Encode_Deprecated.md b/docs/Functions/BE_JSON_Encode_Deprecated.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/Functions/BE_JSON_Error_Description_Deprecated.md b/docs/Functions/BE_JSON_Error_Description_Deprecated.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/Functions/BE_MessageDigest.md b/docs/Functions/BE_MessageDigest.md index e69de29bb..60ff9d5ac 100644 --- a/docs/Functions/BE_MessageDigest.md +++ b/docs/Functions/BE_MessageDigest.md @@ -0,0 +1,44 @@ +## BE_MessageDigest + + BE_MessageDigest ( text ; { algorithm ; encoding } ) + +**Description** + +Returns a hash value generated by the MD5 or SHA functions from the text given, and optional encoding. + +**Parameters** + +* *text* : description. +* *algorithm* ( optional, default:BE_MessageDigestAlgorithmSHA256 ) : The type of hashing function to use. +* *encoding* ( optional, default:none ) : Possible values are BE_EncodingHex, BE_EncodingBase64, or no encoding for a binary result. + +**Keywords** + +Message Digest + +**Version History** + +* 1.2.0 : First Release +* 3.0.0 : Added the optional encoding parameter + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_MessageDigest ( $text ) + BE_MessageDigest ( $text ; BE_MessageDigestTypeMD5 ) + BE_MessageDigest ( $text ; BE_MessageDigestTypeSHA256 ; BE_EncodingBase64 ) + BE_MessageDigest ( $text ; 2 ; 1 ) // BE_MessageDigestAlgorithm_SHA256 and BE_EncodingHex diff --git a/docs/Functions/BE_OpenURL.md b/docs/Functions/BE_OpenURL.md index e69de29bb..879d8ad93 100644 --- a/docs/Functions/BE_OpenURL.md +++ b/docs/Functions/BE_OpenURL.md @@ -0,0 +1,37 @@ +## BE_OpenURL + + BE_OpenURL ( url ) + +**Description** + +Sends the url to the users default web browser. + +**Parameters** + +* *url* : the url to open. + +**Keywords** + +URL + +**Version History** + +* 1.1.0 : URL Open +* 4.0.0 : return error 3, command not available on Linux + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | No | +| iOS | Yes | +| Linux | No | + +**Example Code** diff --git a/docs/Functions/BE_PDFAppend.md b/docs/Functions/BE_PDFAppend.md index e69de29bb..bc4dd66d9 100644 --- a/docs/Functions/BE_PDFAppend.md +++ b/docs/Functions/BE_PDFAppend.md @@ -0,0 +1,65 @@ +## BE_PDFAppend + + BE_PDFAppend ( pdfPathOrContainer ; appendPathOrContainer ; { destinationPath } ) + +**Description** + +Joins two pdf files together, either by appending one to the first, or by creating a third PDF that is the end result. + +**Parameters** + +* *pdfPathOrContainer* : The first PDF file to be appended TO. Can be a container field or a path to a file. +* *appendPathOrContainer* : The second file, to be added to the first file. Can be a container field or a path to a file. +* *destinationPath* ( optional, default:container ) : the path to the result file. If left out, then use this in a Set Field step that points to a container field. + +**Keywords** + +PDF Path Append + +**Version History** + +* 4.0.0 : First Release +* 4.0.0 : Renamed from BE_PDF_Append + +**Notes** + +Some PDFs although they render properly in a PDF Viewer are incompatible with the PDF standard or at least with the version of the standard that our library supports. When this is the case you can get an error when trying to append the PDF. + +To diagnose this before appending if you do *BE_PDFPageCount ( table::field )* on the PDF and you get 0 back from the plugin, then our library doesn't think there's any content, so it can't be appended. + +You should be adding this check in to your script prior to using *BE_PDFAppend*, to confirm that both files contain data that can be read. + +In terms of fixing the PDF, there's no way to do that inside the plugin at the moment. + +You may be able to do this via an external library such Ghostscript. This option requires Ghostscript to be installed on your server or client, and then you run the command using *BE_ExecuteSystemCommand*. + +There are other APIs that offer to do PDF repair such as : + +[https://www.convertapi.com/pdf-to-repair#snippet=curl](https://www.convertapi.com/pdf-to-repair#snippet=curl) + +Which can be called with the BE HTTP functions, or the native *Insert From URL* script step. However the extent to which they can repair a broken PDF vs a non standard PDF is not known. There may also be other similar services online, or local applications as alternatives. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | No | +| Linux | Yes | + +**Example Code** + +Set a container field using two other fields. + + Set Field [ table::containerField ; BE_PDFAppend ( table::pdfField1 ; table::pdfField2 ) ] + +Set a container field using two paths. + + Set Field [ table::containerField ; BE_PDFAppend ( "/pluginPath/to/file1.pdf" ; "/pluginPath/to/file2.pdf" ) ] + +Create an external PDF file by combining a container field and a different external file. + + Set Variable [ $result ; BE_PDFAppend ( table::pdfField1 ; "/pluginPath/to/file2.pdf" "/pluginPath/to/outputFile.pdf" ) ] diff --git a/docs/Functions/BE_PDFGetPages.md b/docs/Functions/BE_PDFGetPages.md index e69de29bb..3c7f6b045 100644 --- a/docs/Functions/BE_PDFGetPages.md +++ b/docs/Functions/BE_PDFGetPages.md @@ -0,0 +1,41 @@ +## BE_PDFGetPages + + BE_PDFGetPages ( pdfPathOrContainer ; newPDFPath ; fromPageNum ; { toPageNum } ) + +**Description** + +Copies a number of pages from the PDF at *pdfPathOrContainer* and creates a new document written to disk at *newPDFPath*, using only pages starting with page number *fromPageNum* and ending with page number *toPageNum* or the end of the document. + +**Parameters** + +* *pdfPathOrContainer* : The original file to GET the pages from, either a container field or a path. +* *newPDFPath* : The path to write the result file to. +* *fromPageNum* : The starting page number to begin from. +* *toPageNum* ( optional ) : The page number to end on, or if left out will go to the end of the document. + +**Keywords** + +PDF Page Get Path + +**Version History** + +* 4.0.0 : First Release +* 4.0.2 : Renamed from BE_PDF_GetPages +* 4.2.0 : Added a "garbage collection" option so that the resulting file size is reduced as well + +**Notes** + +If the plugin can't read the file, but it is a PDF then you may get an invalid result from this function. See the notes at *BE_PDFAppend* for more information. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | No | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_PDFPageCount.md b/docs/Functions/BE_PDFPageCount.md index e69de29bb..ea9d5b01d 100644 --- a/docs/Functions/BE_PDFPageCount.md +++ b/docs/Functions/BE_PDFPageCount.md @@ -0,0 +1,37 @@ +## BE_PDFPageCount + + BE_PDFPageCount ( pdfPathOrContainer ) + +**Description** + +Counts the number of pages in a PDF file. + +**Parameters** + +* *pdfPathOrContainer* : The original file to count the pages of, either a container field or a path. + +**Keywords** + +PDF Page Count Path + +**Version History** + +* 4.0.0 : First Release +* 4.0.0 : Renamed from BE_PDF_PageCount + +**Notes** + +If the plugin can't read the file, but it is a PDF then you may get a 0 from this function. See the notes at *BE_PDFAppend* for more information. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | No | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_Pause.md b/docs/Functions/BE_Pause.md index e69de29bb..13628229f 100644 --- a/docs/Functions/BE_Pause.md +++ b/docs/Functions/BE_Pause.md @@ -0,0 +1,36 @@ +BE_Pause + + BE_Pause ( milliseconds ) + +**Description** + +Pauses ( within the plugin code, so doesn't return to FMP ) for *milliseconds*. + +**Parameters** + +* *milliseconds* : The number of milliseconds to wait for. + +**Keywords** + +Pause Time + +**Version History** + +* 3.3.0 : First Release + +**Notes** + +The plugin code runs in a single thread, so this will lock up any running script for this amount of time. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_PreferenceDelete.md b/docs/Functions/BE_PreferenceDelete.md index e69de29bb..fe6510e38 100644 --- a/docs/Functions/BE_PreferenceDelete.md +++ b/docs/Functions/BE_PreferenceDelete.md @@ -0,0 +1,53 @@ +## BE_PreferenceDelete + + BE_PreferenceDelete ( key ; { domain } ) + +**Description** + +The is the reverse of the BE_PreferenceSet function, this removes the preference at *key*, in *domain* from the system. + +Preferences set via the BE plugin are available across all open copies of FileMaker applications. + +**Parameters** + +* *key* : the key code for the value to set. +* *domain* ( optional, default: See Notes ) : the domain value of where to locate the preference file. + +**Keywords** + +Preference Delete + +**Version History** + +* 4.1.0 : First Release + +**Notes** + +If the domain is not included, there is a default used on Mac and on iOS : + + au.com.goya.baseelements.plugin-user + +On Windows the default will be : + + Software\\Goya\\BaseElements\\PluginUser + +( stored inside HKEY_CURRENT_USER ). + +On Linux this function does not run, will return error 3 - Command is unavailable. + +You can override the domain to specify a different file name on the mac, or a different path on Windows. To respect the various OS conventions you should use something similar to the above, but tailored to your solution. + +This function is required in some situations as the user can't directly delete preferences files to remove a stored preference. For example on the Mac, Setting a preference will create a corresponding file in the Users Library/Preferences folder. However deleting that file does not delete this preference until logout, and it's possible that the preference file will be recreated from memory. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | No | + +**Example Code** diff --git a/docs/Functions/BE_PreferenceGet.md b/docs/Functions/BE_PreferenceGet.md index e69de29bb..d4c4f8e42 100644 --- a/docs/Functions/BE_PreferenceGet.md +++ b/docs/Functions/BE_PreferenceGet.md @@ -0,0 +1,53 @@ +## BE_PreferenceGet + + BE_PreferenceGet ( key ; { domain } ) + +**Description** + +Gets the preference value stored by BE_SetPreference at *key*, in *domain*, from the system. + +Preferences set via the BE plugin are available across all open copies of FileMaker applications. + +**Parameters** + +* *key* : the key code for the value to get. +* *domain* ( optional, default: See Notes ) : the domain value of where to locate the preference file. + +**Keywords** + +Preference Get + +**Version History** + +* 1.3.0 : First Release +* 4.0.0 : Return error 3, command not available on Linux +* 4.0.2 : Renamed from BE_GetPreference + +**Notes** + +If the domain is not included, there is a default used on Mac and on iOS : + + au.com.goya.baseelements.plugin-user + +On Windows the default will be : + + Software\\Goya\\BaseElements\\PluginUser + +( stored inside HKEY_CURRENT_USER ). + +On Linux this function does not run, will return error 3 - Command is unavailable. + +You can override the domain to specify a different file name on the mac, or a different path on Windows. To respect the various OS conventions you should use something similar to the above, but tailored to your solution. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | No | + +**Example Code** diff --git a/docs/Functions/BE_SMTPAddAttachment.md b/docs/Functions/BE_SMTPAddAttachment.md index e69de29bb..ba3ff9873 100644 --- a/docs/Functions/BE_SMTPAddAttachment.md +++ b/docs/Functions/BE_SMTPAddAttachment.md @@ -0,0 +1,53 @@ +## BE_SMTPAddAttachment + + BE_SMTPAddAttachment ( { attachment ; contentType } ) + +**Description** + +Adds the details of the file in the *attachment* container field to the list of attachments, for future *BE_SMTPSend* functions, to be sent with the *contentType*. + +**Parameters** + +* *attachment* : A container field to use as an attachment in an email. +* *contentType* : A mime content type for the attachment. + +**Keywords** + +SMTP Attachment Add ContainerField + +**Version History** + +* 3.3.0 : First Release +* 4.0.0 : Changed the *container* parameter to *attachment* and added the *contentType* parameter +* 4.0.2 : Renamed from BE_SMTP_AddAttachment + +**Notes** + +The *BE_SMTPSend* function lets you add attachments via a path whereas this function lets you select attachments from fields. You can add multiple attachments by calling this function multiple times. Once *BE_SMTPSend* is done it clears out the list of stored attachments regardless of the success of the Send operation. + +Attachments are actually written to disk by the plugin, to the users temp folder, so this does require you to have access to a working temp folder ( defined by the OS ). + +The *contentType* is what is set as the mime type for emails. So usually something like : + + Content-Type: application/pdf; charset=UTF-8 + Content-Type: text/plain; name="file.txt" + Content-Type: application/octet-stream; name="file.pdf" + +Possible mime types are found here : + +[https://www.w3docs.com/learn-html/mime-types.html](https://www.w3docs.com/learn-html/mime-types.html) + +The result of adding the attachment may be unknown until after the *BE_SMTPSend* function has run. Use the *BE_CurlTrace* function and look for the section where the file path is referenced and any resulting error messages. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_SMTPSend.md b/docs/Functions/BE_SMTPSend.md index e69de29bb..2e2940b9d 100644 --- a/docs/Functions/BE_SMTPSend.md +++ b/docs/Functions/BE_SMTPSend.md @@ -0,0 +1,91 @@ +## BE_SMTPSend + + BE_SMTPSend ( from ; to ; subject ; text ; { cc ; bcc ; replyTo ; html ; attachments} ) + +**Description** + +Sends an email via SMTP. Use in conjunction with a call to BE_SMTPServer prior to calling this function. The To, CC, BCC and attachments parameteres can be passed value lists in order to send to multiple people or to include multiple attachments. + +**Parameters** + +* *from* : the from name and email address. +* *to* : the to name and email address. +* *subject* : subject line for the email ( a required parameter, but can be an empty string ). +* *text* : text content of the email ( a required parameter, but can be an empty string ). +* *cc* ( optional ) : the cc name and email address. +* *bcc* ( optional ) : the bcc name and email address. +* *replyTo* ( optional ) : the replyTo name and email address. +* *html* ( optional ) : the text of the HTML version of the email content. +* *attachments* ( optional ) : a list of file paths for attachments to be included. + +**Keywords** + +keyword keyword + +**Version History** + +* 3.1.0 : First Release +* 4.0.0 : Added an RFC 1123 format date header +* 4.0.2 : Renamed from BE_SMTPSend + +**Notes** + +The content of emails on some servers appears to strip FileMaker line endings. Try replacing Char ( 13 ) with Char ( 10 ) in the email content. + +Some servers, in particular various Exchange or Office365 based servers use a different authentication method. When attempting SMTP normally you may get a 35 error. You can force the correct method with : + + BE_CurlSetOption ( "BE_CURLOPT_FORCE_STARTTLS" ; True ) + +before doing BE_SMTPSend. + +**About HTML Content** + +HTML content is complex and not easily setup. We recommend you use an external process or application to generate the HTML content, and use either embedded base64 images, or links to externally hosted images. There is not support for multipart mime messages that would let you attach multiple images and then use them inline inside the HTML content. + +There are lots of examples and help around crafting HTML email content such as : + +[https://sendgrid.com/en-us/blog/create-html-emails](https://sendgrid.com/en-us/blog/create-html-emails) however we make no guarantees around the ability of the plugin to send your HTML email and have it arrive successfully and look as intended. + +We recommend people not use SMTP for email and use the various services that have APIs instead. + +**About SMTP Send and "Sent" Folders** + +A message being put into sent folder is a function of the mail client that sends it : it creates the message to send, sends a copy via the SMTP server, and then on success gives the IMAP server a second copy to save into the users *Sent* folder via IMAP. + +The BE plugin SMTP only does the SMTP send part, so in order to save a copy in a Sent folder, you'd need to have use IMAP functions to save to the sent folder, along with the correct IMAP server credentials, which may be different than the SMTP server and credentials. This is technically possible using the HTTP functions and curl options, but is beyond the scope of the intended use of this function. + +Other options for retaining sent emails are : + +* Some email services let you use an API instead of SMTP, ( eg google or O365 ) and that API may keep copies in the sent folder. +* BCC to an archive email address that stores old copies on the mail server. +* Keep them in a table in FileMaker instead. + +See the *BE_SMTPAddAttachment* documentation for sending attachments from container fields. + +--- + +Authentication is controlled with curl, so additional options, other than the defaults can be set with the *BE_CurlSetOption* function, and headers can be set via the *BE_SMTPSetHeader* function. + +Not all servers respond with data when doing curl operations so use *BE_GetLastError* after the function call to tell if the call was able to be made. + +Error codes that you get from the *BE_GetLastError* function after this function call comes from the curl library itself and not the plugin. To find a specific error code use this documentation : + +[http://curl.haxx.se/libcurl/c/libcurl-errors.html](http://curl.haxx.se/libcurl/c/libcurl-errors.html) + +Also use the *BE_CurlTrace* function to see the transcript of the connection to diagnose any other issues that may have come up and can't be determined from the error value alone. + + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_SMTPSend ( "me@me.com" ; "you@you.com" ; "Subject goes here" ; $textContent ; $cc ; $bcc ; "replyto@me.com" ; $htmlContent ; "/path/to/doc.pdf¶/path/to/secondDoc.pdf" ) \ No newline at end of file diff --git a/docs/Functions/BE_SMTPServer.md b/docs/Functions/BE_SMTPServer.md index e69de29bb..fb34ab6bd 100644 --- a/docs/Functions/BE_SMTPServer.md +++ b/docs/Functions/BE_SMTPServer.md @@ -0,0 +1,50 @@ +## BE_SMTPServer + + BE_SMTPServer ( server ; { port ; username ; password ; keepOpen } ) + +**Description** + +Stores the SMTP connection details for future calls to the *BE_SMTPSend* function. + +**Parameters** + +* *server* : A domain name or IP address of the SMTP server to connect to. +* *port* : the port number ( a required parameter, but can be an empty string ). +* *password* ( optional ) : The password if the url requires authentication. +* *fileName* ( optional ) : The filename to send when sending binary data. +* *keepOpen* ( optional, default:False , ProOnly ) : Whether to keep the connection open for future sends. + +To use the *keepOpen* option, set this to True when sending multiple messages via SMTP in a loop to avoid closing the connection to the server and re-opening it every time. This will be faster and less work for the server and the plugin. To close the connection, use the same command but change the keepOpen parameter to False. + +**Keywords** + +keyword keyword + +**Version History** + +* 3.1.0 : First Release +* 4.0.2 : Renamed from BE_SMTP_Server +* 5.0.0 : Renamed from BE_SMTPSend + +**Notes** + +This function doesn't connect to the server itself it only stores the connection details for future *BE_SMTPSend* function calls. + +Authentication is controlled with curl, so additional options, other than the defaults can be set with the *BE_CurlSetOption* function, and headers can be set via the *BE_SMTPSetHeader* function. + +Any future calls to this function overwrite any existing details. + +port number can be left as an empty string, which will attempt to use whatever ports the server requires, default for SMTP is 25, but using SSL or TLS may use 465 or 587. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_SMTPSetHeader.md b/docs/Functions/BE_SMTPSetHeader.md index e69de29bb..43c79ff0e 100644 --- a/docs/Functions/BE_SMTPSetHeader.md +++ b/docs/Functions/BE_SMTPSetHeader.md @@ -0,0 +1,50 @@ +## BE_SMTPSetHeader + + BE_SMTPSetHeader ( { header ; value } ) + +**Description** + +Sets a custom SMTP header for subsequent SMTP send actions. + +**Parameters** + +* *header* ( optional ) : header name. +* *value* ( optional ) : header value. + +You can remove all headers by calling with no parameters. + +**Keywords** + +SMTP Header Set + +**Version History** + +* 4.0.0 : First Release +* 4.0.2 : Renamed from BE_SMTP_Set_Header + +**Notes** + +A useful list of possible header values can be found here : + +[https://www.iana.org/assignments/message-headers/message-headers.xhtml](https://www.iana.org/assignments/message-headers/message-headers.xhtml) + +Some possible uses for this function are to apply headers such as : + + X-Priority: 1 (Highest) + X-MSMail-Priority: High + Importance: High + +The actual effect of setting this header depends on the both the mail server and clients. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_ScriptExecute.md b/docs/Functions/BE_ScriptExecute.md index e69de29bb..166d749af 100644 --- a/docs/Functions/BE_ScriptExecute.md +++ b/docs/Functions/BE_ScriptExecute.md @@ -0,0 +1,40 @@ +## BE_ScriptExecute + + BE_ScriptExecute ( scriptName ; { fileName ; parameter ; scriptControl } ) + +**Description** + +Performs the script called *scriptName* in the current file ( if no fileName provided, or in *fileName* if available ). +**Parameters** + +* *scriptName* : the name of the script to perform. +* *fileName* ( optional, default:current File ) : a filename of the file in which to locate the script. +* *parameter* ( optional ) : the parameter to pass to the script called. +* *scriptControl* ( optional, default:Pause ) : The values for this parameter are: Halt = 0, Exit = 1, Resume = 2, Pause = 3. + +**Keywords** + +Script + +**Version History** + +* 1.0.0 : First Release + +**Notes** + +Scripts called from the plugin are added to the script queue, so they run when the current script queue is empty. In other words you can't have a calculation within a script, call a script using this plugin function, and have it start immediately. It will run at the completion of the current script. Script results are not set and cannot be returned. + +Be aware, there is an issue in the plugin API where filenames can only have a single "." in their name. Files with more than one will return an error 100 - File is missing. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_ScriptStepInstall.md b/docs/Functions/BE_ScriptStepInstall.md index e69de29bb..21dc5f4dd 100644 --- a/docs/Functions/BE_ScriptStepInstall.md +++ b/docs/Functions/BE_ScriptStepInstall.md @@ -0,0 +1,67 @@ +## BE_ScriptStepInstall + + BE_ScriptStepInstall ( name ; definitionXML ; id ; description ; calculation ) + +**Description** + +Creates a new definition of a script step, using *definitionXML* with the name of the step as *name*. We created this function because we weren't sure what of our functions should be exposed as script steps as well as functions. This step lets us ( and you ) build new steps from existing functionality. Then we can decide to make them permanent features ( or not ). + +**Parameters** + +* *name* : the name of the new step. +* *definitionXML* : the XML that defines the operation of the step. Details about this are in the SDK, but we'll also try to locate some better documentation. +* *id* : an internal id number for the step. These can't be re-used. +* *description* : a text description that appears when you select the step in the script editor. +* *calculation* : the calculation for taking the step details and turning them into a result. + +**Keywords** + +Script Step Install + +**Version History** + +* 4.0.0 : First Release + +**Notes** + +Calculation parameter : + +You can reference the values returned by the UI parameters in your step, by using text like ###0### in your calculation. Each parameter will be numbered from 0 to x and you just use ###0###, or ###1### or ###2### in your calculation and these will be replaced on completion. + +XML Definition : + +This XML is the text that will be passed to the scriptStepDefinition parameter of the RegisterScriptStep function. Up to ten script parameters can be specified in addition to the optional target parameter. All the parameters are defined with tags in a grouping. + +The attributes for a tag include: + +* Type - if not one of the following four types, the parameter is ignored + +1. Calc - a standard Specify button that brings up the calculation dialog. When the script step is executed, the calculation will be evaluated and its results passed to the plug-in. +2. Bool - simple check box that returns the value of 0 or 1. +3. List - a static drop-down or pop-up list in which the id of the item selected is returned. The size limit of this list is limited by the capabilities of the UI widgets used to display it. A List type parameter expects to contain tags as specified below. +4. Target - will include a specify button that uses the new Insert From Target field targeting dialog that allows a developer to put the results of a script step into a field (whether or not it is on a layout), into a variable, or insert into the current active field on a layout. If no Target is defined then the result Data object is ignored. If there are multiple Target definitions, only the first one will be honored. + +* ID - A value in the range of 0 to 9 which is used as an index into the DataVect& parms object for the plug-in to retrieve the value of the parameter. Indexes that are not in range or duplicated will cause the parameter to be ignored. A parameter of type Target ignores this attribute if specified + +* Label - The name of parameter or control that is displayed in the UI + +* DataType - only used by the Calc and Target parameter types. If not specified or not one of the six data types, the type Text will be used 1. Text 2. Number 3. Date 4. Time 5. Timestamp 6. Container + +* ShowInline - value is either true or false. If defined and true, will cause the parameter to show up inlined with the script step in the Scripting Workspace + +* Default - either the numeric index of the default list item or the true/false value for a bool item. Ignored for calc and target parameters + +Parameters of type List are expected to contain tags whose values are used to construct the drop-down or pop-up list. The id of a value starts at zero but specific id can be given to a value by defining an "ID" attribute. If later values do not have an "ID" attributes the id will be set to the previous values id plus one. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | No | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_ScriptStepPerform.md b/docs/Functions/BE_ScriptStepPerform.md index e69de29bb..f3d92ce3b 100644 --- a/docs/Functions/BE_ScriptStepPerform.md +++ b/docs/Functions/BE_ScriptStepPerform.md @@ -0,0 +1,36 @@ +## BE_ScriptStepPerform + + BE_ScriptStepPerform ( scriptStepId ) + +**Description** + +Performs a script step that was previously created with the *BE_ScriptStepInstall*, but performs it via id instead of via the usual Perform Script step. + +**Parameters** + +* *scriptStepId* : the id of the step to be performed. + +**Keywords** + +Script Step Perform + +**Version History** + +* 4.0.0 : First Release + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | No | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_ScriptStepRemove.md b/docs/Functions/BE_ScriptStepRemove.md index e69de29bb..6d33d63a1 100644 --- a/docs/Functions/BE_ScriptStepRemove.md +++ b/docs/Functions/BE_ScriptStepRemove.md @@ -0,0 +1,36 @@ +## BE_ScriptStepRemove + + BE_ScriptStepRemove ( scriptStepId ) + +**Description** + +Removes the step definition from memory. This will cause issues if you try to run a step with the previous definition. + +**Parameters** + +* *scriptStepId* : the id of the step to be removed. + +**Keywords** + +Script Step Remove + +**Version History** + +* 4.0.0 : First Release + +**Notes** + +Be careful, there is no undo. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | No | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_SetPreference.md b/docs/Functions/BE_SetPreference.md index e69de29bb..3e0ee955b 100644 --- a/docs/Functions/BE_SetPreference.md +++ b/docs/Functions/BE_SetPreference.md @@ -0,0 +1,54 @@ +BE_SetPreference + + BE_SetPreference ( key ; value ; { domain } ) + +**Description** + +Gets the preference value stored by BE_SetPreference at *key*, in *domain*, from the system. + +Preferences set via the BE plugin are available across all open copies of FileMaker applications. + +**Parameters** + +* *key* : the key code for the value to get. +* *value* : the value to store in this key. +* *domain* ( optional, default: See Notes ) : the domain value of where to locate the preference file. + +**Keywords** + +Preference Get + +**Version History** + +* 1.3.0 : First Release +* 4.0.0 : Return error 3, command not available on Linux +* 4.0.2 : Renamed from BE_SetPreference + +**Notes** + +If the domain is not included, there is a default used on Mac and on iOS : + + au.com.goya.baseelements.plugin-user + +On Windows the default will be : + + Software\\Goya\\BaseElements\\PluginUser + +( stored inside HKEY_CURRENT_USER ). + +On Linux this function does not run, will return error 3 - Command is unavailable. + +You can override the domain to specify a different file name on the mac, or a different path on Windows. To respect the various OS conventions you should use something similar to the above, but tailored to your solution. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | No | + +**Example Code** diff --git a/docs/Functions/BE_SetTextEncoding.md b/docs/Functions/BE_SetTextEncoding.md index e69de29bb..5142a70bb 100644 --- a/docs/Functions/BE_SetTextEncoding.md +++ b/docs/Functions/BE_SetTextEncoding.md @@ -0,0 +1,58 @@ +## BE_SetTextEncoding + + BE_SetTextEncoding ( { encoding } ) + +**Description** + +Sets the text encoding format for any function that writes or reads text on disk, for example the *BE_WriteTextToFile* function. + +**Parameters** + +* *encoding* ( optional, default:UTF_8 ) : the encoding format to use. By leaving this parameter off, or setting it to empty you reset the encoding to its default. + +**Keywords** + +Set Text Encoding + +**Version History** + +* 1.0.0 : First Release + +**Notes** + +This is using the iconv library so the full list of encoding options can be found at + +[http://www.gnu.org/software/libiconv/ ](http://www.gnu.org/software/libiconv/ ) + +or by typing "iconv -l" on the command line. + +Note that if you've got content that does not match the encoding specified, the result may be an error or may be indeterminate depending on the library in use. As a general rule we don't try to convert one set of text to another as the outcome may not be as the user intended. + +If you're at all curious about encoding and why it's so complex, this is a good write up : + +[https://tonsky.me/blog/unicode/](https://tonsky.me/blog/unicode/) + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + +To use UTF_16 which is the default encoding of the XML DDR : + + BE_SetTextEncoding ( "UTF-16" ) + +To use ISO-8859-1 which is a common windows encoding. + + BE_SetTextEncoding ( "ISO-8859-1" ) + +To revert back to default UTF-8 : + + BE_SetTextEncoding diff --git a/docs/Functions/BE_SignatureGenerateRSA.md b/docs/Functions/BE_SignatureGenerateRSA.md index e69de29bb..5ff474be2 100644 --- a/docs/Functions/BE_SignatureGenerateRSA.md +++ b/docs/Functions/BE_SignatureGenerateRSA.md @@ -0,0 +1,41 @@ +## BE_SignatureGenerateRSA + + BE_SignatureGenerateRSA ( data ; privateKey ; { privateKeyPassword ; algorithm ; fileNameWithExtension } ) + +**Description** + +Generates a digital signature of *data*. The message digest of data is calculated first using the specified *algorithm*. Then the digest is encrypted with *privateKey*. + +**Parameters** + +* *data* : The data to be signed. It can be text or container field. +* *privateKey* : The openssl private key (as text) to digitally sign the input text. PKCS#1 and PKCS#8 PEM formats are supported. +* *privateKeyPassword* ( optional, default:empty ) : The password of the private key if required. It will be ignored if the private key is not password-protected. +* *algorithm* ( optional, default:SHA256 ) : The hash algorithm name (as text) use to calculate the digest of the data. +* *fileNameWithExtension* ( optional, default:BE_MessageDigestAlgorithmSHA256 ) : The filename and extension for the generated signature file. + +**Keywords** + +Signature RSA + +**Version History** + +* 4.0.0 : First Release +* 4.0.2 : Renamed from BE_SignatureGenerate_RSA + +**Notes** + +Uses OpenSSL so algorithms come from there, and should be generally compatible with the equivalent openssl commands. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_SignatureVerifyRSA.md b/docs/Functions/BE_SignatureVerifyRSA.md index e69de29bb..46435e613 100644 --- a/docs/Functions/BE_SignatureVerifyRSA.md +++ b/docs/Functions/BE_SignatureVerifyRSA.md @@ -0,0 +1,40 @@ +## BE_SignatureVerifyRSA + + BE_SignatureVerifyRSA ( data ; publicKey ; { signature ; algorithm ) + +**Description** + +Verifies if signature is valid for *data* by comparing the message digest of *data* with the digest obtained from *signature* by decrypting it using *publicKey*. + +**Parameters** + +* *data* : The source data that was signed. It can be text or container field. +* *publicKey* : The openssl public key (as text) to verify the digital signature. PKCS#1 and PKCS#8 PEM formats are supported. +* *signature* : The digital signature. It can be container field or Base64 encoded text. +* *algorithm* ( optional, default:SHA256 ) : The hash algorithm name (as text) use to calculate the digest of the data. + +**Keywords** + +Signature RSA Verify + +**Version History** + +* 4.0.0 : First Release +* 4.0.2 : Renamed from BE_SignatureVerify_RSA + +**Notes** + +Uses OpenSSL so algorithms come from there, and should be generally compatible with the equivalent openssl commands. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_TextExtractWords.md b/docs/Functions/BE_TextExtractWords.md index e69de29bb..6c3b9b1e2 100644 --- a/docs/Functions/BE_TextExtractWords.md +++ b/docs/Functions/BE_TextExtractWords.md @@ -0,0 +1,49 @@ +## BE_TextExtractWords + + BE_TextExtractWords ( text ; { wordPrefix } ) + +**Description** + +This returns a list of all the "words" in the *text* that start with the *wordPrefix* character. + +**Parameters** + +* *text* : the text to search on. +* *wordPrefix* ( optional, default:$ or @ ) : a single chararacter to use as the first character of the words to find. + +**Keywords** + +keyword keyword + +**Version History** + +* 1.0.0 : First Release + +**Notes** + +Originally an internal only function, this was not exposed as an option in the functions list but as of 4.2, we've made this one visible in case it's useful to others. + +Our use case for this was to use it inside the BaseElements developer tool engine, to retrieve all the variables from a block of calculation text, but getting anything that starts with $. We expanded it to @ for other similar functionality. + +Words are delimited ( ended ) by one of the following characters : + + ; +-=*/&^<>\t\r[]()\u2260\u2264\u2265, + +Note that this list of characters includes a space. The ones starting with \u are single unicode characters. + +Also note that this function leaves out any text within FileMaker comments, so from // to the endOfLine and from /* to */ So it won't find any words inside those characters. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_TextExtractWords ( "apple bear $ball" ) = "$ball" \ No newline at end of file diff --git a/docs/Functions/BE_TimeCurrentMilliseconds.md b/docs/Functions/BE_TimeCurrentMilliseconds.md index e69de29bb..7cfecec9a 100644 --- a/docs/Functions/BE_TimeCurrentMilliseconds.md +++ b/docs/Functions/BE_TimeCurrentMilliseconds.md @@ -0,0 +1,36 @@ +## BE_TimeCurrentMilliseconds + + BE_TimeCurrentMilliseconds + +**Description** + +Returns the current time as number of milliseconds. Effectively the same as GetAsNumber ( Get ( CurrentTimestamp ) ). + +**Parameters** + +None + +**Keywords** + +Time UTC Milliseconds + +**Version History** + +* 2.0.0 : First Release + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_TimeUTCMilliseconds.md b/docs/Functions/BE_TimeUTCMilliseconds.md index e69de29bb..9fc74d643 100644 --- a/docs/Functions/BE_TimeUTCMilliseconds.md +++ b/docs/Functions/BE_TimeUTCMilliseconds.md @@ -0,0 +1,37 @@ +## BE_TimeUTCMilliseconds + + BE_TimeUTCMilliseconds + +**Description** + +Returns UTC time as number of milliseconds - the same as the time from BE_TimeCurrentMilliseconds but in the UTC timezone. + +**Parameters** + +None + +**Keywords** + +Time UTC Milliseconds + +**Version History** + +* 2.0.0 : First Release +* 4.0.2 : Renamed from BE_UTCMilliseconds + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_TimeZoneOffset.md b/docs/Functions/BE_TimeZoneOffset.md index e69de29bb..6f9fc7d57 100644 --- a/docs/Functions/BE_TimeZoneOffset.md +++ b/docs/Functions/BE_TimeZoneOffset.md @@ -0,0 +1,36 @@ +## BE_TimeZoneOffset + + BE_TimeZoneOffset + +**Description** + +Returns the difference ( in minutes ) between UTC and local time. + +**Parameters** + +None + +**Keywords** + +Time UTC Milliseconds Offset + +**Version History** + +* 2.0.0 : First Release + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_UnGzip.md b/docs/Functions/BE_UnGzip.md index e69de29bb..00c2c6509 100644 --- a/docs/Functions/BE_UnGzip.md +++ b/docs/Functions/BE_UnGzip.md @@ -0,0 +1,37 @@ +## BE_UnGzip + + BE_UnGzip ( gzip_data ; { filename } ) + +**Description** + +Uncompresses the file found in *gzip_data* and optionally applies the *filename*, otherwise uses the detail found in the container field if it exists. + +**Parameters** + +* *gzip_data* : a container field with an gzipped file in it. +* *filename* : optional filename to use, appending the .gzip extension. + +**Keywords** + +Gzip zip Ungzip unzip + +**Version History** + +* 3.3.0 : First Release + +**Notes** + +If you're unzipping a file, then this function should be used with a *Set Field* script step and the results stored as a container field. If you're expecting a text result then this could be used anywhere text is expected. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_Unzip.md b/docs/Functions/BE_Unzip.md index e69de29bb..61d15f3a0 100644 --- a/docs/Functions/BE_Unzip.md +++ b/docs/Functions/BE_Unzip.md @@ -0,0 +1,48 @@ +## BE_Unzip + + BE_Unzip ( archiveFilePath ; { outputFolderPath } ) + +**Description** + +Unzips the archive file found at the path *archiveFilePath*. The unzipped file(s) are put into the same location as the zip file itself by default, or into the *outputFolderPath* if specified. Any existing file(s) will be overwritten. + +**Parameters** + +* *archiveFilePath* : a plugin file path, or a container field. +* *filename* : a system folder path to put the result.. + + If the *archiveFilePath* container field contains text, it's treated as a path to a file. + +**Keywords** + +Zip Unzip + +**Version History** + +* 1.3.0 : First Release +* 2.2.0 : added the outputFolderPath parameter +* 4.2.0 : added the option to allow archiveFilePath to be a container field + +**Notes** + +If you're unzipping a file, then this function should be used with a *Set Field* script step and the results stored as a container field. If you're expecting a text result then this could be used anywhere text is expected. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_Unzip ( BE_SelectFile ( "Select a Zip file to unzip." ) ) + + BE_Unzip ( "/Users/nick/Desktop/MyFile.zip" ) + BE_Unzip ( "/Users/nick/Desktop/MyFile.zip" ; "/Users/nick/Desktop/ResultFolder") + + \ No newline at end of file diff --git a/docs/Functions/BE_ValuesUnique.md b/docs/Functions/BE_ValuesUnique.md index 5dadda0e8..8429143c2 100644 --- a/docs/Functions/BE_ValuesUnique.md +++ b/docs/Functions/BE_ValuesUnique.md @@ -13,7 +13,7 @@ Removes duplicate values from listOfValues. **Keywords** -Values Unique +Values Unique List **Version History** diff --git a/docs/Functions/BE_VariableGet.md b/docs/Functions/BE_VariableGet.md index 140cdae10..ba538f9d9 100644 --- a/docs/Functions/BE_VariableGet.md +++ b/docs/Functions/BE_VariableGet.md @@ -1,14 +1,14 @@ ## BE_VariableGet - BE_VariableGet ( name ) + BE_VariableGet ( name ) **Description** -This function gets the previously stored variable of name. +Gets the value of the previously stored plugin variable with *name*. **Parameters** -* *name* : The name of the variable to return. +* *name* : the name of the variable to return. **Keywords** @@ -22,6 +22,8 @@ Variable Get Plugin variables are much like $local and $$global FileMaker variables, except the scope is the instance of the plugin, so will persist across FileMaker files and even on closing and opening of files. They are only lost when the plugin is loaded or unloaded, usually only ever when FileMaker restarts. +On FileMaker Server they exist in a single session, and not across different sessions as each session is a new application launch effectively. + **Compatibility** | Platform | Compatibility | @@ -34,4 +36,3 @@ Plugin variables are much like $local and $$global FileMaker variables, except t | Linux | Yes | **Example Code** - diff --git a/docs/Functions/BE_VariableSet.md b/docs/Functions/BE_VariableSet.md index b1d94277f..94a737daa 100644 --- a/docs/Functions/BE_VariableSet.md +++ b/docs/Functions/BE_VariableSet.md @@ -1,15 +1,15 @@ ## BE_VariableSet - BE_VariableSet ( name ; { value } ) + BE_VariableSet ( name ; { value } ) **Description** -This function creates and sets a variable of *name* with *value*. +Sets *value* into a plugin preference with name of *name*. **Parameters** -* *name* : The name of the variable to create/set. -* *value* ( optional ) : The value to store. Optional because an empty value will delete that variable. +* *name* : the name of the variable to return. +* *value* ( optional ) : the value to store. An empty value will delete that variable. **Keywords** @@ -23,6 +23,8 @@ Variable Set Plugin variables are much like $local and $$global FileMaker variables, except the scope is the instance of the plugin, so will persist across FileMaker files and even on closing and opening of files. They are only lost when the plugin is loaded or unloaded, usually only ever when FileMaker restarts. +On FileMaker Server they exist in a single session, and not across different sessions as each session is a new application launch effectively. + **Compatibility** | Platform | Compatibility | @@ -35,4 +37,3 @@ Plugin variables are much like $local and $$global FileMaker variables, except t | Linux | Yes | **Example Code** - diff --git a/docs/Functions/BE_VectorDotProduct.md b/docs/Functions/BE_VectorDotProduct.md index e69de29bb..658d7319c 100644 --- a/docs/Functions/BE_VectorDotProduct.md +++ b/docs/Functions/BE_VectorDotProduct.md @@ -0,0 +1,42 @@ +## BE_VectorDotProduct + + BE_VectorDotProduct ( a ; b ) + +**Description** + +Does a dot product of two vectors ( lists ) of numbers. + +**Parameters** + +* *a* : the first list. +* *b* : the second list. + +**Keywords** + +Vector DotProductkeyword + +**Version History** + +* 3.2.0 : First Release +* 4.0.2 : Renamed from BE_Vector_DotProduct + +**Notes** + +For more information about vectors, have a look at : + +[http://www.mathsisfun.com/algebra/vectors-dot-product.html](http://www.mathsisfun.com/algebra/vectors-dot-product.html) + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_VectorDotProduct ( "1¶3¶-5" ; "4¶-2¶-1" ) = 3 diff --git a/docs/Functions/BE_VectorEuclideanDistance.md b/docs/Functions/BE_VectorEuclideanDistance.md index e69de29bb..68b3f54c0 100644 --- a/docs/Functions/BE_VectorEuclideanDistance.md +++ b/docs/Functions/BE_VectorEuclideanDistance.md @@ -0,0 +1,42 @@ +## BE_VectorEuclideanDistance + + BE_VectorEuclideanDistance ( a ; b ) + +**Description** + +The euclidean distance between two vector points. + +**Parameters** + +* *a* : vector a as a list. +* *b* : vector b as a list. + +**Keywords** + +Vector DotProductkeyword + +**Version History** + +* 3.2.0 : First Release +* 4.0.2 : Renamed from BE_Vector_EuclideanDistance + +**Notes** + +For more information about this see : + +[https://en.wikipedia.org/wiki/Euclidean_distance](https://en.wikipedia.org/wiki/Euclidean_distance) + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_VectorEuclideanDistance ( "1¶3¶-5" ; "4¶-2¶-1" ) = 7.07107 diff --git a/docs/Functions/BE_Version.md b/docs/Functions/BE_Version.md index e69de29bb..35d88e81a 100644 --- a/docs/Functions/BE_Version.md +++ b/docs/Functions/BE_Version.md @@ -0,0 +1,40 @@ +## BE_Version + + BE_Version + +**Description** + +Returns the plugin version number as text, eg 1.1.3 + +**Parameters** + +None + +**Keywords** + +Version + +**Version History** + +* 1.0.0 : First Release + +**Notes** + +This function should be not be used to when checking for latest updates, as the text string response of it is not easily compared. For example : + + "1.9.0" < "1.10.0" + +even though 10 is greater than 9. To compare versions in order of release, use *GetAsNumber ( BE_VersionAutoUpdate )* instead and then use *BE_Version* to show a meaningful result to the end user. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_VersionAutoUpdate.md b/docs/Functions/BE_VersionAutoUpdate.md index e69de29bb..4a9f3d573 100644 --- a/docs/Functions/BE_VersionAutoUpdate.md +++ b/docs/Functions/BE_VersionAutoUpdate.md @@ -0,0 +1,36 @@ +## BE_Version + + BE_Version + +**Description** + +The text of the plugin number, formatted as an 8 digit number, eg 04020400. This is broken into four parts, and so 4.2.4 would become 04020400 as 04 02 04 00. The final two digits come from a minor rebuild version, if there was one, when we did new builds but didn't change version number. This may be due to build issues or signing updates etc. + +**Parameters** + +None + +**Keywords** + +Version Auto Update + +**Version History** + +* 1.0.0 : First Release + +**Notes** + +This function should be used in place of *BE_Version* when checking for latest updates and comparing versions as numbers, as the text string response of *BE_Version* is not as easily compared. Use *BE_Version* when showing a meaningful description to the end user. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_XMLParse.md b/docs/Functions/BE_XMLParse.md index e69de29bb..247f97842 100644 --- a/docs/Functions/BE_XMLParse.md +++ b/docs/Functions/BE_XMLParse.md @@ -0,0 +1,39 @@ +## BE_XMLParse + + BE_XMLParse ( pathOrXMLText ) + +**Description** + +Parses an XML file at *pathOrXMLText* to determine if it's properly formed. Does not check XSD details, just whether every tag is properly opened and closed. + +The result will be empty when successful with a *BE_GetLastError* returning 0. + +**Parameters** + +* *pathOrXMLText* : the xml text or a plugin path to locate the file to parse. + +**Keywords** + +XML Parse Path + +**Version History** + +* 2.2.0 : First Release +* 4.0.2 : Renamed from BE_XML_Parse + +**Notes** + +This function will look at the content of the text in the pathOrXMLText parameter, and if the first character is < then it assumes it is XML and treats it as such. Any other first character means it assumes it's a path and will try to use it as a path on disk. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_XMLStripInvalidCharacters.md b/docs/Functions/BE_XMLStripInvalidCharacters.md index e69de29bb..7b96a0aa8 100644 --- a/docs/Functions/BE_XMLStripInvalidCharacters.md +++ b/docs/Functions/BE_XMLStripInvalidCharacters.md @@ -0,0 +1,37 @@ +## BE_XMLStripInvalidCharacters + + BE_XMLStripInvalidCharacters ( path ; { resultFilePath } ) + +**Description** + +This function removes characters considered invalid in XML from the file at *path*, and optionally writes the fixed file to the *resultFilePath*. + +**Parameters** + +* *path* : The path to the text XML file to read. +* *resultFilePath* ( optional, default:path ) : If supplied, this will write the output to a new file. If not supplied then the original file will be overwritten. + +**Keywords** + +XML Strip Invalid Characters + +**Version History** + +* 4.2.0 : First Release + +**Notes** + +Used originally internal as a BaseElements developer tool function, likely not useful for anyone else. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_XMLStripNodes.md b/docs/Functions/BE_XMLStripNodes.md index e69de29bb..182ff0994 100644 --- a/docs/Functions/BE_XMLStripNodes.md +++ b/docs/Functions/BE_XMLStripNodes.md @@ -0,0 +1,42 @@ +## BE_XMLStripNodes + + BE_XMLStripNodes ( inputFilePath ; outputFilePath ; nodeNames ) + +**Description** + +This function removes the supplied list *nodeNames* of XML nodes from the source document at *inputFilePath* and writes the result to *outputFilePath*. + +**Parameters** + +* *inputFilePath* : the plugin path to the XML file to read from. +* *outputFilePath* : the plugin path to write the output to. +* *nodeNames* : a space separated list of xml node names to remove. + +**Keywords** + +XML Strip Nodes Path + +**Version History** + +* 4.2.0 : First Release + +**Notes** + +Previously an internal hidden function, was made public in 4.2.0. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + +To remove the *HexData* and *PlatformData* nodes from an XML DDR file, you can use : + + BE_XMLStripNodes ( $inputFilePath ; $outputFilePath ; "HexData PlatformData" ) diff --git a/docs/Functions/BE_XMLTidy.md b/docs/Functions/BE_XMLTidy.md index e69de29bb..68366a4d5 100644 --- a/docs/Functions/BE_XMLTidy.md +++ b/docs/Functions/BE_XMLTidy.md @@ -0,0 +1,36 @@ +## BE_XMLTidy + + BE_XMLTidy ( xml ) + +**Description** + +Does a "tidy" to reformat nicely the XML text. + +**Parameters** + +* *xml* : the xml text to be cleaned up. + +**Keywords** + +XML Tidy + +**Version History** + +* 4.2.0 : First Release + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_XMLValidate.md b/docs/Functions/BE_XMLValidate.md index e69de29bb..074a8fb52 100644 --- a/docs/Functions/BE_XMLValidate.md +++ b/docs/Functions/BE_XMLValidate.md @@ -0,0 +1,38 @@ +## BE_XMLValidate + + BE_XMLValidate ( xmlText ; schemaText ) + +**Description** + +Validates the XML in *xmlText* against an XSD *schemaText* for correctness. + +**Parameters** + +* *xmlText* : the XML text to be validated. +* *schemaText* : the XSD schema text to validate against. + +**Keywords** + +XML Validate Schema + +**Version History** + +* 4.0.0 : First Release +* 4.0.2 : Renamed from BE_XML_Validate + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_XML_Canonical.md b/docs/Functions/BE_XML_Canonical.md index e69de29bb..3051f38ec 100644 --- a/docs/Functions/BE_XML_Canonical.md +++ b/docs/Functions/BE_XML_Canonical.md @@ -0,0 +1,40 @@ +## BE_XML_Canonical + + BE_XML_Canonical ( xml ) + +**Description** + +Generates the Canonical version of given *xml* document - Canonical XML is otherwise known as a "normal form" of XML, intended to allow relatively simple comparison of pairs of XML documents for equivalence. + +Result is the output Canonical XML text. + +**Parameters** + +* *xml* : The text content of the XML to be used. + +**Keywords** + +XML Canonical + +**Version History** + +* 4.1.2 : First Release + +**Notes** + +Canonical XML is a specially structured version of XML that applies certain rules and will therefore be able to compared or used in certain validation processes. + +See [https://en.wikipedia.org/wiki/Canonical_XML](https://en.wikipedia.org/wiki/Canonical_XML) for more information about Canonical XML. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_XPath.md b/docs/Functions/BE_XPath.md index e69de29bb..d58b553e6 100644 --- a/docs/Functions/BE_XPath.md +++ b/docs/Functions/BE_XPath.md @@ -0,0 +1,45 @@ +## BE_XPath + + BE_XPath ( xmlText ; xpathText ; { namespaceListText ; asTextBoolean } ) + +**Description** + +This finds the first instance of a node at the path *xpathText* within the text *xmlText*. + +**Parameters** + +* *xmlText* : the XML text to use. +* *xpathText* : the path to the node you require. +* *namespaceListText* ( optional ) : Namespace list as "prefix1=href1 prefix2=href2...". +* *asTextBoolean* ( optional, default:False ) : Whether to return the XML nodeset as text instead of the standard XPath result. + +The *asTextBoolean* parameter when set to True allows you to get raw XML from the source - normally where the XPath function would return a node, with it's opening and closing tag, this will return the value inside that tag instead. + +**Keywords** + +XML XPath + +**Version History** + +* 1.0.0 : First Release +* 1.2.0 : +* 2.2.0 : Added the optional asText parameter + +**Notes** + +This function is based on the libxml library which only supports XPath 1.0 [http://xmlsoft.org] + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_XPath ( $XML ; "/abc:checkUserResponse/abc:result/abc:accountDetails/@type" ; "abc=http://xml.m4u.com.au/2009" ) \ No newline at end of file diff --git a/docs/Functions/BE_XPathAll.md b/docs/Functions/BE_XPathAll.md index e69de29bb..5c0fac054 100644 --- a/docs/Functions/BE_XPathAll.md +++ b/docs/Functions/BE_XPathAll.md @@ -0,0 +1,42 @@ +## BE_XPathAll + + BE_XPathAll ( xmlText ; xpathText ; { namespaceListText } ) + +**Description** + +This finds all instances of a node at the path *xpathText* within the text *xmlText*. + +**Parameters** + +* *xmlText* : the XML text to use. +* *xpathText* : the path to the node you require. +* *namespaceListText* ( optional ) : Namespace list as "prefix1=href1 prefix2=href2...". + +**Keywords** + +XML XPath + +**Version History** + +* 1.2.0 : First Release +* 2.2.0 : support objects of type XPATH_BOOLEAN, XPATH_NUMBER and XPATH_STRING +* 2.2.1 : return an empty string when getting an empty node set as xml + +**Notes** + +This function is based on the libxml library which only supports XPath 1.0 [http://xmlsoft.org] + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + + BE_XPath ( $XML ; "/abc:checkUserResponse/abc:result/abc:accountDetails/@type" ; "abc=http://xml.m4u.com.au/2009" ) \ No newline at end of file diff --git a/docs/Functions/BE_XSLTApply.md b/docs/Functions/BE_XSLTApply.md index e69de29bb..234fd43ab 100644 --- a/docs/Functions/BE_XSLTApply.md +++ b/docs/Functions/BE_XSLTApply.md @@ -0,0 +1,45 @@ +## BE_XSLTApply + + BE_XSLT_Apply ( xmlFilePath ; xsltText ; outputFilePath {; scriptName ; databaseName ; [ xsltText ; outputFilePath ] ; ... } ) + +**Description** + +Applies the XSLT given by the *xsltText* parameter, to the XML file at *xmlFilePath*, and writes the output to *outputFilePath*. + +**Parameters** + +* *xmlFilePath* : the plugin path to the xml file to process. +* *xsltText* : the text content of the xslt to process with. +* *outputFilePath* : the plugin path to write the output result to. +* *scriptName* : a script to call on completion of the transform. +* *databaseName* : the database where scriptName resides. + +To launch the XSLT process in its own thread add the *scriptName* and optional *databaseName* parameter. When the *scriptName* parameter is used, then the XSLT process is launched in a background thread and control returns to FileMaker immediately. + +This function also allows you to launch multiple threads of the XSLT processing to happen simultaneously by appending groups of two extra parameters after the databaseName parameter, with each additional *xsltText* and *outputFilePath* in pairs. + +**Keywords** + +XML XSLT Memory + +**Version History** + +* 1.0.0 : First Release +* 5.0.0 : Added scriptName, and optional extra parameters. + +**Notes** + +When the *scriptName* option is used, the script parameter sent to *scriptName* is the response from the XSLT function if present, or the *outputFilePath* otherwise. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_XSLT_ApplyInMemory.md b/docs/Functions/BE_XSLT_ApplyInMemory.md index e69de29bb..219bb4e70 100644 --- a/docs/Functions/BE_XSLT_ApplyInMemory.md +++ b/docs/Functions/BE_XSLT_ApplyInMemory.md @@ -0,0 +1,37 @@ +## BE_XSLT_ApplyInMemory + + BE_XSLT_ApplyInMemory ( xmlText ; xsltText ) + +**Description** + +Applies the XSLT given by the *xsltText* parameter, to the XML given by the *xmlText* parameter, and and returns the result. + +**Parameters** + +* *xmlText* : the xml to process. +* *xsltText* : the text content of the xslt to process with. + +**Keywords** + +XML XSLT Memory + +**Version History** + +* 1.2.0 : First Release + +**Notes** + +Notes + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** diff --git a/docs/Functions/BE_XeroSetTokens.md b/docs/Functions/BE_XeroSetTokens.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/Functions/BE_Zip.md b/docs/Functions/BE_Zip.md index e69de29bb..c54b3d123 100644 --- a/docs/Functions/BE_Zip.md +++ b/docs/Functions/BE_Zip.md @@ -0,0 +1,58 @@ +## BE_Zip + + BE_Zip ( filePathList ; { archiveFilePath } ) + +**Description** + +Compresses the file(s) found at the *filePathList* and optionally saves the zip file to *archiveFilePath*. + +**Parameters** + +* *filePathList* : a plugin file path, or a container field. +* *archiveFilePath* : a plugin file path to put the result. + +If the *archiveFilePath* parameter is not specified, then the zip file is put into the same folder as first filename in the list, and has the .zip extension appended to the filename. This will overwrite an existing file if it exists with that name already. + +**Keywords** + +Zip Unzip + +**Version History** + +* 1.3.0 : First Release +* 2.0.0 : Bug Fixes +* 2.2.0 : added the archiveFilePath parameter +* 2.3.0 : modified the archiveFilePath parameter to allow a list of file paths, instead of a single file/folder +* 3.0.0 : improved error handling, create empty directories in archives +* 4.1.3 : don't crash when there's nothing to archive +* 4.1.3 : return an error if more than one file with the same name is added to the archive +* 4.2.0 : added the option to allow filePathList to be a container field + +**Notes** + +The zip file format doesn't have a provision for adding multiple files of the same name. So if you run : + + BE_Zip ( List ( "myfile.txt" ; "folder/myfile.txt" ) ) + +Then it will store both files in the zip, BUT when you unzip the second file will overwrite the first one. This is a limitation of the zip format, not a plugin limitation. + +**Compatibility** + +| Platform | Compatibility | +|-----------|-----------| +| Status | Active | +| Mac FMP | Yes | +| Win FMP | Yes | +| FMS | Yes | +| iOS | Yes | +| Linux | Yes | + +**Example Code** + +Example : you have 2 files in the documents folder called file1.pdf and file2.pdf that you want to add to a zip called archive.zip in the same folder. You need to convert the docs path into a plugin path first, and then do : + + Let ( [ + path = ConvertFromFileMakerPath ( Get ( DocumentsPath ) ; PosixPath ) ; + pathlist = List ( path & "file1.pdf" ; path & "file2.pdf" ) ] ; + BE_Zip ( pathlist ; path & "archive.zip" ) + ) \ No newline at end of file diff --git a/docs/Functions/Deprecated/BE_Base64_Decode.md b/docs/Functions/Deprecated/BE_Base64_Decode.md new file mode 100644 index 000000000..272075167 --- /dev/null +++ b/docs/Functions/Deprecated/BE_Base64_Decode.md @@ -0,0 +1,23 @@ +## BE_Base64_Decode + + BE_Base64_Decode ( text { ; name } ) + +**Description** + +Decodes text from Base64 into it's original value. + +**Parameters** + +* *text* : the text to decode. +* *name* ( optional ) : the name of the output file for binary content. + +**Keywords** + +Removed + +**Version History** + +* 1.3.0 : First Release +* 4.0.0 : Deprecated. Use the FileMaker 16 function *Base64Decode* instead. +* 4.2.0 : Removed. + diff --git a/docs/Functions/Deprecated/BE_Base64_Encode.md b/docs/Functions/Deprecated/BE_Base64_Encode.md new file mode 100644 index 000000000..5693b5d33 --- /dev/null +++ b/docs/Functions/Deprecated/BE_Base64_Encode.md @@ -0,0 +1,23 @@ +## BE_Base64_Encode + + BE_Base64_Encode ( text { ; name } ) + +**Description** + +Decodes text from Base64 into it's original value. + +**Parameters** + +* *text* : the text to decode. +* *name* ( optional ) : the name of the output file for binary content. + +**Keywords** + +Removed + +**Version History** + +* 1.3.0 : First Release +* 4.0.0 : Deprecated. Use the FileMaker 16 function *Base64Encode* instead. +* 4.2.0 : Removed. + diff --git a/docs/Functions/Deprecated/BE_Base64_URL_Encode.md b/docs/Functions/Deprecated/BE_Base64_URL_Encode.md new file mode 100644 index 000000000..c681fcf37 --- /dev/null +++ b/docs/Functions/Deprecated/BE_Base64_URL_Encode.md @@ -0,0 +1,22 @@ +## BE_Base64_URL_Encode + + BE_Base64_URL_Encode ( data ) + +**Description** + +Encodes data as Base64 values with url safe encoding. URL safe encoding gives output that is consistent with other online tools such as php.. + +**Parameters** + +* *data* : the data to encode. + +**Keywords** + +Removed + +**Version History** + +* 2.0.0 : First Release +* 4.0.0 : Deprecated. Use the FileMaker 16 function *Base64EncodeRFC* instead. +* 4.2.0 : Removed. + diff --git a/docs/Functions/Deprecated/BE_ExecuteShellCommand.md b/docs/Functions/Deprecated/BE_ExecuteShellCommand.md new file mode 100644 index 000000000..d4fe51c78 --- /dev/null +++ b/docs/Functions/Deprecated/BE_ExecuteShellCommand.md @@ -0,0 +1,24 @@ +## BE_ExecuteShellCommand + + BE_ExecuteShellCommand ( command { ; waitForResponse } ) + +**Description** + +Performs a command line script of the *data* parameter. + +**Parameters** + +* *command* : the command. +* *waitForResponse* : True or False. + +**Keywords** + +Removed + +**Version History** + +* 1.1.0 : First Release +* 1.2.0 : Modified to include an optional waitForResponse parameter +* 2.0.0 : Deprecated. Use *BE_ExecuteSystemCommand* instead. +* 3.0.0 : Removed. + diff --git a/docs/Functions/Deprecated/BE_FileMaker_Fields.md b/docs/Functions/Deprecated/BE_FileMaker_Fields.md new file mode 100644 index 000000000..fac170a6f --- /dev/null +++ b/docs/Functions/Deprecated/BE_FileMaker_Fields.md @@ -0,0 +1,22 @@ +BE_FileMaker_Fields + + BE_FileMaker_Fields + +**Description** + +Returns a list of the fields in the current open file. + +**Parameters** + +None + +**Keywords** + +Removed + +**Version History** + +* 1.1.0 : First Release +* 2.0.0 : Deprecated. Use internal *ExecuteSQL* instead. +* 3.0.0 : Removed. + diff --git a/docs/Functions/Deprecated/BE_FileMaker_Tables.md b/docs/Functions/Deprecated/BE_FileMaker_Tables.md new file mode 100644 index 000000000..c21a7a657 --- /dev/null +++ b/docs/Functions/Deprecated/BE_FileMaker_Tables.md @@ -0,0 +1,22 @@ +BE_FileMaker_Tables + + BE_FileMaker_Tables + +**Description** + +Returns a list of the Tables in the current open file. + +**Parameters** + +None + +**Keywords** + +Removed + +**Version History** + +* 1.1.0 : First Release +* 2.0.0 : Deprecated. Use internal *ExecuteSQL* instead. +* 3.0.0 : Removed. + diff --git a/docs/Functions/Deprecated/BE_HMAC.md b/docs/Functions/Deprecated/BE_HMAC.md new file mode 100644 index 000000000..a146d705a --- /dev/null +++ b/docs/Functions/Deprecated/BE_HMAC.md @@ -0,0 +1,26 @@ +BE_HMAC + + BE_HMAC ( text ; key ; { algorithm ; outputEncoding ; inputEncoding } ) + +**Description** + +Does HMAC encoding on the *text*, using the *key* with a specific *algorithm* and *outputEncoding*, assuming a certain *inputEncoding* for the text and key. + +**Parameters** + +* *text* : the text to be encoded. +* *key* : the key to encode with. +* *algorithm* ( optional, default:BE_MessageDigestAlgorithm_SHA1 ) : Any of the BE_MessageDigestAlgorithm options. +* *outputEncoding* ( optional, default:BE_Encoding_Hex ) : *BE_Encoding_Hex* or *BE_Encoding_Base64*. +* *inputEncoding* ( optional, default:BE_Encoding_Hex ) : *BE_Encoding_Hex* or *BE_Encoding_Base64*. + +**Keywords** + +Removed + +**Version History** + +* 3.0.0 : First Release +* 4.0.0 : Deprecated. Use internal *CryptAuthCode* instead. +* 4.2.0 : Removed. + diff --git a/docs/Functions/Deprecated/BE_JSONPath.md b/docs/Functions/Deprecated/BE_JSONPath.md new file mode 100644 index 000000000..ea58db738 --- /dev/null +++ b/docs/Functions/Deprecated/BE_JSONPath.md @@ -0,0 +1,22 @@ +## BE_JSONPath + + BE_JSONPath ( json ; path ) + +**Description** + +Query json structure using an XPath like syntax. + +**Parameters** + +* *json* : the json to parse. +* *path* : the path to the data you want. + +**Keywords** + +Removed + +**Version History** + +* 2.1.0 : First Release +* 4.0.0 : Deprecated. Use internal JSON functions instead. +* 5.0.0 : Removed. diff --git a/docs/Functions/Deprecated/BE_JSON_Encode.md b/docs/Functions/Deprecated/BE_JSON_Encode.md new file mode 100644 index 000000000..2440fc31a --- /dev/null +++ b/docs/Functions/Deprecated/BE_JSON_Encode.md @@ -0,0 +1,26 @@ +BE_JSON_Encode + + BE_JSON_Encode ( key ; { value ; type } ) + +**Description** + +Encodes a single value as JSON encoded text. + +**Parameters** + +* *key* : the name of the key value to encode. +* *value* ( optional ) : The value of the key to encode. +* *type* ( optional ) : The type is determined automatically from fields content. + +For text that you want to force to be a different type, use the *type* parameter. Possible values are Boolean ( JSON True or False ), Text or Number ( JSON integer or real, but also includes FileMaker date, time or timestamp ). Any other values will error. + +**Keywords** + +Removed + +**Version History** + +* 2.1.0 : First Release +* 4.0.0 : Deprecated. Use internal JSON functions instead. +* 4.2.0 : Removed. + diff --git a/docs/Functions/Deprecated/BE_JSON_Error_Description.md b/docs/Functions/Deprecated/BE_JSON_Error_Description.md new file mode 100644 index 000000000..11437bc83 --- /dev/null +++ b/docs/Functions/Deprecated/BE_JSON_Error_Description.md @@ -0,0 +1,21 @@ +## BE_JSON_Error_Description + + BE_JSON_Error_Description + +**Description** + +A text description of the last JSON error. + +**Parameters** + +None + +**Keywords** + +Removed + +**Version History** + +* 2.1.0 : First Release +* 4.0.0 : Deprecated. Use internal JSON functions instead. +* 5.0.0 : Removed. diff --git a/docs/Functions/Deprecated/BE_XeroSetTokens.md b/docs/Functions/Deprecated/BE_XeroSetTokens.md new file mode 100644 index 000000000..b0d16a134 --- /dev/null +++ b/docs/Functions/Deprecated/BE_XeroSetTokens.md @@ -0,0 +1,23 @@ +## BE_XeroSetTokens + + BE_XeroSetTokens ( consumer_key ; private_key ) + +**Description** + +Allows authentication to the Xero API using private keys, for use in any subsequent HTTP calls. + +**Parameters** + +* *consumer_key* : the json to parse. +* *private_key* : the path to the data you want. + +**Keywords** + +Removed + +**Version History** + +* 3.0.0 : First Release +* 4.1.4 : Deprecated. Xero no longer uses this auth mechanism, and has switched to a OAuth2 compatible process. +* 4.2.0 : Removed. +