Приложения

Приложение А. Функции, константы и структуры RDS

А.5. Сервисные функции и макросы RDS

А.5.6. Операции с блоками и связями

А.5.6.39. rdsMakeUniqueBlockName – создать уникальное имя блока

Функция rdsMakeUniqueBlockName возвращает динамическую строку, содержащую имя блока, которое будет уникальным в указанной подсистеме. Имя формируется на основе переданной в параметрах строки.

  RDSSTR RDSCALL rdsMakeUniqueBlockNameA( // UTF8
    RDS_BHANDLE System, // Подсистема
    RDSCSTR Name        // Желаемое имя блока (UTF8)
  );
  RDSWSTR RDSCALL rdsMakeUniqueBlockNameW( // UTF16
    RDS_BHANDLE System, // Подсистема
    RDSWCSTR Name       // Желаемое имя блока (UTF16)
  );
  // Функция-псевдоним
  RDSXSTR RDSCALL rdsMakeUniqueBlockName( // Кодировка по умолчанию
    RDS_BHANDLE System, // Подсистема
    RDSXCSTR Name       // Желаемое имя блока (кодировка по умолчанию)
  );

Тип указателя на эту функцию

RDS_SBhS (для UTF8) или RDS_WsBhWs (для UTF16)

Параметры

System (RDS_BHANDLE): Идентификатор подсистемы, для которой нужно создать уникальное имя блока.
Name (RDSCSTR, RDSWCSTR, RDSXCSTR): Указатель на строку (char* или wchar_t*, в зависимости от версии функции) с желаемым именем блока. Если передать в этом параметре NULL, будет сформировано имя вида «BlockN», где N – некоторый номер.

Возвращаемое значение

Указатель на созданную в динамической памяти строку, содержащую созданное уникальное (то есть не встречающееся в подсистеме System) имя блока, или NULL, если System – не подсистема, а блок какого-либо другого типа.

Примечания

Уникальное имя блока формируется из строки Name следующим образом: если в подсистеме System нет блока с именем Name, возвращается динамическая копия строки Name. Если блок с таким именем есть, то цифры в конце строки Name изменяются так, чтобы получившееся имя стало уникальным в подсистеме (например, если в подсистеме есть блоки с именами «Mul1» – «Mul64», а в параметре Name передана строка «Mul1», функция вернет «Mul65»). Если строка Name не оканчивается на цифры, к ней будет добавлен номер, делающий ее уникальной (номера начинаются с единицы). Точно таким же образом RDS корректирует имена вставляемых из буфера обмена или из библиотеки блоков, если их имена совпадают с уже имеющимися в подсистеме.

Динамическая строка, созданная этой функцией, должна быть обязательно освобождена вызовом rdsFree.

Пример

Пример использования функции rdsMakeUniqueBlockName приведен в §2.16.2 руководства программиста.

См. также

rdsFree, rdsGetChildBlockByName, rdsDuplicateBlock.