Dela via

Skapa avstämningar av portföljer

  • Artikel

Ett synkroniseringsverktyg ger Briefcase möjligheten att stämma av olika versioner av ett dokument.

Om avstämare för portföljer

En dokumentförsonare kombinerar olika indataversioner av ett dokument för att skapa en ny, enhetlig version av dokumentet. Du kan behöva skapa en dokumentförlikare för att stödja din typ av dokument. Den här översikten beskriver korthetsavstämningsverktyg och förklarar hur du skapar dem.

Följande ämnen diskuteras:

Försoning

Ett dokument är en samling med information som kan kopieras och ändras. Ett dokument har olika versioner om innehållet i minst två kopior av dokumentet skiljer sig. Avstämning genererar en enskild version av ett dokument från två eller flera initiala versioner. Vanligtvis är den avstämda versionen en kombination av information från de första versionerna med den senaste eller mest användbara informationen bevarad.

Avstämning initieras av Briefcase när den fastställer att två eller flera kopior av samma dokument är olika. Portföljen, som fungerar som initierare i den här kontexten, identifierar och startar portföljens avstämningsprogram kopplat till den angivna dokumenttypen. Stämmaren jämför dokumenten och avgör vilka delar av dokumenten som ska behållas. Vissa avstämare kan kräva användarinteraktion för att slutföra avstämningen. Andra kan slutföra avstämningen utan användarinteraktion. Avstämningsverktyget kan vara en del av ett program eller vara ett tillägg som implementeras som en DLL.

Vissa portföljavstämnare kan skapa rester. Rester är ett dokument som vanligtvis har samma filtyp som det ursprungliga dokumentet och som innehåller information som inte sparats i den sammanfogade versionen. Rester används vanligtvis för att ge författarna ett snabbt sätt att avgöra vilken information från deras ursprungliga dokument som inte finns i den slutliga sammanfogade versionen. Om en avstämningsmodul stöder rester skapar denna en rest för var och en av de ursprungliga versionerna av dokumentet. Rester skapas inte om inte initieraren begär dem.

Vissa avstämningsprogram samarbetar med Briefcase för att användaren ska kunna avsluta avstämningen. Det här är en viktig funktion för en användare som kan besluta att avstämningen inte ska fortsätta. En avstämningsenhet tillhandahåller vanligtvis ett avslutningsobjekt när avstämningen kräver användarinteraktion och kan ta lång tid. I vissa miljöer kan ett avstämningsverktyg tillåta partiell avstämning, vilket gör att en användare tillfälligt kan pausa avstämningen och återuppta den senare. Portföljen stöder dock för närvarande inte partiell avstämning.

Skapa en dokumentportföljavstämning

Du skapar en portföljavstämning genom att implementera avstämningsgränssnitten. Som minst implementerar en avstämare gränssnittet IReconcilableObject och IPersistStorage eller IPersistFile-gränssnittet. Som initierare avgör Briefcase när avstämning behövs och anropar metoden IReconcilableObject::Reconcile för att initiera avstämning.

Även om IReconcilableObject::Reconcile ger en omfattande uppsättning avstämningsfunktioner, utför en portföljförsonare endast minimal avstämning i de flesta fall. I synnerhet kräver Briefcase inte att avstämaren stöder generering av restprodukter eller avslutningsobjektet. Dessutom utför stämmaren en enda avstämning från topp till botten och får inte returnera värdet för REC_E_NOTCOMPLETE; det innebär att den inte bör försöka utföra någon partiell avstämning.

Portföljen innehåller gränssnittet IReconcileInitiator. Portföljavstämningsprogrammet kan använda metoden IReconcileInitiator::SetAbortCallback för att ange avslutningsobjektet. Portföljen använder inte versionsidentifierare och kan därför inte tillhandahålla tidigare versioner av ett dokument om en avstämare begär dem med hjälp av motsvarande metoder i IReconcileInitiator.

Portföljen skickas till IReconcilableObject::Reconcile filmonikers som representerar de versioner av dokumentet som ska stämmas av. Avstämningsprogram för portfölj får åtkomst till versionerna genom att använda antingen metoden IMoniker::BindToObject eller IMoniker::BindToStorage. Det senare är vanligtvis snabbare och rekommenderas. Synkroniseraren måste frigöra alla objekt eller lagringsutrymme som den binder till.

När portföljmöjligheten använder IMoniker::BindToStorage, binder den till lagring som antingen är platt lagring (en stream) eller OLE-definierad strukturerad lagring. Om reconciler förväntar sig platt lagring bör den använda IMoniker::BindToStorage för att begära IStream--gränssnittet. Om stämmaren förväntar sig strukturerad lagring bör den begära IStorage-gränssnittet. I båda fallen bör den begära skrivskyddad, direkt (ej transaktionsbaserad) åtkomst till lagringen, eftersom läs-/skrivåtkomst kanske inte är tillgänglig.

En minimal avstämning av portföljer tittar vanligtvis direkt på lagringen av de andra versionerna och hanterar inbäddade objekt på ett mycket primitivt sätt, till exempel genom att slå samman två versioner av objektet genom att inkludera båda versionerna i utdataversionen.

Initieraren lokaliserar den lämpliga portföljavstämningen genom att använda en delmängd av logiken som implementerats av GetClassFile-funktionen för att fastställa typen av en viss fil och söker sedan i registret efter den avstämningsklass som är associerad med den angivna filtypen. Briefcase, precis som andra Shell-komponenter, avgör typen av en fil enbart utifrån dess filändelse. För att Briefcase ska kunna anropa en avstämare för filen måste filens tillägg ha en registrerad filtyp. Du måste ange en registerpost i följande format när du installerar ditt avstämningsprogram.

CLSID
   {the file CLSID}
      Roles
         Reconciler
            (Default) = {the reconciler-classid}

Klassen måste vara snabbinläsning, måste utses _MULTIPLEUSE, och om inte marskalker tillhandahålls för avstämningsgränssnittet måste den vara en processerver (som finns i en DLL) i stället för en lokal server (implementerad i en .exe fil).

Användarinteraktion i avstämning

Ett portföljavstämningsverktyg bör försöka utföra avstämning utan att användare behöver interagera. Ju mer automatiserad avstämningen är, desto bättre blir användarens uppfattning om processen.

I vissa fall kan användarintervention vara värdefullt. Ett dokumentsystem kan till exempel kräva att en användare granskar ändringar innan den sammanfogade versionen av ett dokument godkänns eller kräver kommentarer från användaren som förklarar de ändringar som har gjorts. I dessa fall är initieraren, inte portföljens avstämningsperson, ansvarig för att fråga användaren och genomföra användarens instruktioner.

I andra fall kan användarintervention vara nödvändigt, till exempel när två versioner har redigerats på inkompatibla sätt. I sådana fall måste antingen initieraren eller portföljavstämnaren fråga användaren om instruktioner för hur konflikten ska lösas. I allmänhet kan ingen initierare förlita sig på att slutföra en avstämning utan att förvänta sig någon användarinteraktion. Integrationshanterare har däremot möjlighet att interagera med användaren för att lösa konflikter eller att låta initieraren göra det.

Avstämning av inbäddade objekt

När du stämmer av ett dokument kan själva portföljavstämningsprogrammet bli en initierare om det upptäcker ett inbäddat objekt av en typ som det inte kan stämma av. I det här fallet måste avstämaren rekursivt stämma av vart och ett av de inbäddade objekten och ta på sig alla ansvarsområden för en initierare.

För att utföra rekursionen läser portföljavstämaren objektet och frågar efter lämpligt gränssnitt. Hanteraren för objektet måste ha stöd för gränssnittet. Om någon metod i gränssnittet returnerar OLE_E_NOTRUNNING-värdet måste avstämaren köra objektet för att utföra åtgärden. Eftersom kod för inbäddade objekt inte alltid är tillgänglig måste en avstämare tillhandahålla en lösning för det här villkoret. Till exempel kan avstämaren innehålla både gamla och nya versioner av det inbäddade objektet i den avstämda versionen. Avstämaren får inte försöka stämma av mellan länkar.

Initieraren lagrar de dokumentversioner som sammanfogas. I många fall har initieraren åtkomst till lagringen av varje version och sparar resultatet av avstämning med liknande lagring. Ibland kan dock initieraren ha ett minnesinternt objekt som ingen beständiga version är tillgänglig för. Den här situationen kan inträffa när ett dokument som innehåller öppna inbäddade objekt måste stämmas av innan det sparas. I sådana fall sparar initieraren resultatet av avstämningen i den version som finns i minnet.

Initieraren använder gränssnittet IPersistStorage för att binda (läsa in) den sammanfogade versionen. Initieraren använder metoden IPersistStorage::Load om en första version redan har skapats och använder metoden IPersistStorage::InitNew för den ursprungliga versionen. När den sammanslagna versionen läses in använder initieraren QueryInterface för att hämta adressen till IReconcilableObject--gränssnittet. Det här gränssnittet ger initieraren åtkomst till lagringen av befintliga restprodukter och ger den ett sätt att skapa lagring för eventuella nya rester. Sedan dirigerar initieraren gränssnittet för att utföra avstämningen. Initieraren frågar faktiskt efter gränssnittet IPersistFile före IPersistStorage. Om samordnaren stöder IPersistFile, manipulerar initieraren repliken via IPersistFile-metoder i stället för IPersistStorage-metoderna. Detta tillåter avstämning av filer som inte lagras som sammansatta dokument.

När avstämningen är klar kan initieraren spara den sammanfogade versionen med hjälp av gränssnittet IPersistStorage eller IPersistFile. Under avstämningen skapar avstämningsprogrammet rester vid behov och skriver sina permanenta data till lagring. Om den sammanslagna versionen är en ström innehåller IStorage-gränssnittet som skickas till IPersistStorage::Load en ström med namnet "Contents" med dess lagringstillstånd inställt på STATEBITS_FLAT. (Du kan ange tillståndsbitarna med hjälp av metoden IStorage::Stat.) Efter sammanslagningen sparar initieraren den sammanslagna versionen genom att skriva data på ett lämpligt sätt. Den bör se till att STATEBITS_FLAT anges efter behov för lagringen.

Rester

Initieraren anger om den vill ha resthalter genom att ange pstgNewResidues parameter till en giltig adress när IReconcilableObject::Reconcile-metoden anropas. Om avstämaren inte stöder skapande av restprodukter måste den omedelbart returnera värdet REC_E_NORESIDUES, såvida inte parametern dwFlags anger RECONCILEF_NORESIDUESOK-värdet.

Avstämningsfunktionen returnerar restposter till initieraren genom att skapa nya lagringselement och kopiera dem till matrisen som pekas ut av pstgNewResidues. För strukturerade lagringsrester kopierar stämmaren ett IStorage--gränssnitt, och för flata lagringsrester kopieras antingen ett IStream- eller ett IStorage-gränssnitt med STATEBITS_FLAT flagguppsättning. Stämmaren använder IStorage för att skapa nödvändig lagring med hjälp av IStorage::CreateStream för att skapa platt lagring för en restmängd som är en ström och IStorage::CreateStorage för att skapa strukturerad lagring.

Initieraren förbereder pstgNewResidues så att den inte innehåller några element i den icke-reserverade delen av IStorage namnområde. Avstämningsverktyget för portföljer placerar varje resterande post i ett element vars namn följer ordningen av dess ursprungliga version. Till exempel finns den första restmängden i "1", den andra i "2" och så vidare. Om själva det avstämda objektet genererar en resthalt, hittas det i elementet med namnet "0".

Varje nytt element som skapats av avstämningsprogrammet för portföljen behandlas individuellt, vilket säkerställer att initieraren har tillgång till informationen. Stämmaren förbinder emellertid inte pstgNewResidues sig själv. Initieraren ansvarar för att genomföra detta eller på annat sätt göra sig av med det.

Referens för avstämning av Briefcase

Det här avsnittet innehåller information om avstämningsgränssnitten. Vid hantering av fel kan en metod endast returnera de felvärden som uttryckligen definieras som möjliga returvärden. Dessutom måste metoden ange alla variabler vars adresser skickas som parametrar till NULL- innan de returneras från felet.

Gränssnitt och metoder för avstämningsverktyg för portföljer