api_handler_editor.cpp

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2024 Jon Evans <[email protected]>
 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation, either version 3 of the License, or (at your
 * option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
#include <api/api_handler_editor.h>
 
#include <api/api_enums.h>
#include <api/api_utils.h>
#include <eda_base_frame.h>
#include <eda_item.h>
#include <title_block.h>
#include <wx/wx.h>
 
using namespace kiapi::common::commands;
 
 
API_HANDLER_EDITOR::API_HANDLER_EDITOR( EDA_BASE_FRAME* aFrame ) :
        API_HANDLER(),
        m_frame( aFrame )
{
    registerHandler<BeginCommit, BeginCommitResponse>( &API_HANDLER_EDITOR::handleBeginCommit );
    registerHandler<EndCommit, EndCommitResponse>( &API_HANDLER_EDITOR::handleEndCommit );
    registerHandler<CreateItems, CreateItemsResponse>( &API_HANDLER_EDITOR::handleCreateItems );
    registerHandler<UpdateItems, UpdateItemsResponse>( &API_HANDLER_EDITOR::handleUpdateItems );
    registerHandler<DeleteItems, DeleteItemsResponse>( &API_HANDLER_EDITOR::handleDeleteItems );
    registerHandler<HitTest, HitTestResponse>( &API_HANDLER_EDITOR::handleHitTest );
    registerHandler<GetTitleBlockInfo, types::TitleBlockInfo>( &API_HANDLER_EDITOR::handleGetTitleBlockInfo );
    registerHandler<SetTitleBlockInfo, google::protobuf::Empty>( &API_HANDLER_EDITOR::handleSetTitleBlockInfo );
}
 
 
HANDLER_RESULT<BeginCommitResponse> API_HANDLER_EDITOR::handleBeginCommit(
        const HANDLER_CONTEXT<BeginCommit>& aCtx )
{
    if( std::optional<ApiResponseStatus> busy = checkForBusy() )
        return tl::unexpected( *busy );
 
    // Before 11.0, commit requests had no header so we assume they are for the PCB editor
    if( aCtx.Request.has_header() && !validateItemHeaderDocument( aCtx.Request.header() ) )
    {
        ApiResponseStatus e;
        // No message needed for AS_UNHANDLED; this is an internal flag for the API server
        e.set_status( ApiStatusCode::AS_UNHANDLED );
        return tl::unexpected( e );
    }
 
    if( m_commits.count( aCtx.ClientName ) )
    {
        ApiResponseStatus e;
        e.set_status( ApiStatusCode::AS_BAD_REQUEST );
        e.set_error_message( fmt::format( "the client {} already has a commit in progress",
                                          aCtx.ClientName ) );
        return tl::unexpected( e );
    }
 
    wxASSERT( !m_activeClients.count( aCtx.ClientName ) );
 
    BeginCommitResponse response;
 
    KIID id;
    m_commits[aCtx.ClientName] = std::make_pair( id, createCommit() );
    response.mutable_id()->set_value( id.AsStdString() );
 
    m_activeClients.insert( aCtx.ClientName );
 
    return response;
}
 
 
HANDLER_RESULT<EndCommitResponse> API_HANDLER_EDITOR::handleEndCommit(
        const HANDLER_CONTEXT<EndCommit>& aCtx )
{
    if( std::optional<ApiResponseStatus> busy = checkForBusy() )
        return tl::unexpected( *busy );
 
    // Before 11.0, commit requests had no header so we assume they are for the PCB editor
    if( aCtx.Request.has_header() && !validateItemHeaderDocument( aCtx.Request.header() ) )
    {
        ApiResponseStatus e;
        // No message needed for AS_UNHANDLED; this is an internal flag for the API server
        e.set_status( ApiStatusCode::AS_UNHANDLED );
        return tl::unexpected( e );
    }
 
    if( !m_commits.count( aCtx.ClientName ) )
    {
        ApiResponseStatus e;
        e.set_status( ApiStatusCode::AS_BAD_REQUEST );
        e.set_error_message( fmt::format( "the client {} does not has a commit in progress",
                                          aCtx.ClientName ) );
        return tl::unexpected( e );
    }
 
    wxASSERT( m_activeClients.count( aCtx.ClientName ) );
 
    const std::pair<KIID, std::unique_ptr<COMMIT>>& pair = m_commits.at( aCtx.ClientName );
    const KIID& id = pair.first;
    const std::unique_ptr<COMMIT>& commit = pair.second;
 
    EndCommitResponse response;
 
    // Do not check IDs with drop; it is a safety net in case the id was lost on the client side
    switch( aCtx.Request.action() )
    {
    case kiapi::common::commands::CMA_DROP:
    {
        commit->Revert();
        m_commits.erase( aCtx.ClientName );
        m_activeClients.erase( aCtx.ClientName );
        break;
    }
 
    case kiapi::common::commands::CMA_COMMIT:
    {
        if( aCtx.Request.id().value().compare( id.AsStdString() ) != 0 )
        {
            ApiResponseStatus e;
            e.set_status( ApiStatusCode::AS_BAD_REQUEST );
            e.set_error_message( fmt::format( "the id {} does not match the commit in progress",
                                              aCtx.Request.id().value() ) );
            return tl::unexpected( e );
        }
 
        pushCurrentCommit( aCtx.ClientName, wxString( aCtx.Request.message().c_str(), wxConvUTF8 ) );
        break;
    }
 
    default:
        break;
    }
 
    return response;
}
 
 
COMMIT* API_HANDLER_EDITOR::getCurrentCommit( const std::string& aClientName )
{
    if( !m_commits.count( aClientName ) )
    {
        KIID id;
        m_commits[aClientName] = std::make_pair( id, createCommit() );
    }
 
    return m_commits.at( aClientName ).second.get();
}
 
 
void API_HANDLER_EDITOR::pushCurrentCommit( const std::string& aClientName,
                                            const wxString& aMessage )
{
    auto it = m_commits.find( aClientName );
 
    if( it == m_commits.end() )
        return;
 
    it->second.second->Push( aMessage.IsEmpty() ? m_defaultCommitMessage : aMessage );
    m_commits.erase( it );
    m_activeClients.erase( aClientName );
}
 
 
HANDLER_RESULT<bool> API_HANDLER_EDITOR::validateDocument( const DocumentSpecifier& aDocument )
{
    if( !validateDocumentInternal( aDocument ) )
    {
        ApiResponseStatus e;
        e.set_status( ApiStatusCode::AS_BAD_REQUEST );
        e.set_error_message( fmt::format( "the requested document {} is not open",
                                          aDocument.board_filename() ) );
        return tl::unexpected( e );
    }
 
    return true;
}
 
 
HANDLER_RESULT<std::optional<KIID>> API_HANDLER_EDITOR::validateItemHeaderDocument(
        const types::ItemHeader& aHeader )
{
    if( !aHeader.has_document() || aHeader.document().type() != thisDocumentType() )
    {
        ApiResponseStatus e;
        e.set_status( ApiStatusCode::AS_UNHANDLED );
        // No error message, this is a flag that the server should try a different handler
        return tl::unexpected( e );
    }
 
    HANDLER_RESULT<bool> documentValidation = validateDocument( aHeader.document() );
 
    if( !documentValidation )
        return tl::unexpected( documentValidation.error() );
 
    if( tl::expected<bool, ApiResponseStatus> result = validateDocumentInternal( aHeader.document() ); !result )
        return tl::unexpected( result.error() );
 
    if( aHeader.has_container() )
    {
        return KIID( aHeader.container().value() );
    }
 
    // Valid header, but no container provided
    return std::nullopt;
}
 
 
std::optional<ApiResponseStatus> API_HANDLER_EDITOR::checkForBusy()
{
    if( !m_frame )
        return std::nullopt;
 
    if( !m_frame->CanAcceptApiCommands() )
    {
        ApiResponseStatus e;
        e.set_status( ApiStatusCode::AS_BUSY );
        e.set_error_message( "KiCad is busy and cannot respond to API requests right now" );
        return e;
    }
 
    return std::nullopt;
}
 
 
HANDLER_RESULT<CreateItemsResponse> API_HANDLER_EDITOR::handleCreateItems(
        const HANDLER_CONTEXT<CreateItems>& aCtx )
{
    if( std::optional<ApiResponseStatus> busy = checkForBusy() )
        return tl::unexpected( *busy );
 
    CreateItemsResponse response;
 
    HANDLER_RESULT<ItemRequestStatus> result = handleCreateUpdateItemsInternal( true,
            aCtx.ClientName,
            aCtx.Request.header(), aCtx.Request.items(),
            [&]( const ItemStatus& aStatus, const google::protobuf::Any& aItem )
            {
                ItemCreationResult itemResult;
                itemResult.mutable_status()->CopyFrom( aStatus );
                itemResult.mutable_item()->CopyFrom( aItem );
                response.mutable_created_items()->Add( std::move( itemResult ) );
            } );
 
    if( !result.has_value() )
        return tl::unexpected( result.error() );
 
    response.set_status( *result );
    return response;
}
 
 
HANDLER_RESULT<UpdateItemsResponse> API_HANDLER_EDITOR::handleUpdateItems(
        const HANDLER_CONTEXT<UpdateItems>& aCtx )
{
    if( std::optional<ApiResponseStatus> busy = checkForBusy() )
        return tl::unexpected( *busy );
 
    UpdateItemsResponse response;
 
    HANDLER_RESULT<ItemRequestStatus> result = handleCreateUpdateItemsInternal( false,
            aCtx.ClientName,
            aCtx.Request.header(), aCtx.Request.items(),
            [&]( const ItemStatus& aStatus, const google::protobuf::Any& aItem )
            {
                ItemUpdateResult itemResult;
                itemResult.mutable_status()->CopyFrom( aStatus );
                itemResult.mutable_item()->CopyFrom( aItem );
                response.mutable_updated_items()->Add( std::move( itemResult ) );
            } );
 
    if( !result.has_value() )
        return tl::unexpected( result.error() );
 
    response.set_status( *result );
    return response;
}
 
 
HANDLER_RESULT<DeleteItemsResponse> API_HANDLER_EDITOR::handleDeleteItems(
        const HANDLER_CONTEXT<DeleteItems>& aCtx )
{
    if( std::optional<ApiResponseStatus> busy = checkForBusy() )
        return tl::unexpected( *busy );
 
    if( !validateItemHeaderDocument( aCtx.Request.header() ) )
    {
        ApiResponseStatus e;
        // No message needed for AS_UNHANDLED; this is an internal flag for the API server
        e.set_status( ApiStatusCode::AS_UNHANDLED );
        return tl::unexpected( e );
    }
 
    std::map<KIID, ItemDeletionStatus> itemsToDelete;
 
    for( const kiapi::common::types::KIID& kiidBuf : aCtx.Request.item_ids() )
    {
        if( !kiidBuf.value().empty() )
        {
            KIID kiid( kiidBuf.value() );
            itemsToDelete[kiid] = ItemDeletionStatus::IDS_NONEXISTENT;
        }
    }
 
    if( itemsToDelete.empty() )
    {
        ApiResponseStatus e;
        e.set_status( ApiStatusCode::AS_BAD_REQUEST );
        e.set_error_message( "no valid items to delete were given" );
        return tl::unexpected( e );
    }
 
    deleteItemsInternal( itemsToDelete, aCtx.ClientName );
 
    DeleteItemsResponse response;
 
    for( const auto& [id, status] : itemsToDelete )
    {
        ItemDeletionResult result;
        result.mutable_id()->set_value( id.AsStdString() );
        result.set_status( status );
    }
 
    response.set_status( kiapi::common::types::ItemRequestStatus::IRS_OK );
    return response;
}
 
 
HANDLER_RESULT<HitTestResponse> API_HANDLER_EDITOR::handleHitTest(
        const HANDLER_CONTEXT<HitTest>& aCtx )
{
    if( std::optional<ApiResponseStatus> busy = checkForBusy() )
        return tl::unexpected( *busy );
 
    if( !validateItemHeaderDocument( aCtx.Request.header() ) )
    {
        ApiResponseStatus e;
        // No message needed for AS_UNHANDLED; this is an internal flag for the API server
        e.set_status( ApiStatusCode::AS_UNHANDLED );
        return tl::unexpected( e );
    }
 
    HitTestResponse response;
 
    std::optional<EDA_ITEM*> item = getItemFromDocument( aCtx.Request.header().document(),
                                                         KIID( aCtx.Request.id().value() ) );
 
    if( !item )
    {
        ApiResponseStatus e;
        e.set_status( ApiStatusCode::AS_BAD_REQUEST );
        e.set_error_message( "the requested item ID is not present in the given document" );
        return tl::unexpected( e );
    }
 
    const EDA_IU_SCALE& scale = getIuScale();
    VECTOR2I posIu = UnpackVector2( aCtx.Request.position(), scale );
    int toleranceIu = scale.NmToIU( aCtx.Request.tolerance() );
 
    if( ( *item )->HitTest( posIu, toleranceIu ) )
        response.set_result( HitTestResult::HTR_HIT );
    else
        response.set_result( HitTestResult::HTR_NO_HIT );
 
    return response;
}
 
 
std::vector<KICAD_T> API_HANDLER_EDITOR::parseRequestedItemTypes( const google::protobuf::RepeatedField<int>& aTypes )
{
    std::vector<KICAD_T> types;
 
    for( int typeRaw : aTypes )
    {
        auto typeMessage = static_cast<types::KiCadObjectType>( typeRaw );
 
        if( KICAD_T type = FromProtoEnum<KICAD_T>( typeMessage ); type != TYPE_NOT_INIT )
            types.emplace_back( type );
    }
 
    return types;
}
 
 
HANDLER_RESULT<types::TitleBlockInfo>
API_HANDLER_EDITOR::handleGetTitleBlockInfo( const HANDLER_CONTEXT<GetTitleBlockInfo>& aCtx )
{
    HANDLER_RESULT<bool> documentValidation = validateDocument( aCtx.Request.document() );
 
    if( !documentValidation )
        return tl::unexpected( documentValidation.error() );
 
    std::optional<TITLE_BLOCK*> optBlock = getTitleBlock();
 
    if( !optBlock )
    {
        ApiResponseStatus e;
        e.set_status( AS_BAD_REQUEST );
        e.set_error_message( "this editor does not support a title block" );
        return tl::unexpected( e );
    }
 
    TITLE_BLOCK& block = **optBlock;
 
    types::TitleBlockInfo response;
 
    response.set_title( block.GetTitle().ToUTF8() );
    response.set_date( block.GetDate().ToUTF8() );
    response.set_revision( block.GetRevision().ToUTF8() );
    response.set_company( block.GetCompany().ToUTF8() );
    response.set_comment1( block.GetComment( 0 ).ToUTF8() );
    response.set_comment2( block.GetComment( 1 ).ToUTF8() );
    response.set_comment3( block.GetComment( 2 ).ToUTF8() );
    response.set_comment4( block.GetComment( 3 ).ToUTF8() );
    response.set_comment5( block.GetComment( 4 ).ToUTF8() );
    response.set_comment6( block.GetComment( 5 ).ToUTF8() );
    response.set_comment7( block.GetComment( 6 ).ToUTF8() );
    response.set_comment8( block.GetComment( 7 ).ToUTF8() );
    response.set_comment9( block.GetComment( 8 ).ToUTF8() );
 
    return response;
}
 
 
HANDLER_RESULT<google::protobuf::Empty>
API_HANDLER_EDITOR::handleSetTitleBlockInfo( const HANDLER_CONTEXT<SetTitleBlockInfo>& aCtx )
{
    HANDLER_RESULT<bool> documentValidation = validateDocument( aCtx.Request.document() );
 
    if( !documentValidation )
        return tl::unexpected( documentValidation.error() );
 
    if( !aCtx.Request.has_title_block() )
    {
        ApiResponseStatus e;
        e.set_status( ApiStatusCode::AS_BAD_REQUEST );
        e.set_error_message( "SetTitleBlockInfo requires title_block" );
        return tl::unexpected( e );
    }
 
    std::optional<TITLE_BLOCK*> optBlock = getTitleBlock();
 
    if( !optBlock )
    {
        ApiResponseStatus e;
        e.set_status( AS_BAD_REQUEST );
        e.set_error_message( "this editor does not support a title block" );
        return tl::unexpected( e );
    }
 
    TITLE_BLOCK& block = **optBlock;
 
    const types::TitleBlockInfo& request = aCtx.Request.title_block();
 
    block.SetTitle( wxString::FromUTF8( request.title() ) );
    block.SetDate( wxString::FromUTF8( request.date() ) );
    block.SetRevision( wxString::FromUTF8( request.revision() ) );
    block.SetCompany( wxString::FromUTF8( request.company() ) );
    block.SetComment( 0, wxString::FromUTF8( request.comment1() ) );
    block.SetComment( 1, wxString::FromUTF8( request.comment2() ) );
    block.SetComment( 2, wxString::FromUTF8( request.comment3() ) );
    block.SetComment( 3, wxString::FromUTF8( request.comment4() ) );
    block.SetComment( 4, wxString::FromUTF8( request.comment5() ) );
    block.SetComment( 5, wxString::FromUTF8( request.comment6() ) );
    block.SetComment( 6, wxString::FromUTF8( request.comment7() ) );
    block.SetComment( 7, wxString::FromUTF8( request.comment8() ) );
    block.SetComment( 8, wxString::FromUTF8( request.comment9() ) );
 
    onModified();
 
    return google::protobuf::Empty();
}
 
 
HANDLER_RESULT<types::PageSettings> API_HANDLER_EDITOR::handleGetPageSettings(
        const HANDLER_CONTEXT<commands::GetPageSettings>& aCtx)
{
    HANDLER_RESULT<bool> documentValidation = validateDocument( aCtx.Request.document() );
 
    if( !documentValidation )
        return tl::unexpected( documentValidation.error() );
 
    std::optional<PAGE_INFO> optPageInfo = getPageSettings();
 
    if( !optPageInfo )
    {
        ApiResponseStatus e;
        e.set_status( AS_BAD_REQUEST );
        e.set_error_message( "this editor does not support page settings" );
        return tl::unexpected( e );
    }
 
    PAGE_INFO& pageInfo = *optPageInfo;
 
    types::PageSettings response;
    response.set_page_size( ToProtoEnum<PAGE_SIZE_TYPE, types::PageSize>( pageInfo.GetType() ) );
 
    if( pageInfo.IsCustom() )
        PackVector2( *response.mutable_user_page_size(), pageInfo.GetSizeIU( pcbIUScale.IU_PER_MILS ) );
 
    response.set_orientation( pageInfo.IsPortrait() ? types::PageOrientation::PO_PORTRAIT
                                                    : types::PageOrientation::PO_LANDSCAPE );
    response.set_drawing_sheet( getDrawingSheetFileName().ToUTF8() );
 
    return response;
}
 
 
HANDLER_RESULT<types::PageSettings> API_HANDLER_EDITOR::handleSetPageSettings(
        const HANDLER_CONTEXT<commands::SetPageSettings>& aCtx )
{
    HANDLER_RESULT<bool> documentValidation = validateDocument( aCtx.Request.document() );
 
    if( !documentValidation )
        return tl::unexpected( documentValidation.error() );
 
    if( !aCtx.Request.has_page_settings() )
    {
        ApiResponseStatus e;
        e.set_status( ApiStatusCode::AS_BAD_REQUEST );
        e.set_error_message( "SetPageSettings requires page_settings" );
        return tl::unexpected( e );
    }
 
    std::optional<PAGE_INFO> optPageInfo = getPageSettings();
 
    if( !optPageInfo )
    {
        ApiResponseStatus e;
        e.set_status( AS_BAD_REQUEST );
        e.set_error_message( "this editor does not support page settings" );
        return tl::unexpected( e );
    }
 
    const types::PageSettings& request = aCtx.Request.page_settings();
 
    PAGE_INFO pageInfo = *optPageInfo;
    PAGE_SIZE_TYPE pageSizeType = FromProtoEnum<PAGE_SIZE_TYPE>( request.page_size() );
 
    if( pageSizeType == PAGE_SIZE_TYPE::User )
    {
        if( !request.has_user_page_size() )
        {
            ApiResponseStatus e;
            e.set_status( ApiStatusCode::AS_BAD_REQUEST );
            e.set_error_message( "custom page size requires user_page_size" );
            return tl::unexpected( e );
        }
 
        VECTOR2D sizeIu = UnpackVector2( request.user_page_size() );
        PAGE_INFO::SetCustomWidthMils( pcbIUScale.IUToMils( sizeIu.x ) );
        PAGE_INFO::SetCustomHeightMils( pcbIUScale.IUToMils( sizeIu.y ) );
 
        pageInfo.SetType( PAGE_SIZE_TYPE::User );
    }
    else
    {
        bool portrait = ( request.orientation() == types::PageOrientation::PO_PORTRAIT );
        pageInfo.SetType( pageSizeType, portrait );
    }
 
    if( !setPageSettings( pageInfo ) )
    {
        ApiResponseStatus e;
        e.set_status( AS_BAD_REQUEST );
        e.set_error_message( "this editor does not support page settings" );
        return tl::unexpected( e );
    }
 
    wxString drawingSheet( wxString::FromUTF8( request.drawing_sheet() ) );
    setDrawingSheetFileName( drawingSheet );
 
    onModified();
 
    types::PageSettings response;
    response.set_page_size( ToProtoEnum<PAGE_SIZE_TYPE, types::PageSize>( pageInfo.GetType() ) );
 
    if( pageInfo.IsCustom() )
        PackVector2( *response.mutable_user_page_size(), pageInfo.GetSizeIU( pcbIUScale.IU_PER_MILS ) );
 
    response.set_orientation( pageInfo.IsPortrait() ? types::PageOrientation::PO_PORTRAIT
                                                    : types::PageOrientation::PO_LANDSCAPE );
    response.set_drawing_sheet( getDrawingSheetFileName().ToUTF8() );
 
    return response;
}