With this proposal VLCKit will provide a new mechanism to configure events dispatch.

Any configuration can be provided with the use of the introduction of the `VLCEventsConfiguring` protocol:
```objectivec
@protocol VLCEventsConfiguring <NSObject>

- (dispatch_queue_t _Nullable) dispatchQueue;
- (BOOL) isAsync;

@end
```
Any configuration can be set globally with `+[VLCLibrary sharedEventsConfiguration]`.

`VLCEventsDefaultConfiguration` is set when `VLCLibrary` class loads at runtime.

```objectivec
@implementation VLCEventsDefaultConfiguration

- (dispatch_queue_t _Nullable)dispatchQueue {
    return nil;
}

- (BOOL)isAsync {
    return NO;
}

@end
```
The above implementation tells the events to be dispatched synchronously from any callback's calling threads.

Another `VLCEventsLegacyConfiguration` is available if any client needs to use the former events dispatching mechanism.

```objectivec
@implementation VLCEventsLegacyConfiguration

- (dispatch_queue_t _Nullable)dispatchQueue {
    return dispatch_get_main_queue();
}

- (BOOL)isAsync {
    return YES;
}

@end
```
The above implementation tells the events to be dispatched asynchronously on the global main thread's queue.
This one would be of great help when we would like to migrate to VLCKit 4 when we're already using VLCKit 3.

The configuration will be used in `-[VLCEventsHandler handleEvent:]` implementation :

```objectivec
- (void)handleEvent:(void (^)(id))handle {
    ///[truncated]
    dispatch_block_t block = ^{handle(object);};
    if (_configuration.dispatchQueue) {
        if (_configuration.isAsync)
            dispatch_async(_configuration.dispatchQueue, block);
        else
            dispatch_sync(_configuration.dispatchQueue, block);
    } else {
        block();
    }
    ///[truncated]
}
```

Internally, libvlc sends events using the internal function `libvlc_event_send` on a `libvlc_event_manager_t` reference.
An iteration over an array of listeners created with `libvlc_event_attach` on the `libvlc_event_manager_t` is performed while a `libvlc_event_manager_t::lock mutex` is locked.
VLCKit objects attach themselves to various events on their initialisation phase.
VLCKit objects detach themselves from those events once the VLCKit object references count reach 0 and deallocation phase is triggered.
`libvlc_event_manager_t::lock mutex` is also locked when `libvlc_event_detach` is called.
This means detaching events always waits for any currently performed callback event.

---

An event callback implementation in VLCKit can actually be illustrated like this :

```objectivec
static void AnyEventCallback(const libvlc_event_t * event, void* opaque) {
    @autoreleasepool {
        VLCKitObject *obj = (__bridge VLCKitObject *)opaque;
        dispatch_async(dispatch_get_main_queue(), ^{
            [obj doSomething];
        });
    }
}
```

But considering at the same time :
- `VLCKitObject *obj` can be either in an allocated or deallocating state when bridge assignement is performed by `VLCKitObject *obj = (__bridge VLCKitObject *)opaque`
- `VLCKitObject *obj` refcount can reach 0 from any other thread hence it's deallocation can be initiated from any other thread
- `VLCKitObject *obj` reference is used asynchronously on main thread to send a `doSomething` message but `VLCKitObject *obj` can be in a deallocating state

So here we’re facing a situation where an `EXC_BAD_ACCESS` would happen once an attempt to perform any `(__bridge MyObject *)opaque` or send message on `VLCKitObject *obj` is done when it becomes an object in a deallocated/deallocating state.

We can then be tempted to try this strategy :

```objectivec
static void AnyEventCallback(const libvlc_event_t * event, void* opaque) {
    @autoreleasepool {
        __weak VLCKitObject *weak_obj = (__bridge VLCKitObject *)opaque;
        dispatch_async(dispatch_get_main_queue(), ^{
            __strong VLCKitObject *strong_obj = weak_obj;
            [strong_obj doSomething];
        });
    }
}
```

But once we run this, a `SIGABRT` would reach us with :
```
objc[10281]: Cannot form weak reference to instance (0x28266b040) of class VLCKitObject. It is possible that this object was over-released, or is in the process of deallocation.
```

So the idea of this patch is to provide a new mechanism to handle the events where `_bridge` cast of `void *opaque` never lead to an `EXC_BAD_ACCESS`.

By the way, another situation have to be considered.

To prevent this `EXC_BAD_ACCESS` issue, we have to prevent the `VLCKitObject *obj` to enter in a deallocating state from another thread.
The only option to achieve that is to find a way to keep a strong reference to the `VLCKitObject *obj` while we're using it in the event's callback's scope.
Hence given we enter a callback and the `VLCKitObject *obj` is still allocated, it makes sense that it would be possible that a deallocation will be triggered from the callback's calling thread.

Here's a reminder of the new problem we would get:
- A `VLCKitObject*`, if not nil when assigned in a callback, will have to be strongly referenced to not be deallocated from another thread, hence it will be deallocated from the callback's calling thread if the refcount reaches 0 when going out of it's scope
- A `-[VLCKitObject dealloc]` call will trigger `libvlc_event_detach`
- Given a callback is called, the `libvlc_event_manager_t::lock mutex` is locked
- Given an event is detached with `libvlc_event_detach`, the `libvlc_event_manager_t::lock mutex` is locked

It means in the callback calling thread we would potentially get this kind of call stack :
`lock(mutex)` => `AnyEventCallback` => `-[VLCKitObject dealloc]` => `libvlc_event_detach` => `lock(mutex)`

A recursive deadlock issue would be introduced if we keep a strong reference of a `VLCKitObject*` and allow its deallocation from any callback's calling thread.

---

The introduction of the new `VLCEventsHandler` object should perform a proper memory management which would help to to prevent any previously enumerated corner cases.

Any VLCKit object that observe libvlc events owns a strong reference to his `VLCEventsHandler` object and use it as a replacement for any callback user data, hence it's deallocated after all event callbacks are detached from vlc objects.

This is how VLCKit object reference memory management is handled :

```objectivec
@interface VLCEventsHandler : NSObject
///[truncated]
@property (nonatomic, readonly, weak) id _Nullable object;
///[truncated]
@end
```

```objectivec
@implementation VLCEventsHandler {
///[truncated]
    /// Queue used to release asynchronously the retained object
    dispatch_queue_t _releaseQueue;
}
///[truncated]
- (void)handleEvent:(void (^)(id))handle {
    __block id object = _object; // We keep a strong reference and make it mutable in a block
    if (!object) { // We check if already deallocated
        return; // Object seems already deallocated, no need to handle the event
    }
    ///[truncated]
    dispatch_async(_releaseQueue, ^{
        object = nil; // We decrease object refcount in another thread, potentially triggering a deallocation if refcount reaches 0
    });
}
///[truncated]
@end
```

In the above code any `VLCEventsHandler` weakly references its related VLCKit object and pass it, if not nil, as strong reference to the block parameter in any `-[VLCEventsHandler handleEvent:]` call.
The `VLCEventsHandler` uses an internal queue to release the VLCKit object strong reference asynchronously, which helps to prevent the `libvlc_event_manager_t` mutex deadlock given a deallocation would happen on any callback calling thread.

Set the media player's media when the playItemAtNumber method is
called.

Closes #669

Previously, we returned only the minutes and seconds for anything
longer than an hour in subsecond mode and '00:00' as string value if
the time matches exactly one hour.

This also removes 3 patches that are no longer needed.

When the player is changing state, the delegate doesn't care about
receiving an NSNotification or knowing from which player it was
triggered, but it will need to know the new state from the player.

It prevents calling libvlc methods from the callback, which is usually
forbidden and works only because of the dispatch_async.

The event signalling a change of media length is not a state change and
should be reported separately with the correct metadata.

Add mediaPlayerTrackSelected API to signal changes reported from the
libvlc_media_player_t object. For now, it mimics the API, by just
transforming raw char strings into NSString, but it should be improved
to report VLCMediaTrack instead.

The blocker for reporting VLCMediaTrack is that libvlc_media_track_t are
not reported by the media player as events currently, so it's not
possible to get a matching libvlc object, which makes it impossible to
get the matching VLCKit object without duplicating them.

Add mediaPlayerTrackAdded/Updated/Removed API to signal changes reported
from the libvlc_media_player_t object. For now, it mimics the API, by
just transforming raw char strings into NSString, but it should be
improved to report VLCMediaTrack instead.

The blocker for reporting VLCMediaTrack is that libvlc_media_track_t are
not reported by the media player as events currently, so it's not
possible to get a matching libvlc object, which makes it impossible to
get the matching VLCKit object without duplicating them.

Soomin Lee authored 2 years ago and Alexandre Janniaux committed 2 years ago

ESAdded/Delete are not VLCMediaPlayer states.

Alexandre Janniaux authored 2 years ago and Felix Paul Kühne committed 2 years ago

`parseWithOptions` is provided through multiple selectors allowing
default values to be provided in most cases. Refactor the documentation
so that the specialized variants are referencing the more general
variant and document the most general one.

Alexandre Janniaux authored 2 years ago and Felix Paul Kühne committed 2 years ago

Expand the usual macro found in Objective-C to ensure doxygen can parse
the types correctly:

 - NS_OPTIONS() and NS_ENUM types are correctly parsed and referenced by
   doxygen, so the \see <an_enum_type> is now creating a reference link.

 - NS_SWIFT_NAME() is not clobbering the doxygen reference anymore.

Alexandre Janniaux authored 2 years ago and Felix Paul Kühne committed 2 years ago

A libvlc_event_attach call must have a matching libvlc_event_detach call
to ensure that the event is removed, otherwise libvlc will assert when
destroying the object.

Having the attach/detach being in two different location can mask that
they should be removed when adding a new handler for a new event, so it
makes sense to gather everything in a single table like done in the
commit 9db4f9c5.

Alexandre Janniaux authored 2 years ago and Felix Paul Kühne committed 2 years ago

Ensure that we have a fully initialized object after [VLCMedia init*]
function returned. It allows to remove every location defensively
checking whether p_md was assigned or not.

Alexandre Janniaux authored 2 years ago and Felix Paul Kühne committed 2 years ago

This reduces the number of indentation needed to every initialization
locations. The [super init] must be called to initialized the object
correctly and is documented as returning nil in case the initialization
failed.

Alexandre Janniaux authored 2 years ago and Felix Paul Kühne committed 2 years ago

Now that preparsing doesn't depend on a library assigned to the VLCMedia
object but directly from the libvlc_instance_t used, the user might want
to alter the parameters by providing their own VLCLibrary object, until
a better API is made for VLCKit.

Alexandre Janniaux authored 2 years ago and Felix Paul Kühne committed 2 years ago

Refactor in VLC 4.0 removed the libvlc_instance_t parameter to most
functions from libvlc_media_t (in particular constructor) and only kept
it for preparsing/thumbnailing requests.

Alexandre Janniaux authored 2 years ago and Felix Paul Kühne committed 2 years ago

VLC 4.0 now has an inhibiter module for UIKit and doesn't need the
idleTimer control. In addition, the control was using libVLC methods
from the callback, enforcing dispatch_async to be used.

test works correctly when quoting the strings already.

Fix the build when -a is used to select an arch that is not buildable
on either simulator or device, but available on the other, which led
lipo to complain that no files were given as input.

Since the previous archives are removed, and probed, it doesn't impact
the generation of the framework.

Example: ./compileAndBuildVLCKit.sh -ftnva aarch64

Refactor the checks to create the lipo-ed build for each target from
each target/arch couple behind a single function. Because of the
discrepancy between VLCKit buildsystem (expecting ${os_style}-simulator-
or ${os_style}-device- prefix) and the way VLC defines the target (which
is directly ${os_style}simulator or ${os_style}os) and the additional
discrepancy against macosx (which is not -os suffixed), some additional
code is made to make them match correctly by checking whether we run in
simulator or for device.