shared_library.h

Go to the documentation of this file.

// Copyright 2020 Open Source Robotics Foundation, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
 
#ifndef RCUTILS__SHARED_LIBRARY_H_
#define RCUTILS__SHARED_LIBRARY_H_
 
#ifdef __cplusplus
extern "C"
{
#endif
 
#include <string.h>
 
#include "rcutils/allocator.h"
#include "rcutils/types/rcutils_ret.h"
#include "rcutils/macros.h"
#include "rcutils/visibility_control.h"
 
typedef struct RCUTILS_PUBLIC_TYPE rcutils_shared_library_t
{
  void * lib_pointer;
  char * library_path;
  rcutils_allocator_t allocator;
} rcutils_shared_library_t;
 
/*
 * This function returns an empty and zero initialized shared library struct.
 *
 * Example:
 *
 * ```c
 * // Do not do this:
 * // rcutils_shared_library_t foo;
 * // rcutils_ret_t ret = rcutils_load_shared_library(
 * //     &foo,
 * //    "library_name",
 * //    rcutils_get_default_allocator()); // undefined behavior!
 * // or
 * // rcutils_ret_t ret = rcutils_unload_shared_library(&foo); // undefined behavior!
 *
 * // Do this instead:
 * rcutils_shared_library_t bar = rcutils_get_zero_initialized_shared_library();
 * rcutils_load_shared_library(&bar, "library_name", rcutils_get_default_allocator()); // ok
 * void * symbol = rcutils_get_symbol(&bar, "bazinga"); // ok
 * bool is_bazinga_symbol = rcutils_has_symbol(&bar, "bazinga"); // ok
 * rcutils_ret_t ret = rcutils_unload_shared_library(&bar); // ok
 * if (ret != RCUTILS_RET_ERROR) {
 *   // error handling
 * }
 * ```
 * */
RCUTILS_PUBLIC
RCUTILS_WARN_UNUSED
rcutils_shared_library_t
rcutils_get_zero_initialized_shared_library(void);
 
 
RCUTILS_PUBLIC
RCUTILS_WARN_UNUSED
rcutils_ret_t
rcutils_load_shared_library(
  rcutils_shared_library_t * lib,
  const char * library_path,
  rcutils_allocator_t allocator);
 
 
RCUTILS_PUBLIC
RCUTILS_WARN_UNUSED
void *
rcutils_get_symbol(const rcutils_shared_library_t * lib, const char * symbol_name);
 
 
RCUTILS_PUBLIC
RCUTILS_WARN_UNUSED
bool
rcutils_has_symbol(const rcutils_shared_library_t * lib, const char * symbol_name);
 
 
RCUTILS_PUBLIC
RCUTILS_WARN_UNUSED
rcutils_ret_t
rcutils_unload_shared_library(rcutils_shared_library_t * lib);
 
 
RCUTILS_PUBLIC
RCUTILS_WARN_UNUSED
bool
rcutils_is_shared_library_loaded(rcutils_shared_library_t * lib);
 
 
RCUTILS_PUBLIC
RCUTILS_WARN_UNUSED
rcutils_ret_t
rcutils_get_platform_library_name(
  const char * library_name,
  char * library_name_platform,
  unsigned int buffer_size,
  bool debug);
 
#ifdef __cplusplus
}
#endif
 
#endif  // RCUTILS__SHARED_LIBRARY_H_