Keyword

# Declare

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

Used to make API calls. DLLs can be called on Windows. Shared libraries can be called on Android, iOS, macOS and Linux.

## Usage

``` xojo
[Soft] Declare Sub / Function Name Lib LibraryName [Alias AliasName] [Selector theSelector] ([ Parameters ]) [As ReturnType] 
```

| Part        | Type                              | Description                                                                                                                                                                                                                                                                   |
|-------------|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Name        | Name                              | The method or function name that will be used in your Xojo code. It is typically the name of the OS API.                                                                                                                                                                      |
| LibraryName | String Literal or String Constant | The Library (DLL, shared library or framework) containing name. This must be in quotes.                                                                                                                                                                                       |
| AliasName   | `String</api/data_types/string>`  | **(Optional)** If the API call (name) has the same name as a built-in method (or you want a different name), <span class="title-ref">declare</span> the call with a different name and use the alias to refer to the actual API method name. The aliasName must be in quotes. |
| Selector    | `String</api/data_types/string>`  | **(macOS and iOS)** Used to specify the parameters to uniquely identify a Cocoa method. The parameters are separated by colons (no spaces) and must end in a colon. This is mutually exclusive with the Alias. This must be in quotes. For example: "addSubview:" like in:    |
| Parameters  |                                   | The parameters of the API call. You can pass `Nil</api/language/nil>` to a parameter of type `Ptr</api/data_types/additional_types/ptr>`.                                                                                                                                     |
| ReturnType  |                                   | **(Optional)** The data type of the value returned by the call if it is a function.                                                                                                                                                                                           |

## Notes

<div class="note">

<div class="title">

Note

</div>

Incorrect Declares, such as Declares that use an incorrect library, method, parameter or selector will crash your Xojo app. You will need to review system logs (such as Console on Mac) to see what the OS reports as the cause of the crash.

</div>

For iOS, you can <span class="title-ref">Declare</span> into Cocoa Touch APIs.

Sub/Function names are always case-sensitive. For example, SetLocalTime works on Win32, but setlocaltime does not.

You can use constants in place of libraryName.

<span class="title-ref">Declare</span> can be used to call external functions that return structure values.

You can pass `Nil</api/language/nil>` to a parameter of type `Ptr</api/data_types/additional_types/ptr>`, but passing `Nil</api/language/nil>` is not the same as passing a `Nil</api/language/nil>` `MemoryBlock</api/language/memoryblock>`. The former is a constant and the latter requires a conversion at runtime. If the `MemoryBlock</api/language/memoryblock>` is `Nil</api/language/nil>`, the conversion will raise a `NilObjectException</api/exceptions/nilobjectexception>`.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Data types

The following data types can be used with the <span class="title-ref">Declare</span> command: `Boolean</api/data_types/boolean>`, `Integer</api/data_types/integer>`, `Int8</api/data_types/additional_types/int8>`, `Int16</api/data_types/additional_types/int16>`, `Int32</api/data_types/additional_types/int32>`, `Int64</api/data_types/additional_types/int64>`, `UInt8</api/data_types/additional_types/uint8>`, `Byte</api/data_types/additional_types/byte>`, `UInt16</api/data_types/additional_types/uint16>`, `UInt32</api/data_types/additional_types/uint32>`, `UInt64</api/data_types/additional_types/uint64>`, `CFStringRef</api/data_types/additional_types/cfstringref>`, `CGFloat</api/data_types/additional_types/cgfloat>`, `Double</api/data_types/double>`, `Single</api/data_types/single>`, `CString</api/data_types/additional_types/cstring>`, `OSType</api/data_types/additional_types/ostype>`, `PString</api/data_types/additional_types/pstring>`, `Ptr</api/data_types/additional_types/ptr>`, `WString</api/data_types/additional_types/wstring>`, and `Structure</api/language/structure>`.

You can pass `Nil</api/language/nil>` in place of a `CString</api/data_types/additional_types/cstring>`, `WString</api/data_types/additional_types/wstring>`, `CFStringRef</api/data_types/additional_types/cfstringref>`, or `PString</api/data_types/additional_types/pstring>`.

You can use the `WString</api/data_types/additional_types/wstring>` and `CFStringRef</api/data_types/additional_types/cfstringref>` types with declares that need a `wchar_t *` or `CFStringRef</api/data_types/additional_types/cfstringref>`, respectively. Their usage is the same as with `CString</api/data_types/additional_types/cstring>`, and all data is cleaned up when appropriate. For example:

``` xojo
Declare Sub Foo Lib "Bar" (utf16Str As WString)
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### macOS and iOS

On macOS and iOS you <span class="title-ref">Declare</span> into Objective-C library calls using the Selector part of the <span class="title-ref">Declare</span> command.

On macOS, the libraryname is automatically expanded to the full path of the library. For example, `CoreMIDI` would expand to `/System/Library/Frameworks/CoreMIDI.framework/CoreMIDI`.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Soft Declares

Soft <span class="title-ref">Declare</span> statements are resolved at runtime only when your application tries to use the <span class="title-ref">Declare</span>.

In most cases, you should use a Soft <span class="title-ref">Declare</span> in order to prevent your app from failing to launch due to missing libraries or library functions.

For example rather than creating a <span class="title-ref">Declare</span> to a specific version of LibC (on Linux) like this:

``` xojo
Declare Function getpid Lib "libc-2.3.2.so" () As Integer
```

You can instead use a soft <span class="title-ref">Declare</span> and allow it to resolve to the appropriate version at runtime:

``` xojo
Soft Declare Function getpid Lib "libc" () As Integer
```

By default, all declares used in projects that target macOS or iOS are *soft* even if you do not specify the Soft keyword.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Checking function availability

To check whether a function can be resolved, you can use the `System.IsFunctionAvailable<system.isfunctionavailable>` function of the `System</api/os/system>` module. It determines whether a function can be resolved without having to actually <span class="title-ref">Declare</span> it and try to call into it. However, this only works for real functions.

With macOS, Cocoa objects communicate through messages (i.e. selectors) but, as objects are defined at runtime, there is no predefined function to check against, so System.IsFunctionAvailable will fail. However, you can check whether a class or an object can respond to a given selector with the following functions:

- class_respondsToSelector to check if a class accepts a given selector (a shared method in Xojo's terminology).
- \[NSObject respondsToSelector:\] to check if an NSObject can handle the given selector.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Alias names

You can use the Alias keyword when you want to refer to the method by a different name:

``` xojo
Declare Function GetProcessID Lib "libc" Alias "getpid" As Integer
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Limitations

Xojo declares don't officially support variadic functions, although they may work on i386 because the calling convention happens to match up.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Namespace and library lookup information

<span class="title-ref">Declare</span> libraries are baked into the Mach-O binaries as LC_LOAD_DYLIB load commands. These commands contain a path for the dylib, a current version, and a compatibility version. Some frameworks in the system use these versions to detect which version of the Xcode SDK you linked with and provide different behavior. When a library name is found these are the steps for expanding the library name into a path:

- If the name contains a slash, the name is used as-is.
- If the name does not contain a slash and it ends with ".dylib", the name is used as-is.
- If the name does not contain a slash and it ends with ".framework", it is treated as a framework name. For the name "AppKit.framework", it would expand it to "/System/Library/Frameworks/AppKit.framework/AppKit".
- If none of the conditions above are met, the name is treated as a framework name. For the name "AppKit", it would expand to "/System/Library/Frameworks/AppKit.framework/AppKit".

## Compatibility

|                       |     |
|-----------------------|-----|
| **Project Types**     | All |
| **Operating Systems** | All |

<div class="seealso">

- `TargetLinux</api/compiler_directives/targetlinux>`, `TargetMacOS</api/compiler_directives/targetmacos>`, `TargetMachO</api/compiler_directives/targetmacho>`, `TargetWindows</api/compiler_directives/targetwindows>` constants; `System.IsFunctionAvailable<system.isfunctionavailable>` method, `FunctionNotFound</api/exceptions/functionnotfoundexception>` exception; `Byte</api/data_types/additional_types/byte>`, `CFStringRef</api/data_types/additional_types/cfstringref>`, `CString</api/data_types/additional_types/cstring>`, `ObjCException</api/exceptions/objcexception>`, `OSType</api/data_types/additional_types/ostype>`, `PString</api/data_types/additional_types/pstring>`, `Ptr</api/data_types/additional_types/ptr>`, `Int16</api/data_types/additional_types/int16>`, `DesktopWindow.Handle<desktopwindow.handle>`, `WString</api/data_types/additional_types/wstring>` data types.
- `Calling Native Linux APIs</topics/declares/calling_native_linux_apis>`, `Calling Native macOS APIs</topics/declares/calling_native_macos_apis>`, `Calling Native Windows APIs</topics/declares/calling_native_windows_apis>`, `Calling Native iOS APIs</topics/declares/calling_native_ios_apis>` topics

</div>