sergey_norseev / com_ports
CI/CD
Реестр контейнеров и пакетов
Сергей Норсеев
Add automatic linking with setupapi
3 недели назад История
README.md

com_ports

Библиотека для работы со списком доступных COM портов. Позволяет получать список доступных COM портов и их дружелюбные (friendly) имена.

Библиотека написана на языке C++ (минимально поддерживаемая версия стандарта C++17) с использованием Windows API.

Операционная система: Windows

Зависимости: setupapi

Лицензия: MIT

Файлы и каталоги

Корневой каталог проекта библиотеки содержит следующие файлы и подкаталоги.

  • cmake/ содержит вспомогательные файлы для конфигурирования и установки библиотеки средствами CMake.
  • doc/ содержит файлы документации к библиотеке в формате reStructuredText. Для её конвертирования в другой формат (например, html) Вам нужен Sphinx.
  • examples/ содержит исходные тексты примеров приложений, использующих библиотеку.
  • include/ содержит заготовку заголовочного файла, который должен использоваться при работе с библиотекой. Обращаю Ваше внимание что это всего лишь заготовка. Полноценный заголовочный файл (com_ports.hpp) формируется при конфигурировании средствами CMake и будет находиться в каталоге сборки.
  • src/ содержит исходные тексты библиотеки на языке C++.
  • CMakeLists.txt файл конфигурации библиотеки для её сборки средствами CMake.
  • LICENSE текст лицензии MIT.
  • LICENSE_RUS неофициальный перевод текста лицензии из файла LICENSE на русский язык.
  • README.md файл README с кратким описанием библиотеки в формате Markdown.

Сборка и установка библиотеки

Сборка и установка библиотеки осуществляется посредством CMake. Библиотека предоставляет следующие опции сборки.

  • COM_PORTS_BUILD_EXAMPLES - нужно ли собирать примеры работы с библиотекой. По умолчанию они не собираются. Примеры находятся в каталоге examples.
  • COM_PORTS_DOCUMENTATION - нужно ли создать цель docs для сборки документации. По умолчанию цель docs не создаётся.
  • COM_PORTS_INSTALL - нужно ли создать цель install для установки библиотеки. По умолчанию цель install не создаётся.

Пример сборки библиотеки

Библиотека собирается только как статическая библиотека с одним заголовочным файлом com_ports.hpp.

Для сборки библиотеки перейдите в каталог, содержащий файл CMakeLists.txt.

Выполните в терминале команды вида

cmake -S . -B build -DCOM_PORTS_BUILD_EXAMPLES=ON -DCOM_PORTS_DOCUMENTATION=ON -DCOM_PORTS_INSTALL=ON
cmake --build build
cmake --build build --target docs
cmake --build build --target install

⚠️ Для успешной сборки документации у Вас должен быть установлен Sphinx.

Экспортируемые имена

Все экспортируемые библиотекой типы данных и функции находятся в пространстве имён com_ports.

Макросы

Библиотека экпортирует следующие макросы:

  • COM_PORTS_VERSION_MAJOR определяет старший номер версии библиотеки.
  • COM_PORTS_VERSION_MINOR определяет младший номер версии библиотеки.
  • COM_PORTS_VERSION_PATCH определяет номер фикса.
  • COM_PORTS_VERSION_TAG определяет тег версии (может быть пустым).
  • COM_PORTS_FULL_VERSION определяет полную версию библиотеки. Полная версия включает в себя старший и младший номера, номер фикса и тег. Тег (если он не пустой) отделяется дефисом.
  • COM_PORTS_FULL_VERSION_NUMBER формирует полный числовой номер версии библиотеки. Он включает в себя старший и младший номера версии, а также номер фикса. Более новые версии библиотеки имеют бОльшее значение полного номера версии.

Типы данных

Библиотека экспортирует следующие типы данных:

  • com_ports::Names коллекция строк в кодировке Unicode (UTF-16). В текущей реализации псевдоним для std::vector<std::wstring>
  • com_ports::NamesANSI коллекция строк в произвольной однобайтовой кодировке или в кодировке UTF-8. В текущей реализации псевдоним для std::vector<std::string>
  • com_ports::Exception класс исключения, которое бросается функциями библиотеки в том случае, если та или иная функция Windows API завершилась ошибкой. Является потомком класса std::exception. Текст описания ошибки возвращается в кодировке UTF-8.

Функции

Все функции, имеющие суффикс _ansi, возвращают коллекцию строк в заданной однобайтовой кодировке (или в UTF-8). Требуемая кодировка передается единственным параметром. Если параметр не задан, используется кодировка Win1251.

Все функции, не имеющие суффикса _ansi, возвращают коллекцию строк в Unicode (UTF-16).

Names get_friendly_names();
NamesANSI get_friendly_names_ansi(unsigned int = 1251);

Возвращает коллекцию дружелюбных имён (как в Диспетчере устройств) доступных COM портов. Например, ["SerialTool - Virtual COM Port VCPA0 (COM3)"].

Names get_names();
NamesANSI get_names_ansi(unsigned int = 1251);

Возвращает коллекцию имён доступных COM портов. Например, ["COM1","COM2"].

Names get_names_with_prefix();
NamesANSI get_names_with_prefix_ansi(unsigned int = 1251);

Возвращает коллекцию имён доступных COM портов, содержащих префикс \\?\\. Например, ["\\?\\COM3", "\\?\\COM4"].

inline std::wstring get_prefix();
inline std::string get_prefix_ansi();

Возвращает сам префикс \\?\\.

Использование библиотеки

Сборка приложения, использующего библиотеку

Если библиотека com_ports установлена в систему, то при использовании CMake Вам нужно прописать примерно такие команды (в файле CMakeLists Вашего проекта)

find_package(com_ports 1.0.0 REQUIRED)
target_link_libraries(YOUR_PROJECT com_ports::com_ports)
target_link_libraries(YOUR_PROJECT setupapi)

Если библиотека com_ports установлена по нестандартному пути, то, возможно Вам стоит использовать переменную CMAKE_PREFIX_PATH для указания каталога, в который была установлена библиотека.

Если Вы используете что-то похожее на Make, команда сборки будет примерно такой

g++ main.cpp -I<path_to_com_ports.hpp> -L<path_to_com_ports.lib> -lcom_ports -lsetupapi

Если же Вы используете какую-то другую систему сборки, то сверяйтесь с её документацией.

Пример 1. Макросы версии

Ниже приводится пример использования макросов библиотеки.

#include <com_ports/com_ports.hpp>

#include <iostream>

int main()
{
    ::std::cout
        << "major version: " << COM_PORTS_VERSION_MAJOR << '\n'
        << "minor version: " << COM_PORTS_VERSION_MINOR << '\n'
        << "patch: " << COM_PORTS_VERSION_PATCH << '\n'
        << "version tag: " << COM_PORTS_VERSION_TAG << '\n'
        << "full version: " << COM_PORTS_FULL_VERSION << '\n'
        << "full version number: " << COM_PORTS_FULL_VERSION_NUMBER
        << ::std::endl;

    return 0;
}

Возможный вывод программы:

major version: 1
minor version: 0
patch: 0
version tag: dev
full version: 1.0.0-dev
full version number: 1000000

Пример 2. Имена COM портов

Ниже приводится пример использования основных функций библиотеки.

#include <com_ports/com_ports.hpp>

#include <iostream>

#include <windows.h>

int main()
{
    try
    {
        ::std::wcout << L"COM ports:\n";

        auto names = com_ports::get_names();

        for(const auto &name : names)
            ::std::wcout << name << L'\n';

        ::std::wcout << L"\nCOM ports with prefix:\n";

        auto names_with_prefix = com_ports::get_names_with_prefix();

        for(const auto &name : names_with_prefix)
            ::std::wcout << name << L'\n';

        ::std::wcout << L"\nFriendly names:\n";

        auto friendly_names = com_ports::get_friendly_names();

        for(const auto &name : friendly_names)
            ::std::wcout << name << L'\n';
    }
    catch(const ::std::exception &e)
    {
        auto prev_cp = ::GetConsoleOutputCP();
        ::SetConsoleOutputCP(CP_UTF8);

        ::std::cout << e.what() << '\n';

        ::SetConsoleOutputCP(prev_cp);
    }

    return 0;
}

Возможный вывод этой программы.

COM ports:
COM3
COM4

COM ports with prefix:
\\?\\COM3
\\?\\COM4

Friendly names:
SerialTool - Virtual COM Port VCPA0 (COM3)
SerialTool - Virtual COM Port VCPB0 (COM4)

Обратная связь

Если Вам понравилась эта библиотека, у Вас появились вопросы, идеи и предложения по её улучшению, Вы можете связаться со мной через форму обратной связи на моём сайте.

Также Вы можете присылать PRы посредством текущего сайта.

Описание
Readme
0 Форки
0 Звезд
0 Наблюдатели
Посмотреть файловое дерево
Конвейеры
0 успешных
0 с ошибкой
Разработчики